Send Signed E-Invoice XML To ZATCA

Send a valid signed E-Invoice XML file to ZATCA for clearance or reporting.

1.1 Request Method

POST

1.2 Request URL

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

1.3 Request Headers

1.4 Request Path Params

1.5 Request Query Params

1.6 Request Body

1.6.1 Requirement of Critical Fields

1.7 Sample Request

Request Body

Reporting Signed XML

1.8 Response Status Codes

1.9 Response Schema

1.9.1 Validation Results Object

1.9.2 infoMessages/warningMessages/errorMessages Object

1.10 Sample Response (Success with warning)

{
    "validationResults": {
        "infoMessages": [
            {
                "type": "INFO",
                "code": "XSD_ZATCA_VALID",
                "category": "XSD validation",
                "message": "Complied with UBL 2.1 standards in line with ZATCA specifications",
                "status": "PASS"
            }
        ],
        "warningMessages": [
            {
                "type": "WARNING",
                "code": "BR-KSA-37",
                "category": "KSA",
                "message": "The seller address building number must contain 4 digits.",
                "status": "WARNING"
            },
            {
                "type": "WARNING",
                "code": "BR-KSA-64",
                "category": "KSA",
                "message": "Seller Address Additional number (KSA-23) must be 4 digits.",
                "status": "WARNING"
            }
        ],
        "errorMessages": [],
        "status": "WARNING"
    },
    "clearedInvoice": null,
    "clearanceStatus": "REPORTED"
}

1.11 Sample Response (Client Error)

{
    "validationResults": {
        "infoMessages": [
            {
                "type": "INFO",
                "code": "XSD_ZATCA_VALID",
                "category": "XSD validation",
                "message": "Complied with UBL 2.1 standards in line with ZATCA specifications",
                "status": "PASS"
            }
        ],
        "warningMessages": [],
        "errorMessages": [
            {
                "type": "ERROR",
                "code": "BR-KSA-64",
                "category": "KSA",
                "message": "Seller Address Additional number (KSA-23) must be 4 digits.",
                "status": "ERROR"
            },
            {
                "type": "ERROR",
                "code": "invoiceHash_QRCODE_INVALID",
                "category": "QRCODE_VALIDATION",
                "message": "Invoice xml hash does not match with qr code invoice xml hash",
                "status": "ERROR"
            }
        ],
        "status": "ERROR"
    },
    "clearedInvoice": null,
    "clearanceStatus": "NOT_REPORTED"
}

1.12 Sample Response (Server Error) - status code 500

{
    "ErrorList": [
        {
            "ErrorCode": "30040102",
            "ErrorMessage": "Was not able to report the invoice. Please try again later",
            "ErrorSource": "CLEARTAX"
        }
    ]
}

1.13 API Validations

There are no validations from Clear for this API.

1.14 API Constraints

  1. This API needs to be authenticated with a valid user authentication token. If the Authentication token is not present or is invalid, the API will return HTTP Status Code 401.

  2. If the Authentication 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 Authentication token is used, should have an β€œAdmin” role for the particular VAT used in the request.

Last updated