Generate E-Invoice Async

Generate a valid E-Invoice with JSON payload synchronously and send it to ZATCA for reporting asynchronously.

This API can be used only for Simplified Tax Invoices and related notes (B2C).

Request Method

POST

Request URL

{{BASE_URL}}/v2/einvoices/generate/async

Replace the {{BASE_URL}} with the one mentioned here based on whether you are using sandbox or production.

Request Headers

Request Path Params

There are no path parameters for this API.

Request Query Params

There are no query parameters for this API.

Request Body

Custom Fields Object This is a custom object of key-value pairs that can be used to display custom fields in custom output PDF templates or in certain reports. For example:

{
    "country_of_origin": "IN",
    "total_containers": "3"
}

Requirement of Critical Fields

Sample Request

{
  "DeviceId": "2caa0dd5-2f20-44d1-b1c8-6257f3f60634",
  "EInvoice": {
    "ProfileID": "reporting:1.0",
    "ID": {
      "en": "269",
      "ar": null
    },
    "InvoiceTypeCode": {
      "name": "0100000",
      "value": "388"
    },
    "IssueDate": "2021-04-25",
    "IssueTime": "15:30:00",
    "DocumentCurrencyCode": "SAR",
    "TaxCurrencyCode": "SAR",
    "Delivery": [
      {
        "ActualDeliveryDate": "2022-04-25"
      }
    ],
    "AccountingSupplierParty": {
      "Party": {
        "PartyLegalEntity": {
          "RegistrationName": {
            "en": "Al Salam Supplies Co. LTD",
            "ar": null
          }
        },
        "PartyTaxScheme": {
          "CompanyID": "300492946900003",
          "TaxScheme": {
            "ID": "VAT"
          }
        },
        "PartyIdentification": {
          "ID": {
            "schemeID": "SAG",
            "value": "123457890"
          }
        },
        "PostalAddress": {
          "StreetName": {
            "en": "King Abdulaziz Road",
            "ar": null
          },
          "BuildingNumber": {
            "en": "8228",
            "ar": null
          },
          "PlotIdentification": {
            "en": "2121",
            "ar": null
          },
          "CityName": {
            "en": "Riyadh",
            "ar": null
          },
          "PostalZone": 12643,
          "CitySubdivisionName": {
            "en": "Al Amal",
            "ar": null
          },
          "Country": {
            "IdentificationCode": "SA"
          },
          "CountrySubentity": {
            "en": "Riyadh Region",
            "ar": null
          }
        }
      }
    },
    "AccountingCustomerParty": {
      "Party": {
        "PartyLegalEntity": {
          "RegistrationName": {
            "en": "AL KAWTHAR MARKETS",
            "ar": null
          }
        },
        "PartyTaxScheme": {
          "CompanyID": null,
          "TaxScheme": {
            "ID": "VAT"
          }
        },
        "PartyIdentification": {
          "ID": {
            "schemeID": "SAG",
            "value": "123C12345678"
          }
        },
        "PostalAddress": {
          "StreetName": {
            "en": "King Abdullah Road",
            "ar": null
          },
          "BuildingNumber": {
            "en": "3709",
            "ar": null
          },
          "PlotIdentification": {
            "en": "1004",
            "ar": null
          },
          "CityName": {
            "en": "Riyadh",
            "ar": null
          },
          "PostalZone": 11564,
          "CitySubdivisionName": {
            "en": "Al Mursalat",
            "ar": null
          },
          "Country": {
            "IdentificationCode": "SA"
          },
          "CountrySubentity": {
            "en": "Riyadh Region",
            "ar": null
          }
        }
      }
    },
    "InvoiceLine": [
      {
        "ID": "1",
        "Item": {
          "Name": {
            "en": "Item A",
            "ar": null
          },
          "ClassifiedTaxCategory": {
            "ID": "S",
            "Percent": 15.00,
            "TaxScheme": {
              "ID": "VAT"
            }
          }
        },
        "Price": {
          "PriceAmount": {
            "currencyID": "SAR",
            "value": 200.00
          }
        },
        "InvoicedQuantity": {
          "value": 1.0
        },
        "LineExtensionAmount": {
          "currencyID": "SAR",
          "value": 200.00
        },
        "TaxTotal": {
          "TaxAmount": {
            "currencyID": "SAR",
            "value": 30.00
          },
          "RoundingAmount": {
            "currencyID": "SAR",
            "value": 230.00
          }
        }
      },
      {
        "ID": "2",
        "Item": {
          "Name": {
            "en": "Item B",
            "ar": null
          },
          "ClassifiedTaxCategory": {
            "ID": "S",
            "Percent": 15.00,
            "TaxScheme": {
              "ID": "VAT"
            }
          }
        },
        "Price": {
          "PriceAmount": {
            "currencyID": "SAR",
            "value": 350.00
          }
        },
        "InvoicedQuantity": {
          "value": 2.0
        },
        "LineExtensionAmount": {
          "currencyID": "SAR",
          "value": 700.00
        },
        "TaxTotal": {
          "TaxAmount": {
            "currencyID": "SAR",
            "value": 105.00
          },
          "RoundingAmount": {
            "currencyID": "SAR",
            "value": 805.00
          }
        }
      }
    ],
    "TaxTotal": [
      {
        "TaxAmount": {
          "currencyID": "SAR",
          "value": 135.00
        },
        "TaxSubtotal": [
          {
            "TaxableAmount": {
              "currencyID": "SAR",
              "value": 900.00
            },
            "TaxAmount": {
              "currencyID": "SAR",
              "value": 135.00
            },
            "TaxCategory": {
              "ID": "S",
              "Percent": 15.00,
              "TaxScheme": {
                "ID": "VAT"
              }
            }
          }
        ]
      }
    ],
    "LegalMonetaryTotal": {
      "LineExtensionAmount": {
        "currencyID": "SAR",
        "value": 900.00
      },
      "AllowanceTotalAmount": {
        "currencyID": "SAR",
        "value": 0.00
      },
      "TaxExclusiveAmount": {
        "currencyID": "SAR",
        "value": 900.00
      },
      "TaxInclusiveAmount": {
        "currencyID": "SAR",
        "value": 1035.00
      },
      "PayableAmount": {
        "currencyID": "SAR",
        "value": 1035.00
      }
    },
    "PaymentMeans": [
      {
        "PaymentMeansCode": "42"
      }
    ]
  },
  "CustomFields": {
    "country_of_origin": "IN",
    "total_containers": "3"
  }
}

Response Status Codes

Response Schema

Error Details Object

Sample Response

Success for Simplified Document - HTTP Status Code - 200

{
    "DeviceId": "625410e387173015f7e5a4c6",
    "Status": "GENERATED",
    "QrCodeStatus": "GENERATED",
    "InvoiceStatus": "PENDING",
    "QRCode": "MjAsSIy1….",
    "RawQRCode": "ARlBb….",
    "InvoiceXml": "ASsdfkf...",
    "UUID": "03779160-c140-4a32-9f9a-7b429149c0ef",
    "ICV": "61",
    "PIH": "KILyvZqPxblzStkif5UsaEtMhLDZUgU/VudKsBFxQN0=",
    "InvoiceHash": "HDlSmFWBE+9LHLrg6X0moqr3fQU677tFbrITarslOZI=",
    "InvoiceType": "INV",
    "InvoiceNumber": "315",
    "IssueDate": "2021-04-25",
    "IssueTime": "16:42:25",
    "GeneratedDate": "2021-04-25",
    "GeneratedTime": "16:42:25",
    "SellerVatNumber": "300492946900003",
    "BuyerVatNumber": null,
    "ErrorList": [],
    "WarningList":[],
    "Message": null
}

Error from ClearTax - HTTP Status Code - 400

{
    "InvoiceType": "INV",
    "InvoiceNumber": "2022",
    "IssueDate": "2021-04-25",
    "IssueTime": "12:24:26",
    "SellerVatNumber": "300492946900003",
    "Status": "GENERATION_FAILED",
    "QrCodeStatus": "GENERATION_FAILED",
    "InvoiceStatus": "FAILED",
    "ErrorList": [
        {
            "ErrorCode": "6002",
            "ErrorMessage": "If Supplier Group Vat number is provided, scheme id must be HQ",
            "ErrorSource": "CLEARTAX",
            "Path": "EInvoice.AccountingSupplierParty.Party.PartyIdentification.ID.schemeID"
        },
        {
            "ErrorCode": "6002",
            "ErrorMessage": "Payment means code in an invoice must contain one of the values (10, 30, 42, 48, 1). In the simplified tax invoice and associated credit notes and debit notes this value is optional.",
            "ErrorSource": "CLEARTAX",
            "Path": "EInvoice.PaymentMeans.PaymentMeansCode"
        }
    ],
}

Error from ZATCA - HTTP Status Code - 200 (Sample Simplified invoice where QR code is generated by ClearTax and then sent to ZATCA for reporting which is not approved by ZATCA).

Note: In case a document is validated by ClearTax but failed at ZATCA, then the HTTP Status Code will be 200 and not 400.

{
    "DeviceId": "625410e387173015f7e5a4c6",
    "Status": "GENERATED",
    "QrCodeStatus": "GENERATED",
    "InvoiceStatus": "NOT_REPORTED",
    "QRCode": "i+GdAUnzMJS.....",
    "RawQRCode": "ARlBbCBTYWxhbSBTdXBwbGllcyBDby4g.....",
    "InvoiceXml": null,
    "UUID": "03779160-c140-4a32-9f9a-7b429149c0ef",
    "ICV": "61",
    "PIH": "KILyvZqPxblzStkif5UsaEtMhLDZUgU/VudKsBFxQN0=",
    "InvoiceHash": "HDlSmFWBE+9LHLrg6X0moqr3fQU677tFbrITarslOZI=",
    "InvoiceType": "INV",
    "InvoiceNumber": "315",
    "IssueDate": "2021-04-25",
    "IssueTime": "16:42:25",
    "SellerVatNumber": "300492946900003",
    "BuyerVatNumber": null,
    "ErrorList": [
        {
            "ErrorCode": "Invalid-Invoice-Hash",
            "ErrorMessage": "The provided invoice hash is invalid",
            "ErrorSource": "ZATCA"
        }
    ],
    "WarningList": [],
    "Message": null
}

API Validations

API validations will remain the same as in Phase I. In addition, the following new validations are added for Phase II.

  1. Other Seller ID is Mandatory.

  2. Other Buyer ID is Mandatory.

  3. Payment type code is Mandatory.

  4. The document issue date must be less than or equal to the current date.

  5. Buyer name is mandatory for Simplified Tax Invoice and associated credit/debit notes.

  6. DEC-20=[BR-DEC-20] - The allowed maximum number of decimals for the VAT category tax amount (BT-117) is 2.

  7. BR-DEC-13=[BR-DEC-13] - The allowed maximum number of decimals for the Invoice total VAT amount (BT-110) is 2.

  8. BR-DEC-15=[BR-DEC-15] - The allowed maximum number of decimals for the Invoice total VAT amount in accounting currency (BT-111) is 2.

API Constraints

  1. This API needs to be authenticated with a valid user authentication token. If the auth token is not present or is invalid, the API will return HTTP Status Code 401. If the auth token is valid, but the user does not have the authorization to generate einvoice , then the API will return HTTP Status Code 403.

  2. Async API is for simplified tax invoices only as for standard tax invoices ZATCA generates the QR code and signs it realtime. Error message in case standard tax invoices are sent via this API - "Async API call is only supported for Reporting simplified tax invoices. For standard invoices use the Generate e-Invoice API."

Last updated