Integration with Zatca

SDK, web-based validator and sandbox
1

السلام عليكم,
اريد شرح كامل لكيفية الربط مع هيئة الزكاة والدخل انا استخدم
sdk3.3.4(.net)
I generate csr, private key, public key ,BinaryTokenSecurity-Secret as Basic Autho, x509Certificate.
لها ؟Signing Process هل اقوم بعمل , simplified Signed Invoice الان اقوم بعمل
To Sign << fatooranet sign -invoice "invoice.xml أم أستخدم هذا
To Hash << fatooranet invoiceRequest -invoice "SignedInvoiceName.xml” وثم هذا
لا استطيع فهم ترتيب الخطوات بشكل صحيح , ارجو التوضيح

2

Hi @Madleen ,

I am assuming that you are asking about the signing process, and generating hash process. Please note that you can sign the invoices and generate the hash using the SDK.
Generating the hash process is applied for standards invoices. you can generate the hash using this command:
Fatooranet -generateHash -invoice “invoice.xml”
You will have to take the hash value from the CLI and replace the first digest value in the invoice with the new generated Hash.

Unlike standard tax invoice, simplified tax invoice & its associated notes must be signed with the taxpayer X.509 certificate (CSID), there are 2 returned X.509 certificates in the taxpayer’s EGS onboarding process.

First X.509 certificate: CCSID, which is returned after completing the first API (Compliance CSID), It’s returned as a security binary token which will be used as a username in the authorization, it’s also used as a signing certificate (X.509) after we decode it using base64 (we decode the binarysecurityToken) using base64 decoder and the output is the X.509 certificate, we use this certificate to sign the simplified tax invoices in the compliance invoice API (Compliance checks phase).

Second X.509 Certificate: PCSID, which is returned after completing the third API on the onboarding process (Production CSID), it’s also returned as a binary security token, and will be used as the username in te authorization for both reporting & clearance API, it’s also used as a signing certificate (X.509) after we decode it using base64 (we decode the binarysecurityToken) using base64 decoder and the output is the X.509 certificate, we use this certificate to sign the simplified tax invoices in the reporting API.

Please refer to the steps of manual signing using ZATCA’s JAVA SDK below:

  1. After sending the CSR in the Compliance request CSID API, a Binarytoken & secret will be returned
  2. Take the Binarytoken output, and decode it using base64 decoder, the decoded value is the x.509 certificate
  3. Go to the SDK file to the following path: SDK/Data/Certificates/Cert.pem
  4. Replace the value with your obtained x.509 certificate
  5. Go to the SDK and use the command: fatooranet -sign -invoice “invoice.xml”
  6. Now the invoice will be signed & can be submitted successfully in the compliance checks phase (Compliance invoice API)
  7. Redo the same steps above with the returned PCSID from the third API in the onboarding process and sign your simplified tax invoices with before sending to Reporting API

If you are implementing the signing process in your own code, please refer to This document:
SigningProcessUpdated.pdf (392.7 KB)

If you require any additional support other than the mentioned steps above, please do not hesitate to reach out.

3

Dear @lalomar ,
Why does your response lack clarification? I’ve read answers to similar questions, but yours doesn’t clarify anything or help with my question. Please make your answer more clear.

4

can you please clarify your question? are you asking about generating hash or signing the invoice? because the signing process will automatically generate the hash. From what I understand, I think you are aiming to send a simplified invoice. Therefore you can follow the signing process I mentioned and no need to generate the hash as the signing process will generate the hash. However, if you are going to send a standard invoice then you need to generate the hash and you can follow the generate hash process I mentioned.

5

Dear @lalomar ,
I would like to understand the steps involved in signing both Simplified and Standard invoices. Could you please clarify the process?

Additionally, I would appreciate it if you could specify when I should use the following commands:

  • fatooranet sign -invoice "invoice.xml"
  • fatooranet invoiceRequest -invoice "SignedInvoiceName.xml"

For reference, I am using SDK version 3.3.4 (.NET). Thank you!

6

Dear @Madleen ,

kindly note that you are not required to sign the standard invoices as ZATCA will sign it for you. However, you need to generate the hash to the standard invoice using this command: Fatooranet -generateHash -invoice “invoice.xml"
then, you will have to take the generated hash value and replace the first digest value tag in the XML.

Unlike standard tax invoices, simplified tax invoices & its associated notes must be signed with the taxpayer X.509 certificate. Below is the manual process of signing the simplified invoices using ZATCA’s .Net SDK:

  1. After sending the CSR in the Compliance request CSID API, a Binarytoken & secret will be returned
  2. Take the Binarytoken output, and decode it using base64 decoder, the decoded value is the x.509 certificate
  3. Go to the SDK file to the following path: SDK/Data/Certificates/Cert.pem
  4. Replace the value with your obtained x.509 certificate
  5. Go to the SDK and use the command: fatooranet -sign -invoice “invoice.xml”
  6. Generate the request body using this command: * fatooranet invoiceRequest -invoice "SignedInvoiceName.xml"
  7. Now the invoice is signed & the JSON request body is generated. You can submit it successfully in the compliance checks phase (Compliance invoice API)
  8. Once you complete the compliance check phase, you need to generate the Production CSID. In this step, you will get a BinarySecurityToken & Secret from the API response. Redo the same steps above, Take the Binarytoken output, and decode it using base64 decoder then go to the SDK file to the following path: SDK/Data/Certificates/Cert.pem and replace the decoded value.

Lastly, you asked about the sign command * fatooranet sign -invoice "invoice.xml" and invoice request command * fatooranet invoiceRequest -invoice "SignedInvoiceName.xml". Kindly note that you will use the sign command as explained above to sign the simplified invoices. And you can use the invoice request command whenever you need to generate the invoice JSON request body to send it to the API.

I hope this clarify your concerns.

BR,