HTTP Response (errors)

Clearance and Reporting
1

##Clearance and Reporting single API###

● “202- Accepted with Errors, clearance invoice/simplified invoice accepted with warning errors”

– If we want to fix the erro/warning, do we resend the document with the same ICV/Hash to zatca or create a new ICV/Hash for the document and send it?

● “303- HTTP See Other. Returned when the submitted invoice is a Standard Invoice while clearance is activated”
“400- HTTP Bad Request. Returned when the submitted request is invalid”
“500- HTTP Internal Server Error. Returned when the service faces internal errors”

– Do we fix the issue and resend the document with the same ICV/Hash to zatca or create a new ICV/Hash for the document and send it?

2

Hi @ptorpes ,

for 202 error which is “accepted with warnings”, you shouldn’t re-submit the invoices becuase it’s actually accepted by ZATCA, what you have to do is to fix your invoices so they be fully compliant with zatca’s requirments.

if the invoice is rejected, after fixing the errors, you have to submit it with a new UUID, hash & ICV, the taxpayer’s system should assign a new values for those unique identifiers, and the PIH should be linked with the last immediately preceding document.

so if the last submitted document was the rejected one then the PIH should be the IH of this invoice.
or
if the last submitted document was an accpeted one then the PIH should be the IH of this invoice also.

So previous Invoice Hash will be based on immediately preceding document (not necessarily linked to the rejected invoice).

3

Response - “303”

  • In this response we resend the document fixed and maintain the original communication?

Example:
Document 2, icv 2, PIH 1 — (CLEARED)
Document 3, icv 3, PIH 2 — (communication with 303)
Document 4, icv 4, PIH 3 — (CLEARED)
Document 3, icv 5, PIH 4 — (new communication with correction)

Response - “401/428”

  • In this responses we maintain the original communication and resend as new?

Example:
Document 2, icv 2, PIH 1 — (CLEARED)
Document 3, icv 3, PIH 2 — (communication with “401/428”)
Document 4, icv 4, PIH 3 — (CLEARED)
Document 3, icv 5, PIH 4 — (new communication)

Response - “413/429/500/503/503/504”

  • In this responses we resend the documents as new communication and ignore the communication with error?

Example:
Document 2, icv 2, PIH 1 — (CLEARED)
Document 3, icv 3, PIH 2 — (communication with “413/429/500/503/503/504”)
Document 4, icv 3, PIH 2 — (CLEARED)
Document 3, icv 4, PIH 3 — (new communication)

Overview of responses and required actions

“303 Clearance switched off”
Please submit via reporting

“401 Unauthorized “
Check authentication certificate and secret and resubmit

“413 Payload Too Large, invoice not received”
Please resend with smaller payload (invoice)

“428 CCSID renewed but not compliant”
CCSID renewed but not compliant yet, because it’s missing invoice compliance check.

  1. The compliance certificate (CCSID) returned in the response is the renewed initial certificate.
  2. Use the renewed certificate (CCSID) in the onboarding process again by sending the invoices to the compliance check API.
  3. Generate new production CSID (PCSID) : the final certificate to be used in submitting invoices to clearance and reporting APIs.

“429 Too Many Requests, invoice not received”
Please resend

“500 Internal Server Error, invoice not received”
Please resend

“503 Service Unavailable, invoice not received”
Please resend

“504 Request Timed Out, invoice not received”
Please resend

1 Like
4

Is this the correct flow of updating ICV and PIH that we have to follow ? Is this the official response ?

5

Dear @shiyaf_texol

if the invoice got rejected, PIH, ICV, UUID, HASH should be updated after correction.

But if you mean to change the ICV/PIH sequence of the device, then NO. This sequence should never be changed, only if the same device has been revoked & onboarded again, then you can reset it.

thank you,