Zatca E-Invoicing APIs

Welcome to Complyance.io Zatca E-invoicing API Documentation!

The Kingdom of Saudi Arabia's Zakat, Tax and Customs Authority (ZATCA) has introduced e-invoicing to streamline the business processes and ensure tax compliance. To help businesses integrate this system seamlessly, Antna provides a comprehensive API solution. Let's delve into the features and functionalities of the Antna's ZATCA E-Invoicing API.

Getting Started with Antna's API:

Before diving into the API calls, it's essential to understand the foundation. Antna's API is designed around the REST architecture, accepting JSON-encoded body requests and returning data in the same format. To begin, users need to register with Antna and create an account. Once registered, they can utilize the API's features completely.

Compliance API - Antna APIs for ZATCA E-Invoicing (1.0.0)

This document is your go-to resource for comprehending and implementing our APIs seamlessly. Specifically tailored for both developers and Antna users, these APIs unlock the full potential of your Antna account's ZATCA features.

Here's what you'll find in this document:

1. API Overview: We've compiled a list of all our APIs, detailing their essential parameters and providing example requests and responses for your convenience.
2. Getting Started: The easiest way to dive into Antna's APIs is to click the "Run in Postman" button above. Postman, a free developer tool, simplifies the process of running and debugging API requests.
3. Technical Insight: Our APIs adhere to REST architecture and employ standard HTTP request methods. They accept JSON-encoded body requests and return data in the same format.

Ready to get started? Explore the sections below to streamline your integration with Antna's ZATCA E-Invoicing APIs.

API Workflows:

API workflows are predefined sequences of API calls and actions that help automate specific processes or tasks within an application or system. In the context of E-Invoicing, there are two workflows mentioned:

1. B2C Tax Document Flow:

• This workflow likely pertains to Business-to-Consumer (B2C) transactions involving tax documents. It outlines the series of API calls and operations needed to manage tax-related documents in scenarios where a business is interacting directly with individual consumers.

2. B2B Tax Document Flow:

• Conversely, the B2B Tax Document Flow pertains to Business-to-Business (B2B) transactions involving tax documents. This workflow defines the sequence of API interactions and steps necessary to handle tax-related documents in situations where businesses are transacting with other businesses.

Each of these workflows would consist of a set of API endpoints, data handling procedures, and potentially authentication and authorization steps, all designed to facilitate the specific tax-related processes involved in either B2C or B2B contexts. These workflows serve as guides for developers and system integrators, ensuring that the right API calls are made in the correct sequence to achieve the desired outcome when dealing with tax-related documents.

Getting Started

To begin, you'll need to register with Antna and create an account. Follow these simple steps:

1. Click on this link.
2. Refer to this video for a step-by-step guide on completing the sign-up process.

Document and API Usage Guidelines

Our APIs operate using fundamental HTTP request methods: POST, GET, PATCH, and PUT.

You can easily select your preferred request and response code language by choosing it from the dropdown menu at the top.

For seamless testing and integration, you can import and evaluate our entire API collection within the Postman app by clicking the 'Run in Postman' button.

Please take note: Any requests made with valid API credentials will directly impact real-time data in your Antna account.

Authorization: accessToken

All our APIs come with corresponding example requests and responses, covering both successful and unsuccessful calls. Here's what each definition means:

• Successful Call: The API request was executed correctly.
• Invalid Data: The data provided in the request was incorrect.
• Missing Fields: Some of the necessary fields in the request are absent.
• Wrong Format: There's a syntax error in the code.

This user-friendly guide will help you get started with Antna's services and make the most out of our APIs.

Error Codes and What They Mean

While using Antna's APIs, you might come across several response codes. Each code signifies a specific status of your request:

1. 200 & 202 - OK & Accepted
   • Everything went smoothly, and you can expect a response. If there's an issue with the data, some APIs may return an error message.
2. 400 - Bad Request
   • Your request isn't quite right. It could be invalid or unsuitable for processing. Double-check your provided data.
3. 401 - Unauthorized
   • There's an issue with validation. This typically indicates a problem with your access token or credentials. Verify that they are correct.
4. 404 - Not Found
   • The requested URI is invalid, or the resource you're seeking doesn't exist. Verify your request URL.
5. 429 - Too Many Requests
   • Slow down! You've exceeded the API call rate limit. Wait a bit before making more requests.
6. 500, 502, 503, 504 - Server Errors
   • Server-side problems have occurred. These could be due to syntax errors or incorrect request parameters. If this persists, contact our support team for help.

Support:

For assistance with Antna's APIs:

• Integration Information: Thoroughly review this documentation for integration details.
• API-related Support: If you encounter API-specific issues, reach out to us at support@antna.co.in, and we'll respond promptly.
• Other Issues: For any other problems or inquiries, contact us at support@antna.co.in.

Ensure you also review our Terms of Service for comprehensive policies and guidelines.

ZATCA Integration APIs:

Within this directory, you'll find a collection of APIs essential for aligning your application with ZATCA compliance.

To access these APIs, an OAuth 2.0 Token header is mandatory for authorization. To acquire the OAuth Access Token for testing purposes, simply sign in through Postman.

When transitioning to the production environment, we will furnish an Authorization API for obtaining both the access token and refresh token.

As a security measure, please note that API sign-in remains disabled in our test environment.

Before proceeding with API testing, it's essential to ensure that you have the necessary tools and accounts set up. Here's a step-by-step guide to help you get started with API testing using Postman:

Step 1: Install Postman (if not already installed)

• If you haven't installed Postman, you can download and install it from the official Postman website.

Step 2: Create a Free Postman Account

• Open Postman after installation.
• Click on the "Sign In / Sign Up" button in the top-right corner.
• Select "Sign Up for Free" to create a free Postman account.

Step 3: Verify Your Email

• After signing up, you'll receive an email from Postman to verify your email address. Click on the verification link in the email to confirm your account.

Step 4: Log In to Postman

• Once your email is verified, return to Postman and log in using the credentials you provided during sign-up.

Step 5: Set Up Postman for API Testing

• Postman is now ready for use. You can start creating and running API tests.

Import or Create Requests

You can access Complyance API Docs within our forked collection, making it effortless to start using our Zatca APIs. Just click the "Run in Postman" button, and you'll have immediate access to all the API resources and endpoints, simplifying the integration process.

Click on the "Run in Postman" button, and after being redirected to the link, simply select "fork collection" to gain access to our Complyance API Docs and facilitate your integration with Zatca APIs.

After forking the collection, you'll have access to all of ZATCA's APIs through our Complyance API Docs.

By following these steps, you'll be ready to perform API testing using Postman. Make sure to refer to the API documentation for the specific API you want to test to understand the endpoints, authentication requirements, and expected responses.

Let's begin our journey into Zatca API onboarding with Postman testing.

Sign Up

API Description:Use this API to create an account in Antna's test environment, granting access to ZATCA APIs for onboarding, reporting, and clearing.

Request Parameters:

• email (Required): Your email for account creation, e.g., example123@example.com.
• password (Required): Password for your Antna test account. Must include at least one capital letter, one special character, and one number. E.g., Example@123.

Response Parameters:

• refreshToken: A permanent token, valid for one year. Securely save it for acquiring a temporary accessToken every 24 hours.

• After you've filled in the necessary data, which typically includes your email and password, make sure everything is accurately entered.
• Now, it's time to proceed by clicking on the "Send" button within Postman. This action will initiate the API request.
• Postman will take care of sending the request to the designated API endpoint. You can monitor the process in the interface.
• As the request reaches the server, Postman will await the response. Once received, the server will provide a response, and Postman will promptly display it.
• In the response, you may receive valuable data, including a "refreshToken." This token is often crucial for maintaining authentication and session management with the API. Make sure to securely store this token for future use.

Request Sample:

{
  "email": "example562234@gmail.com",
  "password": "Example@123"
}

Response Sample:

{
  "refreshToken": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ..."
}

Carefully review the response to confirm the success of your API request. Look for a status code (commonly 200 OK for success) and verify that the refreshToken and any other expected data are present.

Sign In

• With the successful completion of the sign-up process and the reception of your valuable refreshToken, you're now ready to proceed to the next step: the sign-in API request.
• Begin by opening a new request in Postman, ensuring that you've selected the appropriate HTTP method, which is usually "POST" for signing in.
• In the request body, include the necessary information, typically your email and password, along with the refreshToken obtained earlier. This refreshToken serves as a key to maintain your authenticated session.
• Once you've filled in the required data, confirm that everything is accurate and ready for submission.
• Now, it's time to trigger the API request by clicking on the "Send" button within Postman.
• As before, Postman will diligently handle the request, sending it securely to the designated API endpoint.

Request Samples:

• Payload:

{
  "refreshToken": ""
}

• Response Samples:
  • Success

{
  "accessToken": ""
}

This API allows you to log in to your Antna account and obtain an access token for accessing other Antna APIs. You need to provide your refresh token to get the access token, which is valid for one day.

Carefully examine the response to ensure the success of your API request. Look for the status code, which should typically be "200 OK" for a successful sign-in.

Onboarding API

Once you've completed the signup and sign-in processes and successfully acquired the AccessToken, it's time to proceed with onboarding. This API facilitates the onboarding of your E-Invoice Generation Solution (EGS) in the ZATCA sandbox environment. Ensure you supply the necessary parameters in the specified format, and feel free to include any additional parameters that suit your specific requirements.

I can provide a complete explanation of the Onboarding API along with JSON data samples for better understanding. Here's the information presented in a tabular format:

• Use this API to onboard your EGS (E-Invoice Generation Solution) in the ZATCA sandbox environment.
• You need to provide all the required parameters in the specified format at a minimum to successfully onboard your EGS. Additional parameters can be added as per your preference.

<aside>💡 Simply copy the received AccessToken and head to the top of the Zatca File. Click on "Authorization" and paste the AccessToken in the current Token field

</aside>

Upon sending the request, you will receive the following message: For example "Your EGS with serial number - '1-TST|2-TST|3-ed22f1d8-e6a2-1118-9b58-d9a8f11e44yt' has been successfully onboarded with ZATCA!”

<aside>💡 You can view all the details in the response body section.

</aside>

Request Sample:

{
  "csrInputs": {
    "otp": "123345",
    "commonName": "TST-886431145-300055184400003",
    "serialNumber": "1-TST 2-TST 3-ed22f1d8-e6a2-1118-9b58-d9a8f11e44yt",
    "organizationIdentifier": "300055184400003",
    "organizationUnitName": "Riyadh",
    "organizationName": "Antna Technologies",
    "countryName": "SA",
    "invoiceType": "1100",
    "location": "Riyadh",
    "industry": "Petroleum"
  }
}

• csrInputs: This is the main object containing all the parameters required for onboarding.
  • otp: The One-Time Password received from the Fatoora Portal.
  • commonName: A unique name or asset tracking number for your EGS.
  • serialNumber: A unique identification code for the EGS in a specific format.
  • organizationIdentifier: The organization VAT number.
  • organizationUnitName: The branch name for taxpayers or the 10-digit TIN number for VAT Groups.
  • organizationName: The name of the taxpayer or organization.
  • countryName: The name of the country in 2-letter code (ISO 3166 Alpha-2).
  • invoiceType: The document type(s) your solution will be generating.
  • location: The address of the branch or location where the device or solution unit is situated.
  • industry: The industry or sector for which the device or solution (EGS) will generate invoices.

These parameters are sent in the request body to initiate the onboarding process for your EGS in the ZATCA sandbox environment. The response will indicate whether the onboarding was successful ("status": "SUCCESS") or if there were errors ("status": "ERROR"), along with additional details about any errors encountered.

Response Sample (Success):

{
  "status": "SUCCESS",
  "errors": []
}

here's an explanation of the response parameters for the Onboarding API in the previous format:

• status (string): This parameter indicates the status of the onboarding process by ZATCA. It's a high-level summary of whether the onboarding was successful or not. It has two possible enum values:
  • SUCCESS: Indicates that the onboarding process was successfully completed with ZATCA's Fatoora Portal.
  • ERROR: Indicates that the onboarding failed with ZATCA's Fatoora Portal due to various errors.
• errors (list): If the onboarding fails due to errors originating from the APIs in the ZATCA layer, this parameter will contain the corresponding API error messages. It's a list that may include detailed information about what went wrong. Developers are advised to log this error response for further analysis and Root Cause Analysis (RCA).
• code (string): This parameter represents the error status code of the failed ZATCA API. It provides additional information about the nature of the error. For example, if the error is related to a bad request, the code might be 400 BAD_REQUEST.
• message (string): This parameter provides a human-readable error message associated with the corresponding API error. It offers a brief explanation of why the error occurred. For example, it might indicate that the OTP (One-Time Password) is a required field.

These response parameters help developers understand the outcome of the onboarding process and diagnose any issues that may have occurred during the API call.

This API allows you to onboard your EGS in the ZATCA sandbox environment with the required parameters, and it provides feedback on the onboarding status.

QR Code Generation for Simplified Invoices

First, navigate to the Body section and review all the parameters. Once you've reviewed them, send the request. If the request is successful, you will receive a response.

<aside>💡 However, if you encounter an error, make sure to change the document ID and choose one of the following document types for the "documentType" parameter: TAX_INVOICE, SIMPLIFIED_TAX_INVOICE, TAX_INVOICE_CREDIT_NOTE, TAX_INVOICE_DEBIT_NOTE, SIMPLIFIED_TAX_INVOICE_CREDIT_NOTE, SIMPLIFIED_TAX_INVOICE_DEBIT_NOTE, ESTIMATE, or ALL. Then, resend the request.

</aside>

This API allows you to create a secure and cryptographically signed base64 encoded QR code. It's designed for your EGS (E-Invoice Generation Solution) to generate QR codes for specific B2C documents such as Simplified Tax Invoices, Simplified Tax Invoice Credit Notes, or Simplified Tax Invoice Debit Notes, which are meant for submission to ZATCA's sandbox environment.

To successfully report your document to ZATCA, it's crucial to provide all the necessary parameters in the specified format. You also have the flexibility to include additional parameters if needed.

Keep in mind that the generated base64 encoded QR code can be used to produce a scannable QR image for your documents.

Request Parameters:

Certainly, let's explain all the PARAMS (Request Parameters) for the QR Code (Simplified Invoice) API in detail:

1. invoiceData (Required - JSON): This parameter is the core of your request, containing essential information about your B2C (Business-to-Consumer) document. It consists of several sub-parameters:
   • documentType (Required - String): Type of the document. Use the corresponding enum value for your document type. Example: "SIMPLIFIED_TAX_INVOICE"
   • referenceId (Conditional - String): ID of the original document for credit or debit notes. This parameter is applicable only for document types like credit notes and debit notes. For example, if the document type is a credit note, the reference ID should be the invoice number for which this credit note is being created. Example: "2022100627"
   • documentIssueDateTime (Required - String): The date and time when the document was issued, in the format "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'". Example: "2022-10-21T12:53:13.000Z"
   • documentDueDateTime (Optional - String): The due date and time for the document, also in the format "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'". Use this if applicable. Example: "2022-10-21T12:53:13.000Z"
   • sellerName (Required - String): The name of the seller or your company. Example: "Company Name"
   • sellerAddress (Required - JSON): Seller's address details, including various sub-parameters such as addrLine1, addrLine2, additionalNo, buildingNumber, city, state, zipCode, district, and country. These fields describe the physical address of the seller.
   • buyerName (Conditional - String): The name of the buyer. This is mandatory for specific transactions as per the regulations. Example: "Vignesh K"
   • buyerAddress (Optional - JSON): Buyer's address details, similar to the seller's address, including fields like addrLine1, addrLine2, additionalNo, buildingNumber, city, state, zipCode, district, and country.
   • Other Fields: Depending on your document and specific requirements, there can be additional fields under invoiceData for individual line items. These include lineItemDesc, lineItemPrice, lineItemQty, lineItemTaxableAmount, discountOnLineItem, vatRateOnLineItem, and more.
2. totalExcludingVat (Required - Number): The total amount for all line items in the document, excluding VAT (Value Added Tax).
3. totalTaxableAmountExcludingVat (Required - Number): The total taxable amount for all line items in the document, excluding VAT.
4. vatTotal (Required - Number): The total VAT amount for all line items in the document.
5. documentTotal (Required - Number): The total document amount, which includes the total taxable amount and VAT.
6. discountOnDocumentTotal (Optional - Number): If any discount applies to the entire document total, you can provide the discount amount here.
7. isSpecialBillingAgreement (Required - Boolean): Indicates whether the transaction is under a special billing agreement. For example, it can be set to "false" for regular transactions.
8. isTransactionType (Required - Boolean): Indicates the type of transaction and can be set to "false" for regular transactions.
9. isSelfBilled (Required - Boolean): If isSpecialBillingAgreement is true and the self-billed condition applies, this parameter should be set to "false."
10. isThirdParty (Required - Boolean): If isSpecialBillingAgreement is true and the third-party billing condition applies, this parameter should be set to "true."
11. isNominalSupply (Required - Boolean): Indicates if the transaction is a nominal supply and can be set to "false."
12. isExport (Required - Boolean): Indicates if the transaction is an export and can be set to "false."
13. isSummary (Required - Boolean): Indicates if the transaction is a summary invoice and can be set to "false."
14. supplyDate (Required - String): Goods/Service supply date and time in the format "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'."
15. sellerVatRegistrationNumber (Required - String): The VAT registration number of the seller or your company. Example: "300055184400003"
16. additionalSellerIdType (Required - String): This parameter specifies the type of additional seller ID and should use corresponding enums like "CRN" for Commercial Registration Number. Example: "CRN"
17. additionalSellerIdNumber (Required - String): The additional seller ID number of the type specified in additionalSellerIdType. Example: "1112233344"
18. sellerGroupVatRegistrationNumber (Conditional - String): This parameter is used for group VAT registration of the seller and should be provided if applicable.
19. additionalBuyerIdType (Conditional - String): This parameter is required only for specific transactions, such as private education or private healthcare supplies to citizens. It should contain the buyer's ID type, e.g., "NATIONAL_ID."
20. additionalBuyerIdNumber (Conditional - String): The buyer's ID number, which corresponds to the type specified in additionalBuyerIdType. Example: "112233445566"
21. specialTaxTreatment (Conditional - String): If tax

is not charged at the standard rate, you can provide a narration explaining the tax treatment applied to the supply.

1. vatCurrency (Conditional - String): If the document currency is not "SAR" (Saudi Riyal), this parameter specifies the currency in which VAT should be accounted.
2. noteIssuanceReason (Conditional - String): This field is used to provide a reason for issuing a credit or debit note, as per Article 40 and Article 54 of KSA VAT regulations. Reasons can include cancellation of supplies, essential changes, value amendments, refunds, or changes in seller's or buyer's information.
3. currency (Required - String): The transaction currency of the document, usually "SAR" for Saudi Riyal.
4. documentId (Required - Number): A unique identification of the invoice, often referred to as Invoice Reference Number (IRN).

These parameters collectively form your request to generate a QR code for your B2C document. The API uses this data to create a base64 encoded QR code that can be used on your printed B2C document to comply with ZATCA regulations.

Response parameter:

let's explain the Response Parameters for the QR Code (Simplified Invoice) API:

1. encodedQrCodeData (String): This parameter contains a base64 encoded QR code string. This string is generated by the API and is used to create a QR image that can be printed on your B2C (Business-to-Consumer) documents.
   • DESCRIPTION: The encodedQrCodeData parameter holds the QR code data in a format that can be used to create a scannable QR image. It's a critical component for compliance with ZATCA regulations as it contains encoded information about the invoice.
   • EXAMPLE: The value of this parameter will be a long string of characters encoded in base64. For example: "AQxDb21wYW55IE5hbWUCDzMwMDA1NTE4..."

To comply with ZATCA regulations, you'll need to use this encodedQrCodeData string to generate a QR code image. This image can then be added to your B2C documents, enabling customers or tax authorities to scan and verify the invoice information as required by the regulations. It's important to note that this QR code is specifically intended for use on B2C documents.

The JSON format you provided is a request payload for making a POST request to the /test/api/v1/proto/generateQRCode endpoint. This request is intended to generate a QR code for an E-invoice document. Below is an explanation of the JSON format along with an example:

{
  "invoiceData": {
    "documentType": "SIMPLIFIED_TAX_INVOICE",
    "referenceId": "",
    "documentIssueDateTime": "2022-12-30T09:58:24.000Z",
    "documentDueDateTime": "2022-12-30T09:58:24.000Z",
    "sellerName": "ahmad abdurrahman",
    "sellerAddress": {},
    "buyerName": "Zahid Gani",
    "documentLineItems": [],
    "totalExcludingVat": 1112,
    "totalTaxableAmountExcludingVat": 1146,
    "vatTotal": 166.8,
    "documentTotal": 1278.8,
    "discountOnDocumentTotal": 34,
    "isSpecialBillingAgreement": "false",
    "isTransactionType": "false",
    "isSelfBilled": "false",
    "isThirdParty": "false",
    "isNominalSupply": "false",
    "isExport": "false",
    "isSummary": "false",
    "supplyDate": "2022-12-30T09:58:24.000Z",
    "sellerVatRegistrationNumber": "300055184400003",
    "sellerGroupVatRegistrationNumber": "",
    "additionalSellerIdType": "CRN",
    "additionalSellerIdNumber": "1112233344",
    "specialTaxTreatment": "0",
    "currency": "SAR",
    "documentId": "001"
  }
}

‍


Explanation:

• invoiceData: This object contains all the details of the E-invoice document.
• documentType: Specifies the type of document, in this case, "SIMPLIFIED_TAX_INVOICE."
• documentIssueDateTime and documentDueDateTime: The date and time of issue and due date for the document.
• sellerName and buyerName: Names of the seller and buyer.
• documentLineItems: An array of line items within the invoice.
• totalExcludingVat: The total amount excluding VAT.
• totalTaxableAmountExcludingVat: The total taxable amount excluding VAT.
• vatTotal: The total VAT amount.
• documentTotal: The total document amount.
• discountOnDocumentTotal: Any discount applied to the total document.
• Several boolean flags (isSpecialBillingAgreement, isTransactionType, etc.) indicate various conditions related to the transaction.
• supplyDate: Date and time of goods or service supply.
• sellerVatRegistrationNumber: VAT registration number of the seller.
• additionalSellerIdType and additionalSellerIdNumber: Additional seller identification information.
• specialTaxTreatment: Information about any special tax treatment.
• currency: Transaction currency.
• documentId: A unique identification of the invoice.

Example Response:

This JSON response contains the base64 encoded QR code data, which can be used to generate a scannable QR image for the printed B2C document. The encoded QR code data is provided in the encodedQrCodeData field.

The provided information pertains to the authorization and response details for making an HTTP request to the /test/api/v1/proto/generateQRCode endpoint. Let's break down what each part means:

AUTHORIZATIONS:

• oauth2Auth: This indicates that the authorization mechanism being used for this API endpoint is OAuth 2.0, a commonly used protocol for secure and delegated access.

HTTP:

• oauth2Auth: This section specifies the HTTP request method that should be used when making a request to this API endpoint. In this case, it's oauth2Auth, which is a custom or specific request method for OAuth 2.0 authorization.

HTTP Authorization Scheme:

• oauth2: This field specifies the type of authorization scheme being used, which is OAuth 2.0 in this case. OAuth 2.0 is an industry-standard protocol for token-based authorization.

REQUEST BODY SCHEMA:

• application/json object: This indicates that the request body of the HTTP request should adhere to the JSON format and structure defined for this API endpoint. The request body should be an object (in JSON format) that contains the necessary data for generating the QR code.

Responses:

• 200 OK: This is an HTTP status code that indicates a successful response. In other words, when the request to generate the QR code is successful, the server will respond with a status code of 200 OK.

RESPONSE HEADERS:

• These are HTTP response headers that provide metadata about the response from the server. Here are some of the important headers:
  • Date: Specifies the date and time when the response was generated.
  • Content-Type: Specifies the type of content in the response, which is application/json in this case, indicating that the response will be in JSON format.
  • Content-Length: Indicates the length (in bytes) of the response content.
  • Connection: Specifies the status of the connection between the client and the server.
  • x-amzn-RequestId: A unique identifier for the request, which can be useful for tracking and debugging.
  • Access-Control-Allow-Origin: This header indicates which origins are permitted to access this resource. An asterisk (``) means that any origin is allowed.
  • Access-Control-Allow-Headers: Specifies the allowed HTTP headers for cross-origin requests.
  • x-amz-apigw-id: A unique identifier for the Amazon API Gateway used for the request.
  • Access-Control-Allow-Methods: Specifies the HTTP methods that are allowed when accessing this resource from a different origin.
  • Access-Control-Expose-Headers: Lists which headers are exposed to the browser when the request's credentials mode is "include."
  • X-Amzn-Trace-Id: An Amazon Trace ID that can be useful for debugging and tracing requests.

RESPONSE SCHEMA:

• application/json object: This indicates that the response from the server will be in JSON format and should adhere to a specific structure defined for this API endpoint. It's an object in JSON format that contains the response data.

In summary, this information provides details about how to authorize the request (OAuth 2.0), what to include in the request body (JSON object), what to expect in the response (HTTP status code 200 OK, JSON response), and various response headers that provide additional information about the response and its handling.

Report Your Document

This API allows you to send your B2C documents (such as Simplified Tax Invoices, Credit Notes, or Debit Notes) generated by your E-Invoice Generation Solution to ZATCA's sandbox environment.

To make sure your document is reported successfully, you need to provide all the necessary information in a specific format. If needed, you can also include extra details according to your requirements.

This JSON response contains the base64 encoded QR code data, which can be used to generate a scannable QR image for the printed B2C document. The encoded QR code data is provided in the encodedQrCodeData field.

Request Parameters:

1. invoiceData (REQUIRED, json): Contains certificate signing request (CSR) details for onboarding the EGS (E-Invoice Generation Solution).
2. documentType (REQUIRED, string): Specifies the type of document. Use corresponding enums like SIMPLIFIED_TAX_INVOICE, SIMPLIFIED_TAX_INVOICE_CREDIT_NOTE, or SIMPLIFIED_TAX_INVOICE_DEBIT_NOTE.
3. referenceId (CONDITIONAL, string): ID of the original document (reference document) for which this document is generated. Applicable for Credit Notes and Debit Notes.
4. documentIssueDateTime (REQUIRED, string): Document Issue Date and Time in "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" format.
5. documentDueDateTime (OPTIONAL, string): Document Due Date and Time in the specified format.
6. sellerName (REQUIRED, string): Name of the seller.
7. sellerAddress (REQUIRED, json): Seller's address with fields like addrLine1, addrLine2, additionalNo, buildingNumber, city, state, zipCode, district, and country.
8. buyerName (CONDITIONAL, string): Mandatory for certain transactions, like those mentioned in Article 53(7) and for private education and healthcare to citizens.
9. buyerAddress (OPTIONAL, json): Buyer's address with similar address fields.
10. documentLineItems (REQUIRED, array): List of line items, each containing lineItemDesc, lineItemPrice, lineItemQty, discountOnLineItem, vatRateOnLineItem, and related calculations.
11. totalExcludingVat (REQUIRED, number): Total excluding VAT.
12. totalTaxableAmountExcludingVat (REQUIRED, number): Total taxable amount excluding VAT.
13. vatTotal (REQUIRED, number): Total VAT amount.
14. documentTotal (REQUIRED, number): Document total.
15. isSpecialBillingAgreement (REQUIRED, boolean): Indicates if it's a self-billed or third-party billed invoice under special conditions.
16. isTransactionType (REQUIRED, boolean): Indicates if it's a nominal supply, export, or summary.
17. isSelfBilled (REQUIRED, boolean): Applicable when isSpecialBillingAgreement is true and it's a self-billed condition.
18. isThirdParty (REQUIRED, boolean): Applicable when isSpecialBillingAgreement is true and it's a third-party billing condition.
19. isNominalSupply (REQUIRED, boolean): Applicable when isTransactionType is true and it's a nominal supply condition.
20. isExport (REQUIRED, boolean): Applicable when isTransactionType is true and it's an export condition.
21. isSummary (REQUIRED, boolean): Applicable when isTransactionType is true and it's a summary invoice condition.
22. supplyDate (REQUIRED, string): Goods/Service supply Date and Time in the specified format.
23. sellerVatRegistrationNumber (REQUIRED, string): Seller's VAT registration number.
24. additionalSellerIdType (REQUIRED, string): Type of additional seller ID, such as CRN or others.
25. additionalSellerIdNumber (REQUIRED, string): Additional seller ID number.
26. sellerGroupVatRegistrationNumber (CONDITIONAL, string): Group VAT registration number of the seller.
27. additionalBuyerIdType (CONDITIONAL, string): Required only for private education or private healthcare supplies to citizens, should contain the National ID.
28. additionalBuyerIdNumber (CONDITIONAL, string): Buyer's NATIONAL ID number.
29. discountOnDocumentTotal (OPTIONAL, number): Discount applied on the document total.
30. specialTaxTreatment (CONDITIONAL, string): Narration when tax is not charged at the standard rate, as per Article 53 of the VAT Implementing Regulation.
31. vatCurrency (CONDITIONAL, string): If the document currency is not "SAR," provide the VAT currency.
32. noteIssuanceReason (CONDITIONAL, string): Reason for issuing a credit/debit note.
33. currency (REQUIRED, string): Transaction currency of the document.
34. documentId (REQUIRED, number): Unique identification of the Invoice - Invoice Reference number (IRN).

Response Parameters:

1. isReported (boolean): Reporting status of the B2C document with ZATCA.
2. zatcaResponse (list): Proxy of ZATCA Reporting API response, populated for both success and failure scenarios.

The provided JSON data is a sample payload for a POST request to the /test/api/v1/proto/reportDocument endpoint. This request is used to report a document to ZATCA's sandbox environment. Here's an explanation of the JSON data:

{
  "invoiceData": {
    "documentType": "SIMPLIFIED_TAX_INVOICE",
    "referenceId": "",
    "documentIssueDateTime": "2022-12-30T09:58:24.000Z",
    "documentDueDateTime": "2022-12-30T09:58:24.000Z",
    "sellerName": "ahmad abdurrahman",
    "sellerAddress": {},
    "buyerName": "Zahid Gani",
    "documentLineItems": [],
    "totalExcludingVat": 1112,
    "totalTaxableAmountExcludingVat": 1146,
    "vatTotal": 166.8,
    "documentTotal": 1278.8,
    "discountOnDocumentTotal": 34,
    "isSpecialBillingAgreement": "false",
    "isTransactionType": "false",
    "isSelfBilled": "false",
    "isThirdParty": "false",
    "isNominalSupply": "false",
    "isExport": "false",
    "isSummary": "false",
    "supplyDate": "2022-12-30T09:58:24.000Z",
    "sellerVatRegistrationNumber": "300055184400003",
    "sellerGroupVatRegistrationNumber": "",
    "additionalSellerIdType": "CRN",
    "additionalSellerIdNumber": "1112233344",
    "specialTaxTreatment": "0",
    "currency": "SAR",
    "documentId": "001"
  }
}

Explanation:

• invoiceData: This is an object that contains all the details of the invoice or document being reported.
  • documentType: Specifies the type of document, in this case, it's a "SIMPLIFIED_TAX_INVOICE."
  • referenceId: This field is left empty in this example, but it can contain the ID of the original document (reference document) for which this document is generated. It's applicable for Credit Notes and Debit Notes.
  • documentIssueDateTime: Indicates the date and time when the document was issued, in the format "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'."
  • documentDueDateTime: Specifies the due date and time of the document.
  • sellerName: Name of the seller or company.
  • sellerAddress: An empty object here, but it typically contains the seller's address details.
  • buyerName: Name of the buyer.
  • documentLineItems: An empty array for line items; this is where you would include details of the products or services.
  • totalExcludingVat: The total amount excluding VAT.
  • totalTaxableAmountExcludingVat: The total taxable amount excluding VAT.
  • vatTotal: The total VAT amount.
  • documentTotal: The total document amount.
  • discountOnDocumentTotal: Any discount applied to the total document amount.
  • isSpecialBillingAgreement: Indicates if it's a special billing agreement.
  • isTransactionType: Indicates the transaction type.
  • isSelfBilled: Indicates if it's a self-billed condition.
  • isThirdParty: Indicates if it's a third-party billing condition.
  • isNominalSupply: Indicates if it's a nominal supply condition.
  • isExport: Indicates if it's an export condition.
  • isSummary: Indicates if it's a summary invoice condition.
  • supplyDate: Date and time of goods/service supply.
  • sellerVatRegistrationNumber: Seller's VAT registration number.
  • sellerGroupVatRegistrationNumber: Group VAT registration number of the seller.
  • additionalSellerIdType: Type of additional seller ID (e.g., CRN).
  • additionalSellerIdNumber: Additional seller ID number.
  • specialTaxTreatment: Tax treatment applied if not charged at the standard rate.
  • currency: Transaction currency of the document.
  • documentId: Unique identification of the invoice or document.

The response to this request is a JSON object that provides information about the reporting status:

{
  "zatcaResponse": {
    "validationResults": {},
    "reportingStatus": "REPORTED",
    "timestamp": 0,
    "status": 0
  },
  "isReported": true
}

Explanation:

• zatcaResponse: This object contains information related to the ZATCA reporting process.
  • validationResults: This object may contain validation results, such as information messages, warning messages, and error messages. In this example, it's empty.
  • reportingStatus: Indicates the reporting status, which is "REPORTED" in this case.
  • timestamp: A timestamp, which is set to 0 in this example.
  • status: A status code, which is set to 0 in this example.
• isReported: A boolean flag indicating whether the document was successfully reported. In this case, it's set to true, indicating successful reporting.

The provided information is about the authorization and response details for an API. Let's break it down into simpler terms:

• AUTHORIZATIONS: This section indicates how the API is authorized, which means how it checks if someone has permission to use it. In this case, it's using OAuth 2.0 for authorization.
• REQUEST BODY SCHEMA: This tells you what kind of data the API expects when you send a request. In this case, it's expecting data in JSON format, which is a way to structure and send information.
• Responses: This part explains what happens after you send a request to the API.
  • 200 OK: This is a common response code, and it means that everything went well with your request.
  • RESPONSE HEADERS: These are additional pieces of information sent back with the response. They provide details about the response itself.
    • Date: The date and time when the response was sent.
    • Content-Type: The type of data in the response, which is JSON in this case.
    • Content-Length: The size of the response data in bytes.
    • Connection: Information about how the connection is maintained.
    • x-amzn-RequestId: An ID associated with the request for tracking purposes.
    • Access-Control-Allow-Origin: Indicates which websites are allowed to access this API (in this case, any website is allowed with "*").
    • Access-Control-Allow-Headers: Lists the types of headers that are allowed when making requests.
    • x-amz-apigw-id: Another ID related to the request, often used for debugging.
    • Access-Control-Allow-Methods: Specifies which HTTP methods (like GET, POST, etc.) are allowed.
    • Access-Control-Expose-Headers: Specifies which headers are safe to expose to the response.
    • X-Amzn-Trace-Id: A trace ID used for tracking and debugging.
  • RESPONSE SCHEMA: This is the format in which the response data is structured. In this case, it's in JSON format, just like the request body.

In simpler terms, this information tells you how the API checks if you're allowed to use it (OAuth 2.0), what kind of data it expects from you (JSON), and what kind of response it sends back when you use it (a JSON response with specific details in its headers).

Clear Document

This API provides the functionality to clear the B2B documents (including Tax Invoices, Tax Invoice Credit Notes, and Tax Invoice Debit Notes) generated by your EGS (E-Invoice Generation Solution) in the ZATCA's sandbox environment.

To successfully report your document, it's essential to provide all the necessary parameters in the specified format. If needed, you can also include additional parameters based on your preferences.

In simpler terms, this API allows you to transmit your generated business documents to ZATCA's sandbox environment, ensuring compliance and accuracy in the process.

Request Parameters:

• invoiceData (REQUIRED): This parameter is a JSON object containing the data of the B2B document. It includes details such as the line items, seller information, buyer information, and more.
• documentType (REQUIRED): This parameter specifies the type of document being submitted. It should be one of the following enums:
  • Tax Invoice (TAX_INVOICE)
  • Tax Invoice Credit Note (TAX_INVOICE_CREDIT_NOTE)
  • Tax Invoice Debit Note (TAX_INVOICE_DEBIT_NOTE)
• referenceId (CONDITIONAL): This parameter is required in certain cases. It represents the ID of the original document (reference document) for which the current document is generated. It is applicable only for document types such as Tax Invoice Credit Note and Tax Invoice Debit Note. For example, if the document type is Tax Credit Note, the reference ID should be the invoice number for which this credit note is being created (e.g., 2022100627).
• documentIssueDateTime (REQUIRED): This parameter specifies the document's issue date and time in the "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" format (e.g., 2022-10-21T12:53:13.000Z).
• documentDueDateTime (OPTIONAL): This parameter represents the document's due date and time in the same format as the document issue date and time.
• sellerName (REQUIRED): This parameter should contain the name of the seller (e.g., Company Name).
• sellerAddress (REQUIRED): Seller's address is specified as a JSON object with fields such as address lines, building number, city, state, zip code, district, and country.
• buyerName (REQUIRED): The buyer's name is mandatory, especially for transactions mentioned in Article 53(7) and for private education and private healthcare to citizens.
• buyerAddress (REQUIRED): Similar to the seller's address, the buyer's address is provided as a JSON object with address details.
• documentLineItems (REQUIRED): This parameter is an array that represents the line items of the document. Each line item includes information such as description, price, quantity, taxable amount, discount, VAT rate, VAT amount, subtotal, and more.
• isSpecialBillingAgreement (REQUIRED): This boolean parameter indicates whether the transaction falls under special billing agreements, such as self-billed invoices or third-party billed invoices on behalf of the supplier.
• isTransactionType (REQUIRED): This boolean parameter specifies the transaction type, including Nominal Supply, Export, and Summary.
• isSelfBilled (CONDITIONAL): This parameter is required when isSpecialBillingAgreement is true, and it indicates whether the invoice is self-billed.
• isThirdParty (CONDITIONAL): Similar to isSelfBilled, this parameter is required when isSpecialBillingAgreement is true, and it specifies if a third party is involved in billing.
• isNominalSupply (CONDITIONAL): This parameter is required when isTransactionType is true, and it signifies whether the transaction is a nominal supply.
• isExport (CONDITIONAL): This parameter is required when isTransactionType is true, and it denotes whether the transaction is an export.
• isSummary (CONDITIONAL): This parameter is required when isTransactionType is true, and it indicates whether the transaction is a summary invoice.
• supplyDate (REQUIRED): The date and time of goods or service supply are provided in the "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" format.
• sellerVatRegistrationNumber (REQUIRED): This parameter should contain the seller's VAT registration number.
• additionalSellerIdType (REQUIRED): Here, you specify the type of additional seller ID, and it should be one of the following:
  • Commercial registration number with "CRN" as schemeID
  • Momra license with "MOM" as schemeID
  • MLSD license with "MLS" as schemeID
  • Sagia license with "SAG" as schemeID
  • Other OD with "OTH" as schemeID
• additionalSellerIdNumber (REQUIRED): This parameter represents the additional seller ID number corresponding to the selected ID type.
• sellerGroupVatRegistrationNumber (CONDITIONAL): If the seller is part of a group company, you can provide the seller's group VAT registration number.
• additionalBuyerIdType (REQUIRED): Similar to additional seller ID, this parameter specifies the type of additional buyer ID, and it should be chosen from a predefined list.
• additionalBuyerIdNumber (REQUIRED): This parameter contains the additional buyer ID number corresponding to the selected ID type.
• buyerGroupVatRegistrationNumber (CONDITIONAL): If the buyer is part of a group company, this parameter can include the buyer's group VAT number.
• specialTaxTreatment (CONDITIONAL): When tax is not charged at the standard rate, this parameter includes a narration explaining the tax treatment applied to the supply, as per Article 53 of the VAT Implementing Regulation.
• vatCurrency (CONDITIONAL): If the document currency is not SAR (Saudi Riyal), this parameter specifies the currency used for VAT calculations.
• noteIssuanceReason (CONDITIONAL): This parameter represents the reason for issuing a credit or debit note, as per Article 40 (paragraph 1) and Article 54 (3) of KSA VAT regulations.
• currency (REQUIRED): The transaction currency of the document is specified here (e.g., SAR).
• documentId (REQUIRED): This parameter serves as a unique identification of the invoice, often referred to as the Invoice Reference Number (IRN).

The provided JSON data represents a POST request payload for an API endpoint at "/test/api/v1/proto/clearDocument". This API request appears to be related to invoice data and clearance status. Let's break down the JSON data and its structure:

{
    "invoiceData": {
        "documentType": "TAX_INVOICE",
        "referenceId": "",
        "documentIssueDateTime": "2022-12-31T04:33:41.000Z",
        "documentDueDateTime": "2022-12-31T04:33:41.000Z",
        "sellerName": "ahmad abdurrahman",
        "sellerAddress": {},
        "buyerName": "Zahid Gani",
        "buyerAddress": {},
        "documentLineItems": [],
        "totalExcludingVat": 539,
        "totalTaxableAmountExcludingVat": 573,
        "vatTotal": 80.85,
        "documentTotal": 619.85,
        "discountOnDocumentTotal": 34,
        "isSpecialBillingAgreement": "false",
        "isTransactionType": "false",
        "isSelfBilled": "false",
        "isThirdParty": "false",
        "isNominalSupply": "false",
        "isExport": "false",
        "isSummary": "false",
        "supplyDate": "2022-12-31T04:33:41.000Z",
        "sellerVatRegistrationNumber": "310175397400003",
        "sellerGroupVatRegistrationNumber": "",
        "additionalSellerIdType": "CRN",
        "additionalSellerIdNumber": "34523452345234",
        "specialTaxTreatment": "0",
        "additionalBuyerIdType": "CRN",
        "additionalBuyerIdNumber": "12345678",
        "currency": "SAR",
        "paymentMeans": "CREDIT",
        "documentId": "0002"
    }
}

Here's an explanation of the JSON structure:

• invoiceData: This is the main object containing invoice-related information.
  • documentType: Specifies the type of document, in this case, "TAX_INVOICE".
  • referenceId: Appears to be an empty string for this invoice.
  • documentIssueDateTime: Indicates the date and time when the document was issued.
  • documentDueDateTime: Indicates the due date and time for the document.
  • sellerName: Contains the name of the seller, "ahmad abdurrahman".
  • sellerAddress: An empty object, which could potentially hold seller address details.
  • buyerName: Contains the name of the buyer, "Zahid Gani".
  • buyerAddress: An empty object, which could potentially hold buyer address details.
  • documentLineItems: An empty array, suggesting that this invoice has no line items.
  • totalExcludingVat: Total amount excluding Value Added Tax (VAT), 539 SAR in this case.
  • totalTaxableAmountExcludingVat: Total taxable amount excluding VAT, 573 SAR.
  • vatTotal: The total VAT amount, 80.85 SAR.
  • documentTotal: The total amount of the document, 619.85 SAR.
  • discountOnDocumentTotal: Indicates a discount on the document total, 34 SAR.
  • isSpecialBillingAgreement, isTransactionType, isSelfBilled, isThirdParty, isNominalSupply, isExport, isSummary: Boolean flags that appear to be "false" for this invoice.
  • supplyDate: Specifies the supply date and time.
  • sellerVatRegistrationNumber: VAT registration number of the seller.
  • sellerGroupVatRegistrationNumber: An empty string, possibly for seller group VAT registration.
  • additionalSellerIdType: Type of additional seller identification, "CRN" (assuming this means Customer Reference Number).
  • additionalSellerIdNumber: Additional identification number for the seller.
  • specialTaxTreatment: Indicates a special tax treatment, "0" in this case.
  • additionalBuyerIdType: Type of additional buyer identification, "CRN" (Customer Reference Number).
  • additionalBuyerIdNumber: Additional identification number for the buyer.
  • currency: Specifies the currency used, "SAR" (Saudi Riyal).
  • paymentMeans: Payment means used for this document, "CREDIT".
  • documentId: The document's unique identifier, "0002".

This JSON data appears to represent the details of a tax invoice, including information about the seller, buyer, invoice amounts, and related flags. It's typically used for tax and financial purposes. The API request is likely to submit this invoice data for processing, and the response would contain information about the clearance status, as indicated in the provided response sample.

These parameters are essential for successfully reporting your B2B document to ZATCA's sandbox environment, ensuring compliance with E-invoicing regulations in Saudi Arabia.

Response Parameters:

{
    "zatcaResponse": {
        "validationResults": {},
        "clearanceStatus": "CLEARED",
        "clearedInvoice": "PD94bWw... (truncated)",
        // Other fields...
    }
}

1. "zatcaResponse": This is the root object of the JSON data, and it contains several nested fields.
2. "validationResults": This field appears to be an object, but it's empty {}. It might be used to store validation results, but in this case, there don't appear to be any validation results provided.
3. "clearanceStatus": This field contains a string value "CLEARED". It likely represents the status of some clearance process and indicates that the process has been "Cleared."
4. "clearedInvoice": This field appears to contain a long string that starts with "PD94bWw...". This is likely a Base64-encoded XML document, often used for structured data.

The provided JSON data seems to be a response from some system or API. It contains information about the clearance status of an invoice, but the details are truncated, and it includes a Base64-encoded XML document, which might contain more specific information about the cleared invoice.

If you have specific questions or need more information about this JSON data or its purpose, please provide additional details or questions, and I'd be happy to assist further.

Look for the status code, which should typically be "200 OK" for a successful sign-in.

Download Document

Before sending the request, please check the Headers section for the Authorization header. Once you've confirmed its presence, proceed to send the request. This will allow you to obtain the base64 data you need.

After receiving the base64 encoded data, go to **https://base64.guru/converter/decode/pdf** or simply search for "Base64 to PDF" in your preferred search engine. Paste the base64 data into the provided field and click the "Decode" button. You'll then be able to download the PDF document.

Same Tax Invoice Documet:

same Invoice pdf format:

Add User API

• Utilize this API to incorporate a new user into your Antna account, enabling them to onboard another EGS within the ZATCA test environment.
• Ensure that you provide all the necessary parameters in the specified format, adhering to the minimum requirements for a successful account creation.
• You can follow the same signup and signin procedure for adding this new user.

The Add User API allows you to add a new user to your Antna account. This new user can be used to onboard another EGS (Electronic Governance Service) with the ZATCA (Zakat, Tax, and Customs Authority) test environment.

Request Parameters:

• email (Required): This parameter expects a string that represents the email for the account you want to create. For example, "example123@example.com".
• password (Required): This parameter expects a string that represents the password for your Antna test account. The password should contain at least one capital letter, one special character, and one number. For example, "Example@123".

Request Samples:

• Payload (Content type: application/json):

{
  "email": "admin125@example.com",
  "password": "Example@123"
}

Response Parameters:

• refreshToken: This is a string representing the refresh token. The refresh token is a permanent token that is valid for one year. An example response for this parameter is "SUCCESS".

Response Samples:

• HTTP Status Code: 200
• Content Type: application/json

{
  "refreshToken": ""
}

‍


AUTHORIZATIONS:

• oauth2Auth: This section indicates that the authorization method used for this API is OAuth2. OAuth2 is a widely used authorization framework that allows applications to securely access resources on behalf of a user.

HTTP Authorization Scheme:

• oauth2: This indicates that the HTTP Authorization Scheme used for this API is OAuth2, confirming the authentication and authorization method employed.

REQUEST BODY SCHEMA:

• application/json object: This specifies that the request body, which contains data sent to the API, should be in JSON format and follow the structure of a JSON object. JSON (JavaScript Object Notation) is a lightweight data-interchange format.

Responses:

• 200 OK: This is a standard HTTP response code that indicates a successful request. In this context, it means that the API request was successful, and a response is provided.

If you require further information, please don't hesitate to reach out to us through our Contact Us options:

‍

📞 WhatsApp or call us at +91 8778237303📧 Email us at: sales@complyance.io📺 Subscribe to our YouTube channel for informative content and updates: YouTube Channel - youtube.com/@complyance

We eagerly anticipate your engagement and are committed to assisting you in seamlessly navigating the realm of ZATCA invoicing! ✨

‍