# Generate E-Invoice via XML

Generate a valid E-Invoice with an XML file and send it to ZATCA for clearance or reporting.

### Request Method

POST

### Request URL

```
{{BASE_URL}}/v2/einvoices/generate-with-file
```

{% hint style="info" %}
Replace the `{{BASE_URL}}` with the one mentioned [here](https://docs.cleartax.in/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference) based on whether you are using sandbox or production.
{% endhint %}

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

### Request Headers

| Parameter             | Data Type | Field Validations                               | Description                                                                                                                                                                                                           |
| --------------------- | --------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| x-cleartax-auth-token | String    | Cannot be empty.                                | Mandatory. [User auth token](https://docs.cleartax.in/cleartax-docs/e-invoicing-ksa-api/learn-e-invoicing-ksa-api-basics/how-to-get-e-invoicing-ksa-auth-token).                                                      |
| vat                   | String    | Cannot be empty                                 | Mandatory. VAT or Group VAT of the entity.                                                                                                                                                                            |
| branch                | String    | Should be a valid branch from the user account. | Optional. Branch name (store name) added in the user account which maps to a VAT or Group VAT of the entity.                                                                                                          |
| accept-language       | String    | Enum: ar, en                                    | <p>Optional. Language of error message from ZATCA. </p><p></p><p>ar - Arabic </p><p>en - English </p><p></p><p>Default: en.</p>                                                                                       |
| device-id             | String    | MaxLength: 36                                   | Mandatory. The Device ID registered with ClearTax. Refer to [How to get a Device ID](https://docs.cleartax.in/cleartax-docs/e-invoicing-ksa-api/learn-e-invoicing-ksa-api-basics/how-to-register-a-device-for-a-vat)? |

### Request Path Params

There are no path parameters for this API.

### Request Query Params

There are no query parameters for this API.

### Request Body

| Parameter | Data Type | Field Validations | Description |
| --------- | --------- | ----------------- | ----------- |
| file      | form-data | NA                | Mandatory.  |

#### Requirement of Critical Fields

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

### Sample Request

**Standard Tax Invoice XML-**&#x20;

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2">
    
    <cbc:ProfileID>reporting:1.0</cbc:ProfileID>
    <cbc:ID>KSAINV-002</cbc:ID>
    <cbc:UUID>8d487816-70b8-4ade-a618-9d620b73814a</cbc:UUID>
    <cbc:IssueDate>2022-04-07</cbc:IssueDate>
    <cbc:IssueTime>12:21:28</cbc:IssueTime>
    <cbc:InvoiceTypeCode name="0100000">388</cbc:InvoiceTypeCode>
    <cbc:DocumentCurrencyCode>SAR</cbc:DocumentCurrencyCode>
    <cbc:TaxCurrencyCode>SAR</cbc:TaxCurrencyCode>
    <cac:AdditionalDocumentReference>
        <cbc:ID>ICV</cbc:ID>
        <cbc:UUID>23</cbc:UUID>
    </cac:AdditionalDocumentReference>
    <cac:AdditionalDocumentReference>
        <cbc:ID>PIH</cbc:ID>
        <cac:Attachment>
            <cbc:EmbeddedDocumentBinaryObject mimeCode="text/plain">NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzljMmRiYzIzOWRkNGU5MWI0NjcyOWQ3M2EyN2ZiNTdlOQ==</cbc:EmbeddedDocumentBinaryObject>
        </cac:Attachment>
    </cac:AdditionalDocumentReference>
    
    
<cac:Signature>
      <cbc:ID>urn:oasis:names:specification:ubl:signature:Invoice</cbc:ID>
      <cbc:SignatureMethod>urn:oasis:names:specification:ubl:dsig:enveloped:xades</cbc:SignatureMethod>
</cac:Signature>
<cac:AccountingSupplierParty>
      <cac:Party>
         <cac:PartyIdentification>
            <cbc:ID schemeID="MLS">123457890</cbc:ID>
         </cac:PartyIdentification>
         <cac:PostalAddress>
            <cbc:StreetName>King Abdulaziz Road</cbc:StreetName>
            <cbc:BuildingNumber>8228</cbc:BuildingNumber>
            <cbc:PlotIdentification>2121</cbc:PlotIdentification>
            <cbc:CitySubdivisionName>Al Amal</cbc:CitySubdivisionName>
            <cbc:CityName>Riyadh</cbc:CityName>
            <cbc:PostalZone>12643</cbc:PostalZone>
            <cbc:CountrySubentity>Riyadh Region</cbc:CountrySubentity>
            <cac:Country>
               <cbc:IdentificationCode>SA</cbc:IdentificationCode>
            </cac:Country>
         </cac:PostalAddress>
         <cac:PartyTaxScheme>
            <cbc:CompanyID>300188493300003</cbc:CompanyID>
            <cac:TaxScheme>
               <cbc:ID>VAT</cbc:ID>
            </cac:TaxScheme>
         </cac:PartyTaxScheme>
         <cac:PartyLegalEntity>
            <cbc:RegistrationName>Al Salam Supplies Co. LTD</cbc:RegistrationName>
         </cac:PartyLegalEntity>
      </cac:Party>
   </cac:AccountingSupplierParty>
   <cac:AccountingCustomerParty>
      <cac:Party>
         <cac:PartyIdentification>
            <cbc:ID schemeID="SAG">123C12345678</cbc:ID>
         </cac:PartyIdentification>
         <cac:PostalAddress>
            <cbc:StreetName>King Abdullah Road</cbc:StreetName>
            <cbc:BuildingNumber>3709</cbc:BuildingNumber>
            <cbc:PlotIdentification>1004</cbc:PlotIdentification>
            <cbc:CitySubdivisionName>Al Mursalat</cbc:CitySubdivisionName>
            <cbc:CityName>Riyadh</cbc:CityName>
            <cbc:PostalZone>11564</cbc:PostalZone>
            <cbc:CountrySubentity>Riyadh Region</cbc:CountrySubentity>
            <cac:Country>
               <cbc:IdentificationCode>SA</cbc:IdentificationCode>
            </cac:Country>
         </cac:PostalAddress>
         <cac:PartyTaxScheme>
            <cac:TaxScheme>
<cbc:CompanyID>310175397400003</cbc:CompanyID>
               <cbc:ID>VAT</cbc:ID>
            </cac:TaxScheme>
         </cac:PartyTaxScheme>
         <cac:PartyLegalEntity>
            <cbc:RegistrationName>AL KAWTHAR MARKETS</cbc:RegistrationName>
         </cac:PartyLegalEntity>
      </cac:Party>
   </cac:AccountingCustomerParty>

    <cac:Delivery>
        <cbc:ActualDeliveryDate>2022-09-07</cbc:ActualDeliveryDate>
    </cac:Delivery>
    <cac:PaymentMeans>
        <cbc:PaymentMeansCode>10</cbc:PaymentMeansCode>
    </cac:PaymentMeans>
    <cac:AllowanceCharge>
        <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
        <cbc:AllowanceChargeReason>discount</cbc:AllowanceChargeReason>
        <cbc:Amount currencyID="SAR">0.00</cbc:Amount>
        <cac:TaxCategory>
            <cbc:ID schemeID="UN/ECE 5305" schemeAgencyID="6">S</cbc:ID>
            <cbc:Percent>15</cbc:Percent>
            <cac:TaxScheme>
                <cbc:ID schemeID="UN/ECE 5153" schemeAgencyID="6">VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:TaxCategory>
    </cac:AllowanceCharge>
    <cac:TaxTotal>
        <cbc:TaxAmount currencyID="SAR">0.6</cbc:TaxAmount>
    </cac:TaxTotal>
    <cac:TaxTotal>
        <cbc:TaxAmount currencyID="SAR">0.6</cbc:TaxAmount>
        <cac:TaxSubtotal>
            <cbc:TaxableAmount currencyID="SAR">4.00</cbc:TaxableAmount>
            <cbc:TaxAmount currencyID="SAR">0.60</cbc:TaxAmount>
             <cac:TaxCategory>
                 <cbc:ID schemeID="UN/ECE 5305" schemeAgencyID="6">S</cbc:ID>
                 <cbc:Percent>15.00</cbc:Percent>
                <cac:TaxScheme>
                   <cbc:ID schemeID="UN/ECE 5153" schemeAgencyID="6">VAT</cbc:ID>
                </cac:TaxScheme>
             </cac:TaxCategory>
        </cac:TaxSubtotal>
    </cac:TaxTotal>
    <cac:LegalMonetaryTotal>
        <cbc:LineExtensionAmount currencyID="SAR">4.00</cbc:LineExtensionAmount>
        <cbc:TaxExclusiveAmount currencyID="SAR">4.00</cbc:TaxExclusiveAmount>
        <cbc:TaxInclusiveAmount currencyID="SAR">4.60</cbc:TaxInclusiveAmount>
        <cbc:AllowanceTotalAmount currencyID="SAR">0.00</cbc:AllowanceTotalAmount>
        <cbc:PrepaidAmount currencyID="SAR">0.00</cbc:PrepaidAmount>
        <cbc:PayableAmount currencyID="SAR">4.60</cbc:PayableAmount>
    </cac:LegalMonetaryTotal>
    <cac:InvoiceLine>
        <cbc:ID>1</cbc:ID>
        <cbc:InvoicedQuantity unitCode="PCE">2.000000</cbc:InvoicedQuantity>
        <cbc:LineExtensionAmount currencyID="SAR">4.00</cbc:LineExtensionAmount>
        <cac:TaxTotal>
             <cbc:TaxAmount currencyID="SAR">0.60</cbc:TaxAmount>
             <cbc:RoundingAmount currencyID="SAR">4.60</cbc:RoundingAmount>
        </cac:TaxTotal>
        <cac:Item>
            <cbc:Name>قلم رصاص</cbc:Name>
            <cac:ClassifiedTaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>15.00</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:ClassifiedTaxCategory>
        </cac:Item>
        <cac:Price>
            <cbc:PriceAmount currencyID="SAR">2.00</cbc:PriceAmount>
            <cac:AllowanceCharge>
               <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
               <cbc:AllowanceChargeReason>discount</cbc:AllowanceChargeReason>
               <cbc:Amount currencyID="SAR">0.00</cbc:Amount>
            </cac:AllowanceCharge>
        </cac:Price>
    </cac:InvoiceLine>
</Invoice>
```

**Simplified Tax Invoice XML-**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2">
    
    <cbc:ProfileID>reporting:1.0</cbc:ProfileID>
    <cbc:ID>KSAINV-001</cbc:ID>
    <cbc:UUID>8d487816-70b8-4ade-a618-9d620b73814a</cbc:UUID>
    <cbc:IssueDate>2022-04-07</cbc:IssueDate>
    <cbc:IssueTime>12:21:28</cbc:IssueTime>
    <cbc:InvoiceTypeCode name="0200000">388</cbc:InvoiceTypeCode>
    <cbc:DocumentCurrencyCode>SAR</cbc:DocumentCurrencyCode>
    <cbc:TaxCurrencyCode>SAR</cbc:TaxCurrencyCode>
    <cac:AdditionalDocumentReference>
        <cbc:ID>ICV</cbc:ID>
        <cbc:UUID>23</cbc:UUID>
    </cac:AdditionalDocumentReference>
    <cac:AdditionalDocumentReference>
        <cbc:ID>PIH</cbc:ID>
        <cac:Attachment>
            <cbc:EmbeddedDocumentBinaryObject mimeCode="text/plain">NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzljMmRiYzIzOWRkNGU5MWI0NjcyOWQ3M2EyN2ZiNTdlOQ==</cbc:EmbeddedDocumentBinaryObject>
        </cac:Attachment>
    </cac:AdditionalDocumentReference>
    
    
<cac:Signature>
      <cbc:ID>urn:oasis:names:specification:ubl:signature:Invoice</cbc:ID>
      <cbc:SignatureMethod>urn:oasis:names:specification:ubl:dsig:enveloped:xades</cbc:SignatureMethod>
</cac:Signature>
<cac:AccountingSupplierParty>
      <cac:Party>
         <cac:PartyIdentification>
            <cbc:ID schemeID="MLS">123457890</cbc:ID>
         </cac:PartyIdentification>
         <cac:PostalAddress>
            <cbc:StreetName>King Abdulaziz Road</cbc:StreetName>
            <cbc:BuildingNumber>8228</cbc:BuildingNumber>
            <cbc:PlotIdentification>2121</cbc:PlotIdentification>
            <cbc:CitySubdivisionName>Al Amal</cbc:CitySubdivisionName>
            <cbc:CityName>Riyadh</cbc:CityName>
            <cbc:PostalZone>12643</cbc:PostalZone>
            <cbc:CountrySubentity>Riyadh Region</cbc:CountrySubentity>
            <cac:Country>
               <cbc:IdentificationCode>SA</cbc:IdentificationCode>
            </cac:Country>
         </cac:PostalAddress>
         <cac:PartyTaxScheme>
            <cbc:CompanyID>300188493300003</cbc:CompanyID>
            <cac:TaxScheme>
               <cbc:ID>VAT</cbc:ID>
            </cac:TaxScheme>
         </cac:PartyTaxScheme>
         <cac:PartyLegalEntity>
            <cbc:RegistrationName>Al Salam Supplies Co. LTD</cbc:RegistrationName>
         </cac:PartyLegalEntity>
      </cac:Party>
   </cac:AccountingSupplierParty>
   <cac:AccountingCustomerParty>
      <cac:Party>
         <cac:PartyIdentification>
            <cbc:ID schemeID="SAG">123C12345678</cbc:ID>
         </cac:PartyIdentification>
         <cac:PostalAddress>
            <cbc:StreetName>King Abdullah Road</cbc:StreetName>
            <cbc:BuildingNumber>3709</cbc:BuildingNumber>
            <cbc:PlotIdentification>1004</cbc:PlotIdentification>
            <cbc:CitySubdivisionName>Al Mursalat</cbc:CitySubdivisionName>
            <cbc:CityName>Riyadh</cbc:CityName>
            <cbc:PostalZone>11564</cbc:PostalZone>
            <cbc:CountrySubentity>Riyadh Region</cbc:CountrySubentity>
            <cac:Country>
               <cbc:IdentificationCode>SA</cbc:IdentificationCode>
            </cac:Country>
         </cac:PostalAddress>
         <cac:PartyTaxScheme>
            <cac:TaxScheme>
               <cbc:ID>VAT</cbc:ID>
            </cac:TaxScheme>
         </cac:PartyTaxScheme>
         <cac:PartyLegalEntity>
            <cbc:RegistrationName>AL KAWTHAR MARKETS</cbc:RegistrationName>
         </cac:PartyLegalEntity>
      </cac:Party>
   </cac:AccountingCustomerParty>
​
    <cac:Delivery>
        <cbc:ActualDeliveryDate>2022-09-07</cbc:ActualDeliveryDate>
    </cac:Delivery>
    <cac:PaymentMeans>
        <cbc:PaymentMeansCode>10</cbc:PaymentMeansCode>
    </cac:PaymentMeans>
    <cac:AllowanceCharge>
        <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
        <cbc:AllowanceChargeReason>discount</cbc:AllowanceChargeReason>
        <cbc:Amount currencyID="SAR">0.00</cbc:Amount>
        <cac:TaxCategory>
            <cbc:ID schemeID="UN/ECE 5305" schemeAgencyID="6">S</cbc:ID>
            <cbc:Percent>15</cbc:Percent>
            <cac:TaxScheme>
                <cbc:ID schemeID="UN/ECE 5153" schemeAgencyID="6">VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:TaxCategory>
    </cac:AllowanceCharge>
    <cac:TaxTotal>
        <cbc:TaxAmount currencyID="SAR">0.6</cbc:TaxAmount>
    </cac:TaxTotal>
    <cac:TaxTotal>
        <cbc:TaxAmount currencyID="SAR">0.6</cbc:TaxAmount>
        <cac:TaxSubtotal>
            <cbc:TaxableAmount currencyID="SAR">4.00</cbc:TaxableAmount>
            <cbc:TaxAmount currencyID="SAR">0.60</cbc:TaxAmount>
             <cac:TaxCategory>
                 <cbc:ID schemeID="UN/ECE 5305" schemeAgencyID="6">S</cbc:ID>
                 <cbc:Percent>15.00</cbc:Percent>
                <cac:TaxScheme>
                   <cbc:ID schemeID="UN/ECE 5153" schemeAgencyID="6">VAT</cbc:ID>
                </cac:TaxScheme>
             </cac:TaxCategory>
        </cac:TaxSubtotal>
    </cac:TaxTotal>
    <cac:LegalMonetaryTotal>
        <cbc:LineExtensionAmount currencyID="SAR">4.00</cbc:LineExtensionAmount>
        <cbc:TaxExclusiveAmount currencyID="SAR">4.00</cbc:TaxExclusiveAmount>
        <cbc:TaxInclusiveAmount currencyID="SAR">4.60</cbc:TaxInclusiveAmount>
        <cbc:AllowanceTotalAmount currencyID="SAR">0.00</cbc:AllowanceTotalAmount>
        <cbc:PrepaidAmount currencyID="SAR">0.00</cbc:PrepaidAmount>
        <cbc:PayableAmount currencyID="SAR">4.60</cbc:PayableAmount>
    </cac:LegalMonetaryTotal>
    <cac:InvoiceLine>
        <cbc:ID>1</cbc:ID>
        <cbc:InvoicedQuantity unitCode="PCE">2.000000</cbc:InvoicedQuantity>
        <cbc:LineExtensionAmount currencyID="SAR">4.00</cbc:LineExtensionAmount>
        <cac:TaxTotal>
             <cbc:TaxAmount currencyID="SAR">0.60</cbc:TaxAmount>
             <cbc:RoundingAmount currencyID="SAR">4.60</cbc:RoundingAmount>
        </cac:TaxTotal>
        <cac:Item>
            <cbc:Name>قلم رصاص</cbc:Name>
            <cac:ClassifiedTaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>15.00</cbc:Percent>
                <cac:TaxScheme>
                    <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
            </cac:ClassifiedTaxCategory>
        </cac:Item>
        <cac:Price>
            <cbc:PriceAmount currencyID="SAR">2.00</cbc:PriceAmount>
            <cac:AllowanceCharge>
               <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
               <cbc:AllowanceChargeReason>discount</cbc:AllowanceChargeReason>
               <cbc:Amount currencyID="SAR">0.00</cbc:Amount>
            </cac:AllowanceCharge>
        </cac:Price>
    </cac:InvoiceLine>
</Invoice>
```

### Additional Sample of XML with all fields for Simplified (B2C) -

{% file src="<https://2888774781-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LZ9fXxeBEm3pJiVldcu%2Fuploads%2FNlPRfUkeaMiQ2q7QfiFc%2FUnsigned%20XML%20Sample_B2C_10th%20Jun.xml?alt=media&token=c2ea8058-aea0-420a-89b2-0179c36e70e6>" %}

### Response Status Codes

Same as [Generate E-Invoice API](https://docs.cleartax.in/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference/generating-e-invoice/generate-e-invoice). Refer to the corresponding section.

### Response Schema

Same as [Generate E-Invoice API](https://docs.cleartax.in/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference/generating-e-invoice/generate-e-invoice). Refer to the corresponding section.

### Sample Response

Same as [Generate E-Invoice API](https://docs.cleartax.in/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference/generating-e-invoice/generate-e-invoice). Refer to the corresponding section.

### API Validations

Same as [Generate E-Invoice API](https://docs.cleartax.in/cleartax-docs/e-invoicing-ksa-api/e-invoicing-ksa-api-reference/generating-e-invoice/generate-e-invoice). Refer to the corresponding section.

### 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.
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. If the auth token is valid, but the user does not have the authorization to generate device ID, then the API will return HTTP Status Code 403. The user, whose auth token is used, should have an Admin role for the particular VAT used in the request.