Generate E-Invoice (Phase I)

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 built for Phase II.

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

Parameter	Data Type	Field Validations	Description
X-Cleartax-Auth-Token	String	Cannot be empty.	Mandatory. The auth token generated from ClearTax user id and password.
Content-Type	String	Cannot be empty.	Mandatory. This will always be "application/json".
vat	String	Cannot be empty.	TIN (VAT Number) for which you are generating the E-Invoice.
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.

Request URL

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

Request Parameters

Param Name	Type	Validation	Description
EInvoice	Object		Mandatory. E-Invoice object
CustomFields	Object		Custom Fields object

Sample URL

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

Sample Request

{
    "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	Format YYYY-MM-DD, Invoice date.

• 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

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"
}

Invalid Response(400)