KSA ZATCA Phase 2 E-Invoicing

Saudi e-invoicing stopped being a print-layout exercise the moment Phase 2 started. Under the Integration Phase, a standard tax invoice issued to a business customer has to be cleared by the tax authority before it can legally be handed to the buyer, and a simplified invoice issued to a consumer has to be reported within twenty-four hours. Each document must carry a UUID, an invoice hash, the hash of the previous document in the chain, a sequential counter, a cryptographic stamp produced with a certificate issued against your own taxpayer credentials, and a base64 TLV QR code containing the mandated tags. The chain has to be unbroken, per device or per solution unit, for the life of the system.

SAP Business One does not do any of that out of the box. Most Saudi customers discover the gap when a wave notification arrives: the Phase 1 work they did produces a QR code and a compliant layout, and nothing else. What is needed next is a build with a deadline attached to it.

What ECOSIRE builds

ECOSIRE builds a ZATCA Phase 2 integration for your company database as a SAP Business One add-on and companion service. Documents are read and updated through the Service Layer and DI API, all new data lives in user-defined fields, tables and objects, and the printed output is a Crystal Reports layout you can keep maintaining after we hand over.

Onboarding and certificates

The add-on generates the certificate signing request with the attributes ZATCA expects for your organisation, exchanges the one-time password from the taxpayer portal for a compliance certificate, runs the compliance checks required against sample documents, and then requests the production certificate. Private keys and certificates are stored inside your environment, scoped per company database and per solution unit, and never leave it. Renewal is a documented procedure rather than a phone call to us.

Document generation

A/R Invoices (OINV), A/R Credit Memos (ORIN) and A/R Down Payment Invoices (ODPI) are rendered as UBL 2.1 XML in the standard or simplified profile, chosen from the buyer classification on the Business Partner. The generator maps the mandated fields explicitly: seller and buyer VAT registration numbers from OCRD and OADM, the additional buyer identification scheme where the buyer is not VAT registered, invoice type code and transaction type flags, supply date and supply end date, line-level VAT category, rate and exemption reason code, allowance and charge blocks, prepayment references, and the billing reference that ties a credit note back to the invoice it corrects.

Stamping, hashing and the invoice chain

Each document is canonicalised, hashed with SHA-256, and signed. The previous invoice hash and the incremental counter value are maintained in a user-defined table with a locking strategy that survives multiple users adding documents at the same time, because a chain that skips or repeats a counter is a compliance failure that only surfaces later. The signature, hash, counter, UUID and QR payload are written back to user-defined fields on the marketing document so the values are visible to any user and exportable to any auditor.

Clearance and reporting

Standard invoices are submitted for clearance synchronously; the cleared XML returned by the authority becomes the legal document, and printing is blocked until clearance succeeds so nobody hands a customer an uncleared invoice. Simplified invoices are reported asynchronously within the twenty-four hour window, individually or in scheduled batches sized for your volume. Cleared-with-warnings responses are captured and shown rather than swallowed, because warnings today are frequently rejections after the next rule update.

Validation before the document is added

Most rejections come from master data, not from the integration. A pre-flight validation runs while the document is still open: buyer VAT number format and check digits, the national or commercial registration identifier where required, the full address block including building number, street, district, city and postal code, item tax category and exemption reason pairing, and rounding consistency between line VAT and header VAT. Failures surface as SAP messages against the offending field, and an approval procedure can block the document from being added at all, which is far cheaper than cancelling a cleared invoice.

Print layout, archive and audit

A bilingual Arabic and English Crystal Reports layout renders the printed and PDF invoice with the QR code and every mandated field. Signed XML is archived per document alongside the cleared response, attached to the document through the standard attachments mechanism and written to a retention folder you nominate. A user-defined object cockpit lists every submission with its status, the exact request and response payloads, and a resubmission action for documents that failed for a fixable reason.

Architecture and compatibility

Built against SAP Business One 10.0 on Microsoft SQL Server and on SAP HANA, on-premise or cloud-hosted. All extensibility uses UDFs, UDTs and UDOs; no core table is altered and no document is written straight to the database behind the application layer, so approval procedures, authorisations and posting rules keep working. The service supports the sandbox, simulation and production environments so you can rehearse the full flow before your wave date.

Who this is for

VAT-registered businesses in Saudi Arabia running SAP Business One who have received a ZATCA wave notification, or who expect one and want the work done before it arrives. It fits both B2B sellers whose volume is mostly standard invoices requiring clearance, and B2C or mixed businesses issuing simplified invoices at counter speed. Groups running several company databases can have the same solution deployed per company with its own certificates and chains.

How delivery works

1. Scoping call. We review your document types, buyer mix, branch and device structure, existing Phase 1 layout, wave date, and how many company databases are in scope. 2. Fixed quote. A written scope and fixed price, issued before any build work starts, with the wave date stated as the delivery constraint it is. 3. Build. Typically one working week depending on scope, against a copy of your company database. 4. Install in test. Deployed into your test company and run end to end against the ZATCA sandbox and simulation environments, including the compliance document set. You sign off on real document types before production. 5. Install in production. Production certificate onboarding, cutover with the chain initialised correctly, and a supervised first day of live clearance and reporting. 6. Support. A defect warranty window plus an optional support plan, which matters here because the authority publishes rule updates.

Honest boundaries

This is build-to-order. Nothing is pre-built, there is no instant download and no free trial. ECOSIRE is not a certified or accredited e-invoicing provider and does not act as your tax agent - certificates are issued against your own taxpayer credentials and you remain the taxpayer of record. We build, install and support the integration; the compliance obligation stays yours, and we will tell you plainly during scoping if your master data or document practices are the real blocker.