ZATCA

La Resolució de facturació electrònica de la ZATCA (Zakat, Tax and Customs Authority) estableix que les empreses que operen a l’Aràbia Saudita han de generar i enviar factures electròniques en format UBL XML. La REST API de B2Brouter permet que la teva empresa compleixi totalment amb la ZATCA, gestionant per tu la generació de l’XML, l’encadenament de hash i el procés de clearance.

Què és la facturació electrònica ZATCA?

La facturació electrònica ZATCA (Fatoorah) requereix:

Generar factures en format UBL 2.1 XML, amb extensions específiques de l’Aràbia Saudita.
Calcular una cadena hash SHA-256 que enllaci cada factura amb l’anterior.
Enviar cada factura a la Clearance API de la ZATCA perquè sigui validada i signada digitalment.
Incrustar a la factura emesa el codi QR retornat per la ZATCA.

Amb B2Brouter pots descarregar-te de tot això. Emets factures o crees declaracions fiscals mitjançant crides REST, i B2Brouter s’encarrega de l’encadenament, el clearance i la generació del codi QR.

Requisits del compte (empresa)

Les factures ZATCA són emeses per empreses saudites. El compte ha de tenir country: "sa". Els camps següents són obligatoris per als comptes SA:

Paràmetre API	Descripció	Notes
`name`	Nom legal de l’empresa	Obligatori
`country`	Ha de ser `"sa"`	Obligatori
`address`	Nom del carrer	Obligatori
`address2`	Número de l’edifici	Obligatori: enter de 4 dígits
`city`	Ciutat	Obligatori
`postalcode`	Codi postal	Obligatori
`province`	Districte	Obligatori
`tin_value`	Número de registre d’IVA (15 dígits)	Obligatori
`tin_scheme`	Ha de ser `9760` (IVA saudita)	Obligatori

Nota: Els camps address2 i province corresponen, respectivament, als conceptes saudites de número d’edifici i districte. Fes servir address2 i province com a noms de paràmetre a l’API; l’API retornarà errors fent referència a aquests noms.

Requisits del contacte

Els contactes (compradors) de les factures ZATCA també han de tenir les dades d’adreça correctes. Els camps següents apliquen quan country és "sa":

Paràmetre API	Descripció	Notes
`name`	Nom legal del comprador	Obligatori
`country`	Codi de país ISO-2	Obligatori
`address`	Nom del carrer	Obligatori per a contactes SA amb ZATCA activat
`address2`	Número de l’edifici	Obligatori per a contactes SA amb ZATCA activat
`city`	Ciutat	Obligatori per a contactes SA amb ZATCA activat
`postalcode`	Codi postal	Obligatori per a contactes SA amb ZATCA activat
`province`	Districte	Obligatori per a contactes SA amb ZATCA activat
`tin_value`	Número de registre d’IVA	Obligatori per a factures B2B
`tin_scheme`	`9760` per a IVA saudita; consulta Tipus d’identificador del comprador per a compradors estrangers	Obligatori

Requisits de la factura

Les factures ZATCA fan servir SAR (riyal saudita) com a moneda. Els impostos han d’utilitzar name: "VAT" i category: "S" per al tipus estàndard del 15%.

Exemple mínim de factura:

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "send_after_import": true,
    "invoice": {
      "date": "2025-01-15",
      "number": "INV-001",
      "currency": "SAR",
      "payment_method": 1,
      "contact": {
        "name": "Buyer Company Ltd",
        "address": "King Fahd Road",
        "address2": "1234",
        "city": "Riyadh",
        "postalcode": "12345",
        "province": "Riyadh",
        "country": "sa",
        "tin_value": "310175397400003",
        "tin_scheme": 9760,
        "language": "en",
        "currency": "SAR"
      },
      "invoice_lines_attributes": [
        {
          "quantity": 1.0,
          "description": "Professional services",
          "price": 100.0,
          "taxes_attributes": [
            {
              "name": "VAT",
              "percent": 15.0,
              "category": "S"
            }
          ]
        }
      ]
    }
  }'

Categories fiscals i codis d’exempció

La ZATCA defineix quatre categories d’IVA. Per a les categories E (exempt) i Z (tipus zero), un codi vàlid de motiu d’exempció (comment a la línia d’impost) és obligatori; la factura serà rebutjada si no s’inclou.

Categoria	Descripció	Tipus	Cal codi d’exempció?
`S`	Tipus estàndard	15%	No
`E`	Exempt d’IVA	0%	Sí: `VATEX-SA-29`, `VATEX-SA-29-7` o `VATEX-SA-30`
`Z`	Tipus zero	0%	Sí: consulta la taula següent
`O`	Fora d’àmbit	0%	No

El codi d’exempció s’estableix al camp comment de la línia d’impost:

{
  "name": "VAT",
  "percent": 0.0,
  "category": "Z",
  "comment": "VATEX-SA-32"
}

Codis vàlids VATEX-SA-*

Categoria E — Exempt d’IVA

Codi	Descripció
`VATEX-SA-29`	Serveis financers esmentats a l’article 29 del Reglament de l’IVA
`VATEX-SA-29-7`	Serveis d’assegurança de vida esmentats a l’article 29 del Reglament de l’IVA
`VATEX-SA-30`	Operacions immobiliàries esmentades a l’article 30 del Reglament de l’IVA

Categoria Z — Tipus zero

Codi	Descripció
`VATEX-SA-32`	Exportació de béns
`VATEX-SA-33`	Exportació de serveis
`VATEX-SA-34-1`	Transport internacional de béns
`VATEX-SA-34-2`	Transport internacional de passatgers
`VATEX-SA-34-3`	Serveis directament connectats i accessoris a un subministrament de transport internacional de passatgers
`VATEX-SA-34-4`	Subministrament d’un mitjà de transport qualificat
`VATEX-SA-34-5`	Qualsevol servei relacionat amb el transport de béns o passatgers (article 25 del Reglament de l’IVA)
`VATEX-SA-35`	Medicaments i equipament mèdic
`VATEX-SA-36`	Metalls qualificats
`VATEX-SA-EDU`	Educació privada a ciutadans
`VATEX-SA-HEA`	Assistència sanitària privada a ciutadans
`VATEX-SA-MLTRY`	Subministrament de béns militars qualificats
`VATEX-SA-DIPLOMAT`	Subministraments qualificats a missions diplomàtiques
`VATEX-SA-DUTYFREE`	Subministrament qualificat de béns a la zona duty free
`VATEX-SA-32(bis)`	Subministrament sota un règim de suspensió duanera
`VATEX-SA-ROYALDECREE`	Subministrament sobre el qual el Govern assumeix l’IVA

Categoria O — Fora d’àmbit

Codi	Descripció
`VATEX-SA-OOS`	Serveis fora de l’àmbit de l’impost / No subjectes a IVA (text lliure segons el cas)

Tipus d’identificador del comprador

Per a compradors estrangers (no SA), fes servir tin_scheme per indicar el tipus d’identificador:

`tin_scheme`	Descripció
`9760`	Número de registre d’IVA saudita
`0002`	Número d’IVA de la UE
`0003`	Número de passaport
`0004`	Identificador oficial (país de residència)
`0005`	Certificat de residència
`0006`	Altre document
`0007`	No registrat

Cicle de vida de la declaració fiscal

Després de crear o enviar una factura, el clearance de ZATCA és asíncron. El tax_report estarà inicialment en estat processing.

Supervisa el progrés mitjançant:

Webhook (recomanat): subscriu-te al webhook de canvi d’estat de tax report. Els estats finals són registered, error i registered_with_errors.
Polling: crida el endpoint de consulta de tax report fins que l’estat sigui final.

Mapeig de camps: Invoice API → XML ZATCA

Camp de l’Invoice API	Element XML ZATCA
`number`	`cbc:ID`
`date`	`cbc:IssueDate`
`company.tin_value`	`cbc:CompanyID` del proveïdor
`company.address2`	`cbc:BuildingNumber` del proveïdor
`company.province`	`cbc:District` del proveïdor
`contact.tin_value`	`cbc:CompanyID` del client
`contact.address2`	`cbc:BuildingNumber` del client
`contact.province`	`cbc:District` del client
`tax.percent`	`cbc:Percent`
`tax.category`	`cbc:ID` a `cac:TaxCategory`
`tax.comment`	`cbc:TaxExemptionReasonCode`
`invoice.total`	`cbc:TaxInclusiveAmount`
`invoice.subtotal`	`cbc:TaxExclusiveAmount`