ZATCA or Fatoora Environments and APIs to submit e-invoices

tags

Sandbox, ZATCA complaint e-invoicing system

ZATCA #

URL

API #

ZATCA APIs ref Evernote

APIs to send the invoicing data to #

https://sandbox.zatca.gov.sa/IntegrationSandbox

There are APIs are related to:

Reporting (B2C) #

• the invoice (B2C only) ref
• To submit every simplified invoice using this API within 24 hours of generation.
• Reports a single SIMPLIFIED invoice, credit note, or debit note. Specifically, it accepts simplified Invoice, credit note, or debit note encoded in base64 and validates it to ensure:

  1. Compliance to the UBL 2 and XSD.

  2. EN 16931 Rules set.

  3. KSA Specific Rules set.

  4. KSA Rules set will override EN 16931 Rules set in case the same rule exists in both sets.

  5. QR Code validation

  6. Cryptographical Stamp validation

  7. Previous Invoice Hash Validation (PIH)

Clearance (B2B) #

• of an invoice (B2B invoice only) Clearance means ZATCA will check whether the invoice is complaint to be created and shared the buyer. The api returns an XML with signed cryptographic stamp from ZATCA to prove that it is verified.
  • Should happen in real time.

CCSID #

PCSID #

Onboarding #

Renewal #

• Renews an X509 Certificate (CSID) based on submitted CSR

Compliance Check #

It performs compliance checks on einvoice documents such as:

1. Standard invoice.
2. Standard debit note.
3. Standard credit note.
4. Simplified Invoice.
5. Simplified credit note.
6. Simplified debit note.

Except the CSID API all the other APIs take base64 of XML invoice along with UUID in post method.

Available Environments #

ref Simulation and Production Envs

Difference between Sandbox, Simulation and Produciton Environments Base URLs:

• https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal
• https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation
• https://gw-fatoora.zatca.gov.sa/e-invoicing/core

Simulation #

Onboarding API’s #

• API endpoints for Fatoora Simulation Portal

  Onboarding API’s

  • https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/compliance (Request a pre-compliance CSID)
  • https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/compliance/invoices (Run compliance checks for reporting and clearance)
  • https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/production/csids (Request or renew a production CSID)

Core Solution API’s #

• https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/invoices/reporting/single (Reporting API for Invoices, Credit and Debit notes)
• https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/invoices/clearance/single (Clearance API for Invoices, Credit and Debit notes)

• For further details on how to use APIs, please visit the Developer Portal

Sandbox #

Onboarding API’s

• API endpoints for Fatoora Simulation Portal

Onboarding API’s #

• https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/compliance (Request a pre-compliance CSID)
• https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/compliance/invoices (Run compliance checks for reporting and clearance)
• https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/production/csids (Request or renew a production CSID)

Core Solution API’s #

• https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/invoices/reporting/single (Reporting API for Invoices, Credit and Debit notes)
• https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/invoices/clearance/single (Clearance API for Invoices, Credit and Debit notes)

• For further details on how to use APIs, please visit the Developer Portal

Production #

API endpoints for Fatoora

Onboarding API’s #

• https://gw-fatoora.zatca.gov.sa/e-invoicing/core/compliance (Request a pre-compliance CSID)
• https://gw-fatoora.zatca.gov.sa/e-invoicing/core/compliance/invoices (Run compliance checks for reporting and clearance)
• https://gw-fatoora.zatca.gov.sa/e-invoicing/core/production/csids (Request or renew a production CSID)

Core Solution API’s #

• https://gw-fatoora.zatca.gov.sa/e-invoicing/core/invoices/reporting/single (Reporting API for Invoices, Credit and Debit notes)
• https://gw-fatoora.zatca.gov.sa/e-invoicing/core/invoices/clearance/single (Clearance API for Invoices, Credit and Debit notes)

For further details on how to use APIs, please visit the Developer Portal

Production APIs and URLs #

zatca forum

A. FATOORA portal (production)

● Onboarding APIs: https://gw-fatoora.zatca.gov.sa/e-invoicing/core/compliance 7 (Request a pre-compliance CSID) https://gw-fatoora.zatca.gov.sa/e-invoicing/core/compliance/invoices 6 (Run compliance checks for reporting and clearance) https://gw-fatoora.zatca.gov.sa/e-invoicing/core/production/csids (Request or renew a production CSID)

● Core Solution APIs: https://gw-fatoora.zatca.gov.sa/e-invoicing/core/invoices/reporting/single 3 (Reporting API for Invoices, Credit and Debit notes) https://gw-fatoora.zatca.gov.sa/e-invoicing/core/invoices/clearance/single 2 (Clearance API for Invoices, Credit and Debit notes)

B. FATOORA Simulation portal ● Onboarding APIs: https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/compliance 5 (Request a pre-compliance CSID) https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/compliance/invoices 2 (Run compliance checks for reporting and clearance) https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/production/csids 1 (Request or renew a production CSID)

● Core Solution APIs: https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/invoices/reporting/single 2 (Reporting API for Invoices, Credit and Debit notes) https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/invoices/clearance/single 4 (Clearance API for Invoices, Credit and Debit notes)

● Note, since FATOORA Simulation portal is an independent environment when generating the CSR value, on the CSR Configuration use below values:

● For FATOORA Portal a. Openssl: certificateTemplateName = ASN1:PRINTABLESTRING:ZATCA-Code-Signing b. Fatoora command: default value

● For FATOORA Simulation Portal a. Use openssl with certificateTemplateName = ASN1:PRINTABLESTRING:PREZATCA- Code-Signing