# Generate E-Invoice (Phase I)

{% hint style="warning" %}
**A new version is available!**

This API is valid only for Phase I requirements of ZATCA. In case you are implementing for Phase II, use the latest [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) built for Phase II.
{% endhint %}

You can generate the E-Invoice by sending a **`POST`** request to E-Invoicing KSA API.

#### **Request Headers**

```
x-cleartax-auth-token: {{USER_AUTH_TOKEN}}
Content-Type: application/json
owner_id: {{OWNER_ID}}
vat: {{VAT}}
```

<table><thead><tr><th width="192.00000000000003">Parameter</th><th>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. The auth token generated from ClearTax user id and password.</td></tr><tr><td>Content-Type</td><td>String</td><td>Cannot be empty.</td><td>Mandatory. This will always be <br>"application/json".</td></tr><tr><td>vat</td><td>String</td><td>Cannot be empty.</td><td>TIN (VAT Number) for which you are generating the E-Invoice.</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></tbody></table>

#### **Request URL**

```
POST: https://api-demo.cleartax.com/middle-east/ksa/einvoicing/v2/einvoices/generate
```

#### **Request Parameters**

<table><thead><tr><th>Param Name</th><th width="256.88562596599695">Type</th><th width="168">Validation</th><th>Description</th></tr></thead><tbody><tr><td>EInvoice</td><td>Object</td><td></td><td>Mandatory. <a href="../resources-and-masters/e-invoice-object">E-Invoice object</a></td></tr><tr><td>CustomFields</td><td>Object</td><td></td><td>Custom Fields object</td></tr></tbody></table>

#### **Sample URL**

```
POST: https://api.cleartax.com/v2/einvoices/generate
```

#### Sample Request

```json
{
    "EInvoice": {
        "UBLVersionID": "2.1",
        "ProfileID": "reporting:1.0",
        "ID": {
            "en": "K01082K5",
            "ar": "K01082K5"
        },
        "InvoiceTypeCode": {
            "name": "0101000",
            "value": "388"
        },
        "IssueDate": "2021-08-14",
        "IssueTime": "15:44:20",
        "Delivery": [
            {
                "ActualDeliveryDate": "2021-08-14",
                "LatestDeliveryDate": "2021-08-14"
            }
        ],
        "BillingReference": [
            {
                "InvoiceDocumentReference": {
                    "ID": {
                        "ar": "string",
                        "en": "156166151"
                    }
                }
            }
        ],
        "OrderReference": {
            "ID": {
                "ar": "string",
                "en": "161313031"
            }
        },
        "ContractDocumentReference": [
            {
                "ID": {
                    "ar": "string",
                    "en": "161313031"
                }
            }
        ],
        "DocumentCurrencyCode": "SAR",
        "TaxCurrencyCode": "SAR",
        "AccountingSupplierParty": {
            "Party": {
                "PartyLegalEntity": {
                    "RegistrationName": {
                        "en": "Gulf Arabian Equipment Co",
                        "ar": "شركة الخليج العربية للمعدات"
                    }
                },
                "PartyTaxScheme": {
                    "CompanyID": "310387374800003",
                    "TaxScheme": {
                        "ID": "VAT"
                    }
                },
                "PartyIdentification": {
                    "ID": {
                        "value": "312345678914443",
                        "schemeID": "CRN"
                    }
                },
                "PostalAddress": {
                    "StreetName": {
                        "en": "Abdelrahman Road",
                        "ar": "طريق عبد الرحمن"
                    },
                    "AdditionalStreetName": {
                        "en": "",
                        "ar": ""
                    },
                    "BuildingNumber": {
                        "en": "2021",
                        "ar": "2021"
                    },
                    "PlotIdentification": {
                        "en": "2347",
                        "ar": "2347"
                    },
                    "CitySubDivisionName": {
                        "en": "Abqaiq",
                        "ar": "بقيق"
                    },
                    "CityName": {
                        "en": "Al-Baḥah",
                        "ar": "الباءة"
                    },
                    "PostalZone": "33502",
                    "CountrySubentity": {
                        "en": "Al-Jawf",
                        "ar": "الجوف"
                    },
                    "Country": {
                        "IdentificationCode": "SA"
                    }
                }
            }
        },
        "AccountingCustomerParty": {
            "Party": {
                "PartyLegalEntity": {
                    "RegistrationName": {
                        "en": "AL Amal Specialized Hospital",
                        "ar": "مستشفى الامل التخصصى"
                    }
                },
                "PartyTaxScheme": {
                    "CompanyID": "300761193700003",
                    "TaxScheme": {
                        "ID": "VAT"
                    }
                },
                "PartyIdentification": {
                    "ID": {
                        "value": "300761193710003",
                        "schemeID": "NAT"
                    }
                },
                "PostalAddress": {
                    "StreetName": {
                        "en": "Abdelrahman Road",
                        "ar": "طريق عبد الرحمن"
                    },
                    "AdditionalStreetName": {
                        "en": "",
                        "ar": ""
                    },
                    "BuildingNumber": {
                        "en": "2119",
                        "ar": "2119"
                    },
                    "PlotIdentification": {
                        "en": "2345",
                        "ar": "2345"
                    },
                    "CitySubDivisionName": {
                        "en": "Abqaiq",
                        "ar": "بقيق"
                    },
                    "CityName": {
                        "en": "Khobhar",
                        "ar": "الخبر"
                    },
                    "PostalZone": "31952",
                    "CountrySubentity": {
                        "en": "Riyadh",
                        "ar": "الرياض"
                    },
                    "Country": {
                        "IdentificationCode": "SA"
                    }
                }
            }
        },
        "InvoiceLine": [
            {
                "ID": "1",
                "Item": {
                    "Name": {
                        "en": "Cable",
                        "ar": "كابل"
                    },
                    "ClassifiedTaxCategory": {
                        "ID": "S",
                        "Percent": "15",
                        "TaxScheme": {
                            "ID": "VAT"
                        }
                    }
                },
                "Price": {
                    "PriceAmount": {
                        "currencyID": "SAR",
                        "value": "9000"
                    },
                    "BaseQuantity": {
                        "unitCode": "MTR",
                        "value": "10"
                    },
                    "AllowanceCharge": 
                        {
                            "ChargeIndicator": "false",
                            "BaseAmount": {
                                "currencyID": "SAR",
                                "value": "10000"
                            },
                            "Amount": {
                                "currencyID": "SAR",
                                "value": "1000"
                            }
                        }
                    
                },
                "InvoicedQuantity": {
                    "unitCode": "MTR",
                    "value": "10"
                },
                "AllowanceCharge": [
                    {
                        "ChargeIndicator": "false",
                        "BaseAmount": {
                            "currencyID": "SAR",
                            "value": "9000"
                        },
                        "MultiplierFactorNumeric": "10",
                        "Amount": {
                            "currencyID": "SAR",
                            "value": "900"
                        },
                        "AllowanceChargeReason": {
                            "ar": "خصم",
                            "en": "Discount"
                        },
                        "AllowanceChargeReasonCode":null
                    }
                ],
                "LineExtensionAmount": {
                    "currencyID": "SAR",
                    "value": "8100"
                },
                "TaxTotal": {
                    "TaxAmount": {
                        "currencyID": "SAR",
                        "value": "1215"
                    },
                    "RoundingAmount": {
                        "currencyID": "SAR",
                        "value": "9315"
                    }
                }
            }
        ],
        "AllowanceCharge": [
            {
                "BaseAmount": {
                    "currencyID": "SAR",
                    "value": "10000"
                },
                "MultiplierFactorNumeric": "5",
                "Amount": {
                    "currencyID": "SAR",
                    "value": "500"
                },
                "TaxCategory": {
                    "ID": "S",
                    "Percent": "15",
                    "TaxScheme": {
                        "ID": "VAT"
                    }
                }
            }
        ],
        "TaxTotal": [
            {
                "TaxAmount": {
                    "currencyID": "SAR",
                    "value": "1140"
                },
                "TaxSubtotal": [
                    {
                        "TaxableAmount": {
                            "currencyID": "SAR",
                            "value": "7600"
                        },
                        "TaxAmount": {
                            "currencyID": "SAR",
                            "value": "1140"
                        },
                        "TaxCategory": {
                            "ID": "S",
                            "Percent": "15",
                            "TaxScheme": {
                                "ID": "VAT"
                            }
                        }
                    }
                ]
            }
        ],
        "LegalMonetaryTotal": {
            "LineExtensionAmount": {
                "currencyID": "SAR",
                "value": "8100"
            },
            "AllowanceTotalAmount": {
                "currencyID": "SAR",
                "value": "500"
            },
            "TaxExclusiveAmount": {
                "currencyID": "SAR",
                "value": "7600"
            },
            "TaxInclusiveAmount": {
                "currencyID": "SAR",
                "value": "8740"
            },
            "PrepaidAmount": {
                "currencyID": "SAR",
                "value": "0"
            },
            "PayableAmount": {
                "currencyID": "SAR",
                "value": "8740"
            }
        },
        "PaymentMeans": [
            {
                "PaymentMeansCode": "10",
                "InstructionNote": {
                    "en": "10",
                    "ar": ""
                },
                "PayeeFinancialAccount": {
                    "PaymentNote": {
                        "en": "",
                        "ar": ""
                    }
                }
            }
        ]
    },
    "CustomFields": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
    }
}
```

#### **Response Parameters**

* For Successful request you will receive a response with HTTP Status 200 with the below schema.

| Parameter       | Type   | Description                                                  |
| --------------- | ------ | ------------------------------------------------------------ |
| QRCode          | String | Rendered QR Code image in base64encoded PNG format.          |
| RawQRCode       | String | QR Code payload in base64encoded TLV format.                 |
| SellerVatNumber | String | Seller VAT identification number.                            |
| BuyerVatNumber  | String | Buyer VAT identification number.                             |
| Status          | String | "Generated" if the request is successful.                    |
| InvoiceType     | String | Document Type: INV-INVOICE, CRN-CREDIT NOTE, DBN-DEBIT NOTE. |
| InvoiceNumber   | String | Invoice number.                                              |
| InvoiceDate     | String | <p>Format YYYY-MM-DD, </p><p>Invoice date.</p>               |

* For Failed request you will receive a response with HTTP Status 400 with the below schema.

| Parameter | Type                  | Description           |
| --------- | --------------------- | --------------------- |
| ErrorList | Array of Error Detail | Details of all errors |

#### Error Details

| Parameter    | Type   | Description               |
| ------------ | ------ | ------------------------- |
| ErrorCode    | String | Error Code                |
| ErrorMessage | String | Error Message             |
| ErrorSource  | String | Error Source              |
| Path         | String | Field name throwing error |

####

#### Sample Response

{% tabs %}
{% tab title="Valid Response(200)" %}

```
{
    "QRCode": "iVBORw0KGgoAAAANSUhEUgAAAcIAAAHCAQAAAABUY/ToAAACu0lEQVR4Xu2YQW7sMAxDDfQAOVKuPkfKAQq4JinFsZOpP7r7GHLhxBKfuiHsTEv9o15lrvyrTK5kciWTK5lcyeRKJlcyudJ/SZbQl6plr9/atje4trbdj3SpZtLkQHJTD1gP4t8Ry5dwbNVIs0mTE4loBQSdLiWydTX3kkiTapicyQJdSLiGrkmTCzJuvLOm9FEmTf5K9t7GNwxCQ+Q5t5tNmhzJEKIF/HlJl8l3yyeTF72EwwD/GMbBN+5NfjhZKPphJdTuQxp6o/2swx1p0uQDqQqsgvBfAb7FacUZWNQwafKJ5CYyl0mLmrLZA2rS5J3sx5PKrO0VNUzTtkHZqCZlMHkhGbwzfQyZpqkRunxTmTQ5kBW3m548t84acQ0aw2gyaiYzfSgXfkT19O1oRCwLICwcZNLkA6lvcFQ25hALvsaVPjX4F2IxaXIiYahxPDUrhUQyc5zLUlpMmpxJ4TuWcsEjfbktkUj4TJocSW0q7j756eIgnVvAjxxp0uQDyczxniMZX1IRQY3UcJhNmryT7UlDuPJzCi7UXpggZcOkyZk8Dyq4iF/ThxlQ/AWTJm9kugBp0DV9vSHfbtLkOxJ+5Qv+8/DKow012k2avJGVdx/PrcKzjNbKQazlyDjpTJqcSfYCYhlbvKWraedwpNSkyQcScWtdZE5vcOkE47mVOcSbSZPPZLPieJJfNfmTrLmYNPlI8nEwdrDyjacaEklc6oecSZNXsitmUAPORl9MQiZrT1+IwevpYwPpAx4XZZlOMJMmRXJTW0+Zw7WnpJ1H1rSYNDmT9Ctfmb4wnGGEYJFMmnxH0s+Pbs2ga8PaLBwkmTQp3ck4svjrjQbghLbnX3QmTYrkQyQMHIQGIhhb4N1s0uRIhkBm3NLA7Ve+3dJn0iTJP8jkSiZXMrmSyZVMrmRyJZMrfQz5A8JgUny/HLvzAAAAAElFTkSuQmCC",
    "RawQRCode": "ARlHdWxmIEFyYWJpYW4gRXF1aXBtZW50IENvAg8zMDA0NTk4MDM4MDAwMDMDEzIwMjEtMDgtMTQgMTU6NDQ6MjAEBDg3NDAFBDExNDA=",
    "SellerVatNumber": "300459803800003",
    "BuyerVatNumber": "300761193700003",
    "Status": "GENERATED",
    "InvoiceType": "INV",
    "InvoiceNumber": "K01082K5",
    "InvoiceDate": "2021-08-14"
}
```

{% endtab %}

{% tab title="Invalid Response(400)" %}

```
{
    "ErrorList": [
        {
            "ErrorCode": "6002",
            "ErrorMessage": "Invalid value for the field EInvoice.TaxTotal. Send the correct the value and try again",
            "ErrorSource": "CLEARTAX",
            "Path": "EInvoice.TaxTotal"
        }
    ]
}
```

{% endtab %}
{% endtabs %}