# Generate E-Invoice Async

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

{% hint style="info" %}
This API can be used only for Simplified Tax Invoices and related notes (B2C).
{% endhint %}

### **Request Method**

POST

### **Request URL**

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

{% hint style="info" %}
Replace the `{{BASE_URL}}` with the one mentioned [here](..) based on whether you are using sandbox or production.
{% endhint %}

{% hint style="danger" %}
Rate Limit : 1000 API requests per minute
{% endhint %}

### **Request Headers**

<table><thead><tr><th width="170">Parameter</th><th width="132">Data Type</th><th>Field Validations</th><th>Description</th></tr></thead><tbody><tr><td>x-cleartax-auth-token</td><td>String</td><td>Cannot be empty</td><td>Mandatory. User auth token.</td></tr><tr><td>vat</td><td>String</td><td>Cannot be empty</td><td>Mandatory. VAT or Group VAT of the entity.</td></tr><tr><td>branch</td><td>String</td><td>Should be a valid branch from the user account</td><td>Optional. Branch name (store name) added in the user account which maps to a VAT or Group VAT of the entity.</td></tr><tr><td>accept-language</td><td>String</td><td>Enum: ar, en</td><td><p>Optional. Language of error message from ZATCA. ar - Arabic en - English</p><p>Default: en.</p></td></tr></tbody></table>

### **Request Path Params**

There are no path parameters for this API.

### **Request Query Params**

There are no query parameters for this API.

### **Request Body**

<table><thead><tr><th width="176.33333333333334">Parameter</th><th width="135">Data Type</th><th>Field Validations</th><th>Description</th></tr></thead><tbody><tr><td>DeviceId</td><td>String </td><td>MaxLength: 36</td><td>Mandatory. The Device ID registered with ClearTax.</td></tr><tr><td>EInvoice</td><td>Object</td><td>Not null</td><td>Mandatory. <a href="https://docs.cleartax.in/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference/resources-and-masters/e-invoice-object">E-Invoice object</a></td></tr><tr><td>CustomFields</td><td>Object</td><td>NA</td><td>Optional. Custom Fields object</td></tr></tbody></table>

**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**

| Fields      | Generate E-Invoice API (via JSON)                             | Generate E-Invoice via XML API                                                                                                                                                                                                                                                |
| ----------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UUID        | Optional. Will be generated by ClearTax if not sent in input. | Optional. Will be generated by ClearTax if not sent in input.                                                                                                                                                                                                                 |
| ICV         | Read Only. Will be ignored if sent in input.                  | Read Only. Will be ignored if sent in input.                                                                                                                                                                                                                                  |
| PIH         | Read Only. Will be ignored if sent in input.                  | Read Only. Will be ignored if sent in input.                                                                                                                                                                                                                                  |
| InvoiceHash | Read Only. Will be ignored if sent in input.                  | Read Only. Will be ignored if sent in input.                                                                                                                                                                                                                                  |
| Signature   | Read Only. Will be ignored if sent in input.                  | Read Only. Will be ignored if sent in input.                                                                                                                                                                                                                                  |
| RawQRCode   | Read Only. Will be ignored if sent in input.                  | Read Only. Will be ignored if sent in input.                                                                                                                                                                                                                                  |
| InvoiceXml  | NA. Not available in the input schema.                        | <p>NA. Not available in the input schema. The XML received will be enhanced before sending to ZATCA.</p><p><br><strong>The use case where generating CSID (at customer side) and reporting CSID (at ClearTax side) is different, is not supported at the moment.</strong></p> |

### **Sample Request**

```json
{
  "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**

| HTTP Status Code | Description                                        |
| ---------------- | -------------------------------------------------- |
| 202              | For successfully acceptance from CT                |
| 400              | For any cleartax validation error                  |
| 400              | Validation error from zatca                        |
| 401              | If the user is not authenticated for the operation |
| 403              | If the user is not authorized for the operation    |
| 429              | Too Many Requests                                  |

### **Response Schema**

<table><thead><tr><th width="161">Parameter</th><th width="119">Data Type</th><th>Field Validations</th><th>Description</th></tr></thead><tbody><tr><td>DeviceId</td><td>String</td><td>MaxLength: 36</td><td>Optional. Device ID used to generate invoices.</td></tr><tr><td>Status</td><td>String</td><td>Enum: GENERATED, NOT_GENERATED, GENERATION_FAILED, IN_PROGRESS</td><td><p>Mandatory.</p><p>Status of E-Invoice QR Code. This is the same as QrCodeStatus below. Provided only for backward compatibility for Phase I API.</p><p>IN_PROGRESS, NOT_GENERATED, GENERATION_FAILED</p></td></tr><tr><td>QrCodeStatus</td><td>String</td><td>Enum: GENERATED, NOT_GENERATED, GENERATION_FAILED</td><td><p>Mandatory.</p><p>Status of E-Invoice QR Code.</p><p>GENERATED, NOT_GENERATED, GENERATION_FAILED</p></td></tr><tr><td>InvoiceStatus</td><td>String</td><td>Enum: PENDING, FAILED. </td><td><p>Mandatory.</p><p>Status of submission to ZATCA.</p></td></tr><tr><td>QRCode</td><td>String</td><td></td><td><p>Optional. Rendered QR Code image in base64 encoded PNG format.</p><p>If validations fail, this will be null.</p></td></tr><tr><td>RawQRCode</td><td>String</td><td></td><td>Optional. QR Code payload in base64 encoded TLV format.</td></tr><tr><td>InvoiceXml</td><td>String</td><td></td><td>Optional. It is the XML used for reporting.</td></tr><tr><td>UUID</td><td>String</td><td></td><td><p>Optional. UUID sent to ZATCA</p><p>ClearTax generates this before sending to ZATCA, if not sent in input.</p></td></tr><tr><td>ICV</td><td>String</td><td></td><td>Optional. Invoice counter value sent to ZATCA<br>ClearTax generates this before sending it to ZATCA.</td></tr><tr><td>PIH</td><td>String</td><td></td><td>Optional. Previous hash value, Invoice hash value of previous invoice reported for same deviceId.</td></tr><tr><td>InvoiceHash</td><td>String</td><td></td><td><p>Optional. Current invoice hash.</p><p>Hash value of current invoice xml by removing tags <a href="ext:UBLExtensions">ext:UBLExtensions</a>, <a href="cac:AdditionalDocumentReference:QRCode">cac:AdditionalDocumentReference:QRCode</a></p></td></tr><tr><td>InvoiceType</td><td>String</td><td>Enum:<br>INV, CRN, DBN</td><td><p>Mandatory.</p><p>Document Type: INV-INVOICE, CRN-CREDIT NOTE, DBN-DEBIT NOTE.</p></td></tr><tr><td>InvoiceNumber</td><td>String</td><td>Can not be null</td><td>Mandatory. Invoice number (ID) as per the input.</td></tr><tr><td>IssueDate</td><td>String</td><td>Can not be null</td><td>Mandatory. Issue Date as per the input.</td></tr><tr><td>IssueTime</td><td>String</td><td>Format: HH:mm:ss (24 hr format)</td><td>Mandatory. Invoice issue time. The time when the invoice was issued.</td></tr><tr><td>GeneratedDate</td><td>String</td><td>Cannot be null</td><td>Mandatory. Date on which the invoice is generated</td></tr><tr><td>GeneratedTime</td><td>String</td><td>Format: HH:mm:ss (24 hr format)</td><td>Mandatory. Invoice generation time. The time when the invoice is generated.</td></tr><tr><td>SellerVatNumber</td><td>String</td><td>Can not be null</td><td>Mandatory. Seller VAT identification number.</td></tr><tr><td>BuyerVatNumber</td><td>String</td><td>Can not be null</td><td>Optional. Buyer VAT identification number.<br></td></tr><tr><td>ErrorList</td><td>Array&#x3C;Error Detail></td><td>Can be empty</td><td>Optional. Validation errors.</td></tr></tbody></table>

### **Error Details Object**

<table><thead><tr><th width="165">Parameter</th><th width="125">Data Type</th><th>Field Validations</th><th>Description</th></tr></thead><tbody><tr><td>ErrorCode</td><td>String</td><td>Cannot be null</td><td>A code to identify the error. Error codes are published above.</td></tr><tr><td>ErrorMessage</td><td>String</td><td>Cannot be null</td><td>Human readable error message.</td></tr><tr><td>ErrorSource</td><td>String</td><td>CLEARTAX</td><td>Source of the error.</td></tr><tr><td>Path</td><td>String</td><td>-</td><td>If it is a validation error of a request data, it will point to the request data field. Example below.</td></tr></tbody></table>

### **Sample Response**

Success for Simplified Document - HTTP Status Code - 200

```json
{
    "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

```json
{
    "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).

{% hint style="info" %}
Note: In case a document is validated by ClearTax but failed at ZATCA, then the HTTP Status Code will be 200 and not 400.
{% endhint %}

```json
{
    "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.&#x20;
2. Each customer is allowed to send a limited number of requests per minute to prevent server overload. If the limit is exceeded, the server will respond with a 429 Too Many Requests status code.
3. 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."\
