Hello,
Now I am at the beginning of send invoices with platform
I need steps to start obtaining the username and password generated binarySecurityToken and secret that I will use to send the invoice.
How can I extract and use the CSR certificate?
Thank you all.
Hi @ahmedtaher ,
Thank you for reaching out,
Kindly find below the process for onboarding using JAVA SDK.
- Download the SDK through this link here
- Prepare your configuration file in SDK/Data/Input directory, you can refer to Technical Guideline, 3.3.3. Sending a Certificate Signing Request (CSR) in order to receive a Compliance CSID section for more information regarding the CSR input
- Open CMD in the above file Path and run CSR generation command depending on which environment you want to generate CSR for.
-
For Production:
Fatoora -csr -csrConfig “Properties file.properties” -
For Simulation:
Fatoora -sim -csr -csrConfig “Properties file.properties”
- You need to send the generated CSR to Compliance CSID API, you will include the generated CSR in the request body along with an OTP (obtained from Fatoora portal), and Accept-Version with value “V2” in the headers.
The response will be similar to the below:
-
RequestId:
will be submitted in the PCSID generation API, it’s a unique ID for each compliance CSID. -
BinarySecurityToken
This is the Compliance certificate encoded in base64 and to use it to sign the invoices (simplified) and generate a hash (standard). You first need to decode it and put it in the cert.pem file of SDK found in SDK/Data/Certificates folder
NB: after the Token is decoded it will be in X509Certificate format.
Also, this token will be used as it is encoded in base64 as username in authorization as Basic Auth in the next 2 APIs (Compliance check, PCSID generation API). -
Secret
This one will be used as a password in authorization as Basic Auth in the next 2 APIs (Compliance check, PCSID generation API).
- Now you can start the Compliance Check, in the compliance check steps, you need to submit sample invoices. in this steps, you will either send 3 invoices or 6 invoices based on invoiceType filed in the configuration file.
- If the value is 1000 => You will send standard invoices (standard invoice, standard credit, standard debit).
- if the value 0100 => You will send simplified invoices (simplified invoice, simplified credit, simplified debit).
- If the value 1100 => You will send standard and simplified invoices(standard invoice, standard credit, standard debit, simplified invoice, simplified credit, simplified debit).
NB: You can use sample invoices from SDK/Data/Samples.
before sending the invoices you need to sign the simplified invoice first using this command:
Fatoora -sign -invoice “invoice.xml”
This will generate new invoice file with suffix “_signed” has new QR, Hash & signature tags.
and for standards invoices you need to generate hash using this command:
Fatoora -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.
Now you need to send the request, in the Authorization Tab, we will use the BinarySecurityToken & secret obtained from the previous steps.
Headers:
And the body will be the invoice itself
To convert the XML file to JSON you can do so using this command
Fatoora -invoiceRequest -invoice “invoice.xml”
- After completing the compliance checks, you now need to generate Production CSID. In order to do so, you need to send the requestID returned from CCSID API mentioned in the fourth step in the body.
Headers:
In Authorization (the BinarySecurityToken and secret returned from first API)
In the response you will get the BinarySecurityToken and Secret, and you will use it to submit invoices to ZATCA.
-Below are more references that might help you:
- Educational Library
- Developer Portal
- and you can find the endpoints in Fatoora portal
Thankyou @lalomar for replay
now after generate csr by sdk and call compliance api get binarySecurityToken and secret but when use it in Header Authorization reporting invoice api get 401 not authorized
i’m tried base64_encode(binarySecurityToken . secret) and base64_encode(binarySecurityToken . ‘:’ . secret) and binarySecurityToken . ‘:’ . secret but all attempts failed.
You should use the BinarySecurityToken and Secret as it is without encoding in the Authorization of your request, with Basic Auth
$headerData = array(
'Authorization: Basic ' . $binarySecurityToken . ':' . $secret,
'Accept-Version: V2',
'Accept-Language: en',
'Clearance-Status: 0',
'Content-Type: application/json'
);
But get 401, decoded by base64 also get 401
Can you please check the below:
1- CSR Request : Double-check that you’ve used the correct command to configure the CSR (Certificate Signing Request) based on the environment you intend to use.
-
Using the SDK and config.properties to generate the CSR :
Simulation portal commad :
fatoora -sim -csr -csrConfig "configfile.properties path file"
Fatoora portal command:
fatoora -csr -csrConfig "configfile.properties path file"
-
Using openssl and config.cnf file to generate the CSR:
the config.cnf file in Simulation should contain :
certificateTemplateName = ASN1:PRINTABLESTRING:PREZATCA-Code-Signing
the config.cnf file in Fatoora should contain :
certificateTemplateName = ASN1:PRINTABLESTRING:ZATCA-Code-Signing
2- API Endpoint: Ensure that you are using the correct APIs for the correct Environment you want to use.
e.g :
If using Simulation Env, use the Simulation portal to get the OTP and Simulation APIs to get the CCSID and PCCSID
3- Valid Credentials: Ensure that you are using the correct credentials for the correct environment for example you should not use the Simulation Certificates on production and vice versa.
Please let us know if you have verified all of the above and still encountering the “401 Unauthorized” error.