Transitioning from Sandbox to Simulation Environment: Handling CSR and Compliance API with ZATCA

I’ve moved from the sandbox to the simulation environment to test my code, and everything worked fine in the sandbox—from CSR generation to the compliance check API. In the simulation environment, I generated the CSR and sent a request to the compliance API. My question is: during CSR generation, should actual information (like VAT number, custom_id, etc.) be used in OpenSSL instead of dummy data? My goal is to successfully receive the requestID, binarySecurityToken, and secret from the compliance API.

I suspect that using dummy data during CSR generation may be causing issues, as I’m encountering the following error in the compliance API response within the simulation environment:

Note: I already have a valid OTP from the Fatoora portal, active for one hour.

For reference, I followed the steps outlined on pages 17 to 20 in this guide:
https://zatca.gov.sa/en/E-Invoicing/Introduction/Guidelines/Documents/Fatoora_Portal_User_Manual_English.pdf

Error Response:

{#1330 ▼ // app/Zatca/API.php:48
  +"errors": array:1 [▼
    0 => {#1329 ▼
      +"code": "Invalid-OTP"
      +"message": "The provided OTP is invalid"
    }
  ]
}

Environment: PHP, Laravel.

API URL in use:
https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/compliance

Would using accurate information resolve this issue? If so, which information is required when generating the CSR certificate?

Dummy Information which I am passing:

$egs_unit = [
    'uuid' => '6f4d20e0-6bfe-4a80-9389-7dabe6620f12',
    'custom_id' => 'EGS1-886431145',
    'model' => 'IOS',
    'CRN_number' => '454634645645654',
    'VAT_name' => 'Wesam Alzahir',
    'VAT_number' => '399999999900003',
    'location' => [
        'city' => 'Khobar',
        'city_subdivision' => 'West',
        'street' => 'King Fahahd st',
        'plot_identification' => '0000',
        'building' => '0000',
        'postal_zone' => '31952',
    ],
    'branch_name' => 'My Branch Name',
    'branch_industry' => 'Food',
    'cancelation' => [
        'cancelation_type' => 'INVOICE',
        'canceled_invoice_number' => '',
    ],
];

Yes we need real vat number for simulation environment, and login to fatoora simulation portal with same vat number to get an OTP.

If you use OpenSSL to generate CSR, then make sure change this value in config.cnf

[req_ext]
certificateTemplateName = ASN1:PRINTABLESTRING:TSTZATCA-Code-Signing
subjectAltName = dirName:alt_names
switch ($environmentType) {
            case 'NonProduction':
                $asnTemplate = 'TSTZATCA-Code-Signing';
                break;
            case 'Simulation':
                $asnTemplate = 'PREZATCA-Code-Signing';
                break;
            case 'Production':  
                $asnTemplate = 'ZATCA-Code-Signing';
                break;
        }

If you use Zatca eInvoice SDK to generate CSR then make sure you add -sim flag parameter in cli command.

Dear @hassan.fayyaz

Thanks for reaching out,

Please find the below sample of the .cnf file you can replace it with your actual data


oid_section = OIDs
[ OIDs ]
certificateTemplateName= 1.3.6.1.4.1.311.20.2

[ req ]
default_bits=
emailAddress=
req_extensions=
x509_extensions=
prompt = no
default_md = sha256
req_extensions = req_ext
distinguished_name = dn

[ dn ]
C=SA
OU=
O=ElSEIF COM
CN = integr

[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment

[req_ext]
certificateTemplateName = ASN1:PRINTABLESTRING:PREZATCA-Code-Signing
subjectAltName = dirName:alt_names

[alt_names]
SN=1-AB|2-89|3-14142328-e6a2
UID=
title=0100
registeredAddress=splonline.com.sa
businessCategory=EL SEIF ENGINEERING CONTRACTING CO

Please note that (ASN1:PRINTABLESTRING:PREZATCA-Code-Signing) in certificateTemplateName refer to which environment you want to generate the CSR (PREZATCA-Code-Signing) refer to simulation Env, (ZATCA-Code-Signing) this mean the generated CSR is for production Env.

From the error you are receiving (The provided OTP is invalid) make sure that you are getting the OTP from the right portal, as mentioned above If you are using (ASN1:PRINTABLESTRING:PREZATCA-Code-Signing) as (certificateTemplateName) in your .cnf file, then you need to get the OTP from fatoora simulation portal, not fatoora portal (this where you get the OTP for production env).

For any further support, do not hesitate to reach out.

Thanks,
Ibrahem Daoud.

Dear,

For Simulation portal, we are trying to generate the CCSID using the power shell script. and getting the error response.

CSRCONFIG

oid_section = OIDs
[OIDs]
certificateTemplateName = 1.3.6.1.4.1.311.20.2
[req]
default_bits = 2048
emailAddress = abgzakat@abg.com.sa
req_extensions = v3_req
x509_extensions = v3_ca
prompt = no
default_md = sha 256
req_extensions = req_ext
distinguished_name = dn
[dn]
C=SA
OU=Headoffice
O=Al Blagha Industrial Company
CN=PREZATCA-Code-Signing
[v3_req]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment
[req_ext]
certificateTemplateName = ASN1:PRINTABLESTRING:PREZATCACode-Signing
subjectAltName = dirName:alt_names
[alt_names]
SN=1-TST|2-TST|3-6ec77209-b72f-4a28-901d-4573d6d04bdc
UID=300049785700003
title=1100
registeredAddress=Riyadh
businessCategory=Service

Dear @muthusamycse

Thanks for reaching out, Welcome to our community.

What Is the endpoint that you are hitting?

Thanks,
Ibrahem Daoud.

Dear @idaoud ,

Simulation Endpoint:

https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/compliance

Thanks,
Muthusamy

Dear @muthusamycse

To ensure comprehensive support as usual, Can I kindly ask you to mention the steps that you followed before hitting compliance API?

Thanks,
Ibrahem Daoud.

1 Like

Dear @idaoud,

I am following the Microsoft document link (shared here) to obtain a CSID

[Electronic invoicing onboarding in Saudi Arabia - Finance | Dynamics 365 | Microsoft Learn] (Electronic invoicing onboarding in Saudi Arabia - Finance | Dynamics 365 | Microsoft Learn)

In the document link, step# 8 - we are executing the onboarding script and getting the error. Below screenshot for your reference.

Dear @muthusamycse

Did you review official Educational library shared by ZATCA site?

Our recommendation is to review all the docs shared on ZATCA site to ensure being comply with all regulations,

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

Note: reviewing the educational library, will be more helpful to understand your concerns, and provide comprehensive support as usual.

Thanks,
Ibrahem Daoud.

Try modifying OpenSSL command for generating CSR, remove parameter -extensions v3_req

Not sure in simulation as i try this on sanbox, but maybe this will help

1 Like