Onboarding per la fatturazione elettronica in Arabia Saudita

2025-06-05

In questo articolo viene descritto come eseguire l'onboarding dei contribuenti e il software di fatturazione elettronica presso l'autorità fiscale dell'Arabia Saudita in Microsoft Dynamics 365 Finance.

L'onboarding è obbligatorio per tutti i contribuenti soggetti alla fatturazione elettronica in Arabia Saudita. Come risultato del processo di onboarding, i contribuenti ottengono identificatori di timbro crittografico (CSID). I CSID sono necessari per l'integrazione con il portale di fatturazione elettronica gestito dall'autorità fiscale dell'Arabia Saudita (Zakat, Autorità fiscale e doganale [ZATCA]) e per l'ulteriore invio delle fatture elettroniche.

Prerequisiti

La persona giuridica deve essere registrata come contribuente in Arabia Saudita e deve avere un numero di partita IVA valido.
La persona giuridica deve avere accesso al portale fiscale dell'Arabia Saudita (ERAD).

Processo di onboarding

Il processo di onboarding è costituito da due passaggi:

Ottenere un CSID di conformità (CCSID), che ZATCA assegna per eseguire i controlli di conformità sulle soluzioni di generazione di fatture elettroniche (EGS).
Ottenere un CSID di produzione (PCSID), che ZATCA assegna agli EGS conformi.

Ottenere un CCSID

Per ottenere un CCSID, seguire questi passaggi.

Nel Portale fiscale dell'Arabia Saudita (ERAD) accedi al portale di onboarding e gestione selezionando il riquadro pertinente.
Nella pagina di destinazione principale del portale di onboarding e gestione seleziona il riquadro Integra nuova unità/dispositivo della soluzione, quindi seleziona Genera codice OTP.
Seleziona il numero di codici OTP (One-Time Password) da generare. Il numero dipende dal numero di unità di generazione (dispositivi) di fatturazione elettronica che verranno usate.
Salvare i codici OTP generati per poterli usare nei passaggi successivi.

Importante

I codici OTP sono validi solo per un'ora dopo la generazione. Assicurarsi di usarli entro tale periodo di tempo.

Preparare un file di configurazione per la richiesta di firma del certificato (CSR). Il file di configurazione deve essere sotto forma di file di testo normale contenente i dati seguenti.

oid_section = OIDs
[OIDs]
certificateTemplateName = 1.3.6.1.4.1.311.20.2
[req]
default_bits = 2048
emailAddress = MyEmail@email.com
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=Riyad Branch
O=Contoso
CN=EA123456789
[v3_req]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment
[req_ext]
certificateTemplateName = ASN1:PRINTABLESTRING:ZATCA-Code-Signing
subjectAltName = dirName:alt_names
[alt_names]
SN=1-TST|2-TST|3-ed22f1d8-e6a2-1118-9b58-d9a8f11e445f
UID=310122393500003
title=1100
registeredAddress= MyAddress
businessCategory=Industry

Salva il file di configurazione CSR nella stessa posizione dello script di onboarding e denominalo csr_config.txt.

Nel file di configurazione CSR aggiorna il valore emailAddress e i seguenti dati.

Codice	Description	Specifica
C	Codice paese/area geografica.	Un codice di due lettere (ISO 3166 Alpha-2).
OU	Nome dell'unità organizzativa.	Per i contribuenti normali, il valore è il testo libero. Per i gruppi IVA, identificare il valore attraverso il fatto che l'undicesima cifra dell'identificativo dell'organizzazione è "1". Verificare che l'input sia un numero di identificazione fiscale (TIN) di 10 cifre.
O	Il nome dell'organizzazione o del contribuente.	Testo libero.
CN	Nome univoco della soluzione o dell'unità.	Testo libero.
SN	Codice di identificazione univoco per la soluzione.	Testo libero.
UID	Partita IVA del contribuente.	Numero di 15 cifre che inizia con "3" e termina con "3".
titolo	Tipo di documento emesso dall'unità di soluzione del contribuente.	Input numerico a quattro cifre che utilizza "0" e "1" mappati su "TSCZ": "0" = Falso/Non supportato e "1" = Vero/Supportato. "T" = Fattura fiscale (standard), "S" = Fattura fiscale semplificata, "C" = Per uso futuro e "Z" = Per uso futuro.
registeredAddress	L'indirizzo della filiale o dell'ubicazione in cui si trova principalmente il dispositivo o l'unità della soluzione.	Testo libero.
businessCategory	L'industria o il settore per cui il dispositivo o la soluzione genererà fatture.	Testo libero.

Nota

Quando si utilizza il portale di simulazione, i valori di CN e certificateTemplateName nel file di configurazione CSR differiscono.

Nel portale di simulazione usare i seguenti valori:

CN: PREZATCA-Code-Signing
certificateTemplateName: ASN1:PRINTABLESTRING:PREZATCA-Code-Signing

Per tutti gli altri casi, usare i valori forniti in precedenza.

Eseguire lo script di onboarding fornito più avanti in questo articolo. Specificare il codice OTP e il file di configurazione CSR come parametri di input. Ecco un esempio.

.\OnboardingScript.ps1 -action getComplianceCSID -otp 123345 -csrconfig .\csr_config.txt -password 123

Nota

Il parametro password è facoltativo e può essere omesso. Se è incluso, il certificato generato avrà la password specificata.
Il CCSID viene ricevuto come file di certificato, CCSID.pfx. Il segreto per il CCSID viene salvato come file di testo, CCSIDSecret.txt. Salva il file del certificato CCSID nel certificato dell'insieme di credenziali delle chiavi Microsoft Azure e salva il segreto nel segreto dell'insieme di credenziali delle chiavi. Per ulteriori informazioni, vedi Certificati e segreti del cliente.
Configura l'impostazione delle funzionalità correlate nella funzionalità di fatturazione elettronica per il controllo della conformità ZATCA (SA) dell'Arabia Saudita e fai riferimento al certificato CCSID salvato nell'insieme di credenziali delle chiavi. Il certificato sarà utilizzato per la comunicazione con il portale di fatturazione elettronica ZATCA.

Controllo di conformità

Dopo aver ottenuto un CCSID utilizzando lo script PowerShell, ZATCA richiede il completamento di specifici controlli di conformità mediante l'invio di fatture di esempio. Questo passaggio è un prerequisito per richiedere un PCSID.

Assicurarsi che tutti i tipi di fatture di esempio configurati nel file di configurazione CSR siano inviati correttamente a ZATCA. Usare il processo standard per l'emissione di fatture elettroniche. Per altre informazioni, vedi Emissione di fatture elettroniche in Finance e Supply Chain Management.

Segui i passaggi in Fatturazione elettronica per l'Arabia Saudita - Fase due. Usa la funzionalità di controllo della conformità ZATCA (SA) dell'Arabia Saudita per la fatturazione elettronica e il CCSID ottenuto.

Dopo che i controlli di conformità sono stati completati con successo, utilizzare lo script PowerShell per ottenere un PCSID. (Vedi lo script di onboarding fornito più avanti in questo articolo).

Nota

Se il tipo di documento del campo titolo del file di configurazione CSR è impostato su 1000, è necessario inviare le seguenti tre fatture di esempio per il controllo di conformità:

Fattura fiscale standard
Nota di addebito standard
Nota di accredito standard

Se il tipo di documento è impostato su 0100, è necessario inviare le seguenti tre fatture di esempio per il controllo di conformità:

Fattura fiscale semplificata
Nota di debito semplificata
Nota di credito semplificata

Se il tipo di documento è impostato su 1100, è necessario inviare tutte e sei le fatture di esempio per il controllo di conformità.

Ottenere un PCSID

Per ottenere un PCSID, è necessario configurare correttamente la soluzione per la generazione e l'invio di fatture elettroniche e la soluzione deve essere completamente funzionante. Per ottenere questo risultato, è necessario completare tutti i passaggi preliminari di configurazione richiesti. Per ulteriori informazioni, vedi Fatturazione elettronica per l'Arabia Saudita - Fase due.

Per ottenere un PCSID, seguire questi passaggi.

Assicurarsi che tutte le fatture elettroniche siano inviate correttamente a ZATCA.
Eseguire lo script di onboarding fornito più avanti in questo articolo. Specificare il CCSID come parametro di input. Ecco un esempio.

.\OnboardingScript.ps1 -action getProductionCSID -password 123

Nota

Il parametro password è facoltativo e può essere omesso. Se è incluso, il certificato generato avrà la password specificata.
Il PCSID viene ricevuto come file di certificato in formato PFX. Salvare il certificato PCSID e il file segreto nell'insieme di credenziali delle chiavi.
Configura la funzionalità correlata per la funzionalità di fatturazione elettronica Invio per Zatca dell'Arabia Saudita. Includi il certificato PCSID e il segreto nei parametri dell'insieme di credenziali delle chiavi.

Dopo aver completato tutti i passaggi di configurazione, il sistema è pronto per essere usato in modalità di produzione.

Per esaminare i CSID ottenuti sul lato ZATCA, usa il riquadro Esamina identificatore CSID (Cryptographic Stamp Identifier) nella pagina di destinazione esistente del portale di onboarding e gestione. Questo portale è accessibile dal portale fiscale dell'Arabia Saudita (ERAD) principale.

Script di onboarding

Nota

Gli script di esempio non sono supportati in alcun programma o servizio di supporto standard Microsoft. Gli script di esempio vengono forniti COSÌ COME SONO senza garanzie di alcun tipo. Microsoft declina inoltre tutte le garanzie implicite incluse, senza limitazioni, qualsiasi garanzia implicita di commerciabilità o idoneità per uno scopo particolare. L'intero rischio derivante dall'uso o dalle prestazioni degli script e della documentazione di esempio rimane a carico dell'utente. In nessun caso Microsoft, i suoi autori o chiunque altro sia coinvolto nella creazione, produzione o consegna degli script saranno responsabili per eventuali danni di qualsiasi tipo (inclusi, a titolo esemplificativo, danni per perdita di profitti aziendali, interruzione dell'attività, perdita di informazioni commerciali o altre perdite pecuniarie) derivanti dall'uso o dall'impossibilità di utilizzare gli script o la documentazione di esempio, anche nel caso in cui Microsoft sia stata avvisata della possibilità di tali danni.

Utilizzare il seguente script Windows PowerShell per ottenere un CCSID e un PCSID.

#Saudi Arabian electronic invoice onboarding script
#Version 1.2
param($action, $otp, $csrconfig, $password)
$env:path = $env:path + ";C:\Program Files\Git\usr\bin"
 
if ($action -eq "getComplianceCSID")
{
    if (-not (Test-Path -Path $csrconfig))
    {
        throw "CSR configuration file does not exist, please make sure to provide a valid file path for the '-csrconfig' parameter."
    }
 
if ($otp -eq $null)
    {
        throw "OTP code is not provided, please carry correct parameters."
    }
 
#Generate private key
    openssl ecparam -name secp256k1 -genkey -noout -out privatekey.pem
    Write-Host "Private key generated."
 
#Generate public key
    openssl ec -in privatekey.pem -pubout -conv_form compressed -out publickey.pem
    Write-Host "Public key generated."
 
#Generate CSR(Certificate signing request)
    openssl base64 -d -in publickey.pem -out publickey.bin
    openssl req -new -sha256 -key privatekey.pem -extensions v3_req -config $csrconfig -out .\taxpayer.csr
    openssl base64 -in taxpayer.csr -out taxpayerCSRbase64Encoded.txt
    $CSRbase64Encoded = Get-Content -path taxpayerCSRbase64Encoded.txt -Raw
    $CSRbase64Encoded = $CSRbase64Encoded -replace "`n",""
    $CSRbase64Encoded = $CSRbase64Encoded -replace "`r",""
 
#Init request for CCSID
    $postParams = @{"csr"=$CSRbase64Encoded} | ConvertTo-Json
    $postHeader = @{
           "Accept"="application/json"
           "OTP"=$otp
           "Content-Type"="application/json"
           "Accept-Version"="V2"}
 
try
    {
        $response = Invoke-WebRequest -Uri 'https://gw-fatoora.zatca.gov.sa/e-invoicing/core/compliance' -Method POST -Body $postParams -Headers $postHeader
    }
    catch
    {
        Write-Host "`nZatca service communication error:"
        Write-Host $_.Exception.Message
        Write-Host "Please make sure the OTP code in script parameter and Serial Number (SN) in configuration file are valid."
        Write-Host "The process of obtaining a Compliance CSID (CCSID) is interrupted."
    }
 
if ($response -ne $null)
    {
        $response = $response | ConvertFrom-Json
        $requestId = $response.requestID
        Write-Host "Request ID:"
        Write-Host $requestId
        $requestId | Out-File -FilePath .\requestId.txt -Encoding utf8 -NoNewline
 
$CCSIDbase64 = $response.binarySecurityToken
        Write-Host "`nCompliance CSID received from Zatca:"
        Write-Host $CCSIDbase64
        $CCSID = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($CCSIDbase64))
        $CCSIDCertString = "-----BEGIN CERTIFICATE-----`n" + $CCSID + "`n" + "-----END CERTIFICATE-----"
 
$CCSIDSecret = $response.secret
        Write-Host "`nCompliance CSID secret received from Zatca:"
        Write-Host $CCSIDSecret
 
$CCSIDStringFileName = "CCSIDString.txt"
        $CCSIDSecretFileName = "CCSIDSecret.txt"
        $CCSIDCertFileName = "CCSID.pem"
        $CCSIDFolderPath = Get-Location
        $CCSIDCertFilePath = Join-Path $CCSIDFolderPath $CCSIDCertFileName
        $CCSIDStringFilePath = Join-Path $CCSIDFolderPath $CCSIDStringFileName
        $CCSIDSecretFilePath = Join-Path $CCSIDFolderPath $CCSIDSecretFileName
 
$Utf8NoBomEncoding = New-Object System.Text.UTF8Encoding $False
        [System.IO.File]::WriteAllLines($CCSIDCertFilePath, $CCSIDCertString, $Utf8NoBomEncoding)
        [System.IO.File]::WriteAllLines($CCSIDStringFilePath, $CCSIDbase64, $Utf8NoBomEncoding)
        [System.IO.File]::WriteAllLines($CCSIDSecretFilePath, $CCSIDSecret, $Utf8NoBomEncoding)
 
openssl pkcs12 -inkey privatekey.pem -in CCSID.pem -export -passout pass:$password -out CCSID.pfx
        Write-Host "`nCertificate is saved to CCSID.pfx file and secret is saved to CCSIDSecret.txt file."
        Write-Host "The process of obtaining a Compliance CSID (CCSID) is complete, please process the compliance check and do not delete or move any created files before getting PCSID."
    }
}
 
if ($action -eq "getProductionCSID")
{
    if (-not (Test-Path -Path requestId.txt))
    {
        throw "'requestId.txt' file is missing, please make sure you're running the script in the same location where the results of getting the CCSID are stored."
    }
    if (-not (Test-Path -Path CCSIDString.txt))
    {
        throw "'CCSIDString.txt' file is missing, please make sure you're running the script in the same location where the results of getting the CCSID are stored."
    }
    if (-not (Test-Path -Path CCSIDSecret.txt))
    {
        throw "'CCSIDSecret.txt' file is missing, please make sure you're running the script in the same location where the results of getting the CCSID are stored."
    }
 
$requestId = Get-Content -path requestId.txt -Raw
    $requestId = $requestId -replace "`n",""
    $requestId = $requestId -replace "`r",""
    Write-Host "Request ID is:" $requestId
    $CCSID = Get-Content -path CCSIDString.txt -Raw
    $CCSID = $CCSID -replace "`n",""
    $CCSID = $CCSID -replace "`r",""
    Write-Host "`nCompliance CSID read locally:"
    Write-Host $CCSID
    $CCSIDSecretString = Get-Content -path CCSIDSecret.txt -Raw
    $CCSIDSecretString = $CCSIDSecretString -replace "`n",""
    $CCSIDSecretString = $CCSIDSecretString -replace "`r",""
    Write-Host "`nCompliance CSID secret read locally:"
    Write-Host $CCSIDSecretString
    $AuthTokenString = $CCSID + ":" + $CCSIDSecretString
    $BasicAuthToken = "Basic " + [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($AuthTokenString))
 
#Init request for Production CSID (PCSID)
    $postParams = @{"compliance_request_id"=$requestId} | ConvertTo-Json
    $postHeader = @{
           "Accept"="application/json"
           "Authorization"=$BasicAuthToken
           "Content-Type"="application/json"
           "Accept-Version"="V2"}
 
try
    {
        $response = Invoke-WebRequest -Uri 'https://gw-fatoora.zatca.gov.sa/e-invoicing/core/production/csids' -Method POST -Body $postParams -Headers $postHeader
    }
    catch
    {
        Write-Host "`nZatca service communication error:"
        Write-Host $_.Exception.Message
        Write-Host "Please make sure the compliance check process has been done before obtaining a Production CSID (PCSID)."
        Write-Host "The process of obtaining a Production CSID (PCSID) is interrupted."
    }
 
if ($response -ne $null)
    {
        $response = $response | ConvertFrom-Json
        $PCSIDbase64 = $response.binarySecurityToken
        Write-Host "`nProduction CSID received from Zatca:"
        Write-Host $PCSIDbase64
 
$PCSID = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($PCSIDbase64))
        $PCSIDCertString = "-----BEGIN CERTIFICATE-----`n" + $PCSID + "`n" + "-----END CERTIFICATE-----"
 
$PCSIDSecret = $response.secret
        Write-Host "`nProduction CSID secret received from Zatca:"
        Write-Host $PCSIDSecret
 
$PCSIDCertFileName = "PCSID.pem"
        $PCSIDSecretFileName = "PCSIDSecret.txt"
        $PCSIDFolderPath = Get-Location
        $PCSIDCertFilePath = Join-Path $PCSIDFolderPath $PCSIDCertFileName
        $PCSIDSecretFilePath = Join-Path $PCSIDFolderPath $PCSIDSecretFileName
 
$Utf8NoBomEncoding = New-Object System.Text.UTF8Encoding $False
        [System.IO.File]::WriteAllLines($PCSIDCertFilePath, $PCSIDCertString, $Utf8NoBomEncoding)
        [System.IO.File]::WriteAllLines($PCSIDSecretFilePath, $PCSIDSecret, $Utf8NoBomEncoding)
 
        # Sandbox API will get error: openssl : No certificate matches private key
        openssl pkcs12 -inkey privatekey.pem -in PCSID.pem -export -passout pass:$password -out PCSID.pfx
 
if (Test-Path -Path PCSID.pfx)
        {
            Write-Host "`nCertificate is saved to PCSID.pfx file and secret is saved to PCSIDSecret.txt file."
            Write-Host "The process of obtaining a Production CSID (PCSID) is complete."
        }
        else
        {
            Write-Host "`nThe process of obtaining a Production CSID (PCSID) is interrupted."
        }
    }
}

Salvare il file di certificato .pfx di output ricevuto nell'insieme di credenziali delle chiavi.

Condividi tramite

Onboarding per la fatturazione elettronica in Arabia Saudita

Prerequisiti

Processo di onboarding

Ottenere un CCSID

Controllo di conformità

Ottenere un PCSID

Script di onboarding

Risorse aggiuntive

Commenti e suggerimenti

Risorse aggiuntive