Server response indicating that the Invoice is recorded on the Server

Clearance and Reporting
1

Dear All

I still don’t really understand, with the server response indicating whether my data has been recorded on the server or not. Because there is no apipath to check the invoice UUID and Approval Status from the Zatca Server.

One way to find out is to look at the Response Status code from the server when I send an Invoice.

The most difficult is the Status where the Invoice is Rejected by the server. It is difficult to determine whether I need to create a new UUID, ICV and PIH to resend the Rejected Invoice (after adjustment).

image

From the image above, which response code requires me to create a new UUID, ICV and PIH?

So far I have used NOT_REPORTED and NOT_CLEARED status as a sign that the invoice is recorded on the server and the UUID, ICV and PIH cannot be reused for subsequent invoice delivery.

Please enlighten me,
Thank you.

2

Only 200 and 202 is recorded in ZATCA servers, all others reply are not recorded.

3

Rejected Invoice By Codes 400 & 401

4

@Hadif , @Embro

Maybe I’m thinking too much.

Please explain more details for Code 401 Unauthorized.

Considering the API is open to the public. Is it possible that someone else uploaded an Invoice using my Certificate without me knowing and got Rejected?

Logically, when Unauthorized should everything sent to the server be ignored. Which means that the Invoice sent will not be received or recorded on the server and the UUID, ICV and PIH should be reusable.

5

Hi,

It’s true that API is open to public but no one should have your certificate unless you send it to them. Moreover, no one can generate a certificate on your behalf without you giving him the permission. This is the main idea of generating OTP, public key, private key, & CSR.
Regarding rejected ones, please refer to page 61 of Detailed Guidelines for E-Invoicing Version 2 which reads:
In case of Tax Invoices, if clearing fails (Response is 400 Error), then the taxpayer must submit another invoice for clearance after rectifying the errors. Please note that every document shall have its own hash and counter value. Rejected document’s hash and counter value should not be changed or updated.

Regards,

6

Dear @eCloud,

Please find the responses to the raised concernes below:

First concern: after receiving what response code should I change the UUID, ICV, invoiceHash after fixing?

you should change the UUID, ICV, invoiceHash. After fixing the errors of the rejected invoice, and this error response should be “400”.

“400” means that the invoice has been validated by fatoora platform, and failed in at least one of the validation criteria i.e (KSA business rules).

Other responses such as “401” and the rest on the table, means that fatoora platform didn’t validate the invoice yet, so there is a chance of receiving “401” for a valid invoice, because “401” indicates an issue with the username & password or both. Not an invoice rejection.

So in conclusion, you should only change UUID,ICV, invoiceHash of the rejected invoices that returned “400” code in response, after fixing.

Second concern: fatoora platform’s APIs are public, does this mean that anyone can send invoices on my behalf?

The answer is no, only solutions that are onboarded (integrated) with fatoora platform can send invoices.

1- “OTP”, in order to onboard a solution to fatoora portal, taxpayers must provide a correct" OTP" that is associated with its device that they are trying to onboard. By login to fatoora portal using TIN & password.

2- authorization credentials: each solution has its own unique username & password returned by fatoora platform after validation with OTP, no one should have the access to your authorization credentials.

3- private key: each solution has it own unique associated private key, private key is used to sign simplified tax invoices, and fatoora platform will verify the signature in submission, if the signature is not valid or someone else has signed a document that doesn’t belong to them, the document will be rejected by fatoora platform.

To get more information about securing the solutions, please refer to:

20230519_ZATCA_Electronic_Invoice_Security_Features_Implementation_Standards_vF.pdf (720.4 KB)

1 Like
7

Dear @Aturkistani ,

Thanks for the detailed explanation, this has cleared my doubts.

I note that only response 400 shows that the Rejected Request is recorded on the server side and we need a new UUID, ICV and PIH for the next delivery.

This statement also cleared up my doubts about the status of a 401.

Thank you very much.

8

Dear @eCloud ,

I am glad to hear that your doubts are cleared now

Should you require any further clarifications, please don’t hesitate to reach out.

9

Resend … means you don’t have to make change to your documents …so re-rend it again.
Resubmit …you have to ammend your error …and submit again.

when no change to your document …don’t make new ICV, UUID and PIH
while changing document …make new ICV…

10

Hi @Aturkistani ,

Just a follow up Q. When the response with 400 do we need to create a new document with new UUID, ICV and PIH or resubmit the same document in new xml composition with the corrections and new UUID, ICV and PIH?

11

Update your data in the same invoice . (document) corrections … but with a new UUID, ICV and PIH

1 Like
12

Hi @jonathanb,

regarding your follow-up question, please find the answer below:

The answer is, it doesn’t matter actually, you can update the old document with the corrections & new UUID, PIH, Hash.

Or you can create an entirely new document with, it’s totally up to you, no restrections from ZATCA side.

1 Like