Responses

This page showcases the responses for the einvoice API. The responses remains the same for either input type

200 (OK)

If the Invoice has been successfully inserted in our system. Then you will received the following response

Schema

Parameter	Value	Description
message	"Operation Successful/Unsuccessful"	Basic message returned by us
info_messages	[]	List of info messages returned by ZATCA
warning_messages	[]	List of warning messages returned by ZATCA
status	"REPORTED/NOT_REPORTED/CLEARED/NOT_CLEARED"	Reporting/Clearance Status of the invoice retunred by ZATCA
schematron_overall_status	PASS/WARNING/FAIL	over schematron status of the invoice returned by ZATCA
invoice	base64 encoded XML/None	Updated XML document. Value can be Null in case of clearance errors
qr_code	""	Raw QR code generated
icv	123	Invoice Counter Value
invoice_hash	AVBC	Invoice Hash calculated by us for the given XML
invoice_id	1	Invoice ID
invoice_uuid	484fde54-9439-453a-ae33-86b637c43c38	Invoice UUID

Sample Response

{
    "success": true,
    "message": "Invoice is being processed",
    "error_code": 0,
    "data": {
        "invoice_id": "20230619-45017",
        "invoice_uuid": "4284d025-0ca2-43a8-8ae8-ad2d44f4e6a2"
    }
}

400 Bad Request

If the application has some issues with the pre-processing of the document we will return 400. This could be the following

• Basic issues in the JSON inputs provided

• Issues in constructing the final UBL2.1 document

• Incorrect values in the generated UBL2.1 document

• If the onboarding was incomplete/not done for the taxpayer

401 (Permission Error)

If the mandatory headers are not passed then a 401 response will be returned. Additionally if the APIKey used in the system has expired then you will receive a 401 response. Format of the response is not consistent but you can fetch them from the status code and either inform us to renew the APIKey and try again.

500 Server Error

If there was an unexpected crash in the system you will receive a server error. If this error is seen please share the response to us and we will investigate from our end and see what the problem could be.

503 Service Unavailable

If the server is down and we are unable to process the document then this error would be returned. Normally this should never happen apart from scheduled maintenance phases, but they do happen please let us know.