Signing XML for Reporting

Signing process
1

I have trying to implement reporting single invoice in the web service in using php I have already done the implementation for the steps for compliance CSID, Production CSID now the next step to do is implement the /invoices/reporting/single on doing so I am facing several issues

[errorMessages] => Array
(
[0] => stdClass Object
(
[type] => ERROR
[code] => XSD_ZATCA_INVALID
[category] => XSD validation
[message] => Schema validation failed; XML does not comply with UBL 2.1 standards in line with ZATCA specifications. ERROR: org.xml.sax.SAXParseException; lineNumber: 55; columnNumber: 136; cvc-datatype-valid.1.2.1: ‘0x1100003803C5F74023B3FC5C5F000100003803’ is not a valid value for ‘integer’.
[status] => ERROR
)

                [1] => stdClass Object
                    (
                        [type] => ERROR
                        [code] => certificate-permissions
                        [category] => CERTIFICATE_ERRORS
                        [message] => User only allowed to use the vat number that exists in the authentication certificate
                        [status] => ERROR
                    )

                [2] => stdClass Object
                    (
                        [type] => ERROR
                        [code] => signed-properties-hashing
                        [category] => CERTIFICATE_ERRORS
                        [message] => Invalid signed properties hashing, SignedProperties with id='xadesSignedProperties'
                        [status] => ERROR
                    )

            )

Any help will be appreciated, Thanks

2

Dear @HishamTariq ,

Kindly note that your invoice is not compliant with XML implementation standards, please refer to E-Invoice specifications for the XML implantation standards and Data Dictionary.

And please redo the signing process steps:-

1-After submitting the Certificate Signing Request (CSR) via the Compliance Request CSID API, you will receive a BinaryToken and a secret.
2-Decode the BinaryToken using a base64 decoder. The decoded value will be the x.509 certificate.
3-Navigate to the SDK directory: SDK/Data/Certificates/Cert.pem.
4-Replace the contents of the Cert.pem file with the x.509 certificate obtained from the decoded BinaryToken.
5-Insert the newly generated private key into the ec-secp256k1-priv-key.pem file.
6-if you use JAVA SDK, run the following command: fatoora -sign -invoice “invoice.xml”.
else the .Net SDK, run the following command: fatooranet sign -invoice “invoice.xml”
7-The invoice will now be signed and can be successfully submitted during the compliance checks phase via the Compliance Invoice API.
8-Repeat the above steps using the returned PCSID from the third API in the onboarding process, sign your simplified tax invoices, and submit them to the Reporting API. Ensure the returned Binary Token is decoded using a base64 decoder, and the certificate is updated at
SDK/Data/Certificates/Cert.pem.
Thanks

3

I am not using java sdk or .net since i am developing for a webserver in laravel i have followed the same steps but I signed the document using certifacte found in the PCSID which is binarySecurityToken

4

Please know that you need to review all the Educational Library shared by ZATCA on the site, to ensure a full understanding of the integration phase.

So, as a beginner, our recommendations is to review the educational library first and start following the steps.

Please find the educational library link: Educational library (zatca.gov.sa)

Kindly review the docs carefully, and if you faced any blocker during the integration, do not hesitate to reach out via below mail.

SP mail: sp_support@zatca.gov.sa

Thanks

5

I have generated xml file and i can apply verifiation process by local sdk using fatoora which successfully passed the xml.

The xml invoice has no UBL Extension in it.

For me this is the point where i am confused to further step forward.

All i need to know is the sequence of steps that are needed to finally get invoice cleared from zatca. I need all the steps that i need to go through like sandboxing, complience and production.

Really, i got no single source that explains each and every step from zero to hero.

While going through chain of questions i found few steps you wrote in proper sequence. To me these steps are not complete because i need each and every single step required for reaching the goal.

I am expecting with great hope that you or anyone who read this question might spend a little time to complete the whole process that i need to follow next after my xml invoice is locally checked with sdk.

Please note that i have no CSID, no CSCID, no PCSID or whatever all i got is data and the generated xml file. The genrated xml file surely have no UBL Extensions in it. And please also note that i am doing this e-invoicing on behalf of someone else. I am a develper so easy part for me was to generate the xml invoice which was purely based on invoice data. So, if there are required things from my side then i can ask my friend who actually running the company will provide the detail because he has the tax resigration. Please write those as well in the steps sequence.

I would request you to write each and eveything i need next in precised steps required otherwise looking for missing step becomes a big problem sometimes.

With all the above detailed question i expect that you can get clear idea of what i am doing and what i need next.

Thanks a lot for reading this far and please do not hasitate to ask more if miising in above detail. I will be glad to get you involved.

I hope a one page soution will solve all issues if everything is in proper sequence.

6

Dear @ABCD ,

The following links are some documentation that might help you.

XML Standard and Data Dictionary: Technical requirements & Specifications
API Integration Sandbox: Zatca
Web based validator: Zatca
Developer Community: https://zatca1.discourse.group/
E-invoicing Detailed Technical Guidelines: https://zatca.gov.sa/en/E-Invoicing/Introduction/Guidelines/Documents/E-invoicing-Detailed-Technical-Guideline.pdf

You can find below the steps for the onboarding process using Java SDK:

Prepare your config file with the required info
Use “fatoora -CSR -csrConfig –[config file path]” command to generate CSR file
A CSR file will be generated
Generate the OTP from Fatoora portal or simulation portal based on the purpose of either testing or production.
Use the CSR in the body of the request using one of the below endpoints to send the request for generating the CCSID (Use the OTP in the Headers of the request):
For the simulation environment use this API URL: https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/compliance
For the production environment, use this API URL: https://gw-fatoora.zatca.gov.sa/e-invoicing/core/compliance
The response will include the BinarySecurityToken and Secret, you will use those as Authentication in the compliance checks. Moreover, the response will include request_ID which will be used in the body for generating PCSID API in a later step.
You need to start the compliance check.
In order to complete the compliance check you need to prepare your invoices. Please note that this is based on the invoice type in your configuration file if it’s 0100 that’s mean you will only send a simplified invoice, if it’s 1000 only for standard invoices and if it is 1100 you will send both standard and simplified.
For standard invoices
use “fatoora -generateHash -invoice [invoice path]” command to generate the hash
replace the generated hash in the “Digestvalue” tag in the XML
generate the JSON file for the invoice using “fatoora -invoiceRequest -invoice [invoice path]” command
For simplified invoices
make sure to change the SDK\Data\Certificates\cert.pem with the decoded CCSID
sign the invoice using “fatoora -sign -invoce [invoice path] command
generate the JSON file for the signed invoice using “fatoora -invoiceRequest -invoice [invoice path]”
After you prepared your invoices, you need to send the encoded invoices (JSON file) to one of the following APIs:
For compliance checks in the Production Environment, use this API URL. https://gw-fatoora.zatca.gov.sa/e-invoicing/core/compliance/invoices
For compliance checks in the Simulation Environment, use this API URL https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/compliance/invoices
In order to generate the PCSID, take the “Request ID” you got from the CCSID response (on step 6 above)and replace it in the body of the request.
Make sure to send an invoice, credit note, and debit note to the compliance check, to avoid “Missing Compliance Steps”
Now you need to generate the PCSID using one of the following APIs in the body use the request_ID and in authentications use the BinarySecurityToken as user name, secret as password:
For Simulation Environment: https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/production/csids
For Production Environment: https://gw-fatoora.zatca.gov.sa/e-invoicing/core/production/csids

Thanks

7

Alright, that seems good start. Thanks a lot for making that check list.

1 Like
8

Hello @HishamTariq,
I saw your post on the ZATCA Developer Community Portal regarding signing the document using the certificate found in the PCSID (binarySecurityToken).

I wanted to ask if you managed to resolve this issue. I am developing on a web server using Laravel and facing the same error. If you have resolved this issue, could you please share some details? It would be really helpful. Thanks!

9

Dear @waqas.mehmood

Thank you for reaching out and welcome to the community.

We highly recommend that you read the following below documentation links that might help you in the beginning.

XML Standard and Data Dictionary: Technical requirements & Specifications
API Integration Sandbox: Zatca
Web based validator: Zatca
Developer Community: https://zatca1.discourse.group/
E-invoicing Detailed Technical Guidelines: https://zatca.gov.sa/en/E-Invoicing/Introduction/Guidelines/Documents/E-invoicing-Detailed-Technical-Guideline.pdf

Also, if you are using ZATCA published tools (JAVA SDK), kindly find below the steps for the onboarding process:

Prepare your config file with the required info
Use “fatoora -CSR -csrConfig –[config file path]” command to generate CSR file
A CSR file will be generated
Generate the OTP from Fatoora portal or simulation portal based on the purpose of either testing or production.
Use the CSR in the body of the request using one of the below endpoints to send the request for generating the CCSID (Use the OTP in the Headers of the request):
For the simulation environment use this API URL: https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/compliance
For the production environment, use this API URL: https://gw-fatoora.zatca.gov.sa/e-invoicing/core/compliance
The response will include the BinarySecurityToken and Secret, you will use those as Authentication in the compliance checks. Moreover, the response will include request_ID which will be used in the body for generating PCSID API in a later step.
You need to start the compliance check.
In order to complete the compliance check you need to prepare your invoices. Please note that this is based on the invoice type in your configuration file if it’s 0100 that’s mean you will only send a simplified invoice, if it’s 1000 only for standard invoices and if it is 1100 you will send both standard and simplified.
For standard invoices
use “fatoora -generateHash -invoice [invoice path]” command to generate the hash
replace the generated hash in the “Digestvalue” tag in the XML
generate the JSON file for the invoice using “fatoora -invoiceRequest -invoice [invoice path]” command
For simplified invoices
make sure to change the SDK\Data\Certificates\cert.pem with the decoded CCSID
sign the invoice using “fatoora -sign -invoce [invoice path] command
generate the JSON file for the signed invoice using “fatoora -invoiceRequest -invoice [invoice path]”
After you prepared your invoices, you need to send the encoded invoices (JSON file) to one of the following APIs:
For compliance checks in the Production Environment, use this API URL. https://gw-fatoora.zatca.gov.sa/e-invoicing/core/compliance/invoices
For compliance checks in the Simulation Environment, use this API URL https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/compliance/invoices
In order to generate the PCSID, take the “Request ID” you got from the CCSID response (on step 6 above)and replace it in the body of the request.
Make sure to send an invoice, credit note, and debit note to the compliance check, to avoid “Missing Compliance Steps”
Now you need to generate the PCSID using one of the following APIs in the body use the request_ID and in authentications use the BinarySecurityToken as user name, secret as password:
For Simulation Environment: https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/production/csids
For Production Environment: https://gw-fatoora.zatca.gov.sa/e-invoicing/core/production/csids

Thank you!