ZATCA

La Resolución de facturación electrónica de ZATCA (Autoridad de Zakat, Impuestos y Aduanas) exige que las empresas que operan en Arabia Saudí generen y envíen facturas electrónicas en formato UBL XML. La API REST de B2Brouter permite que tu empresa cumpla totalmente con ZATCA, gestionando por ti la generación XML, el encadenamiento de hashes y el proceso de clearance.

¿Qué es la facturación electrónica ZATCA?

La facturación electrónica ZATCA (Fatoorah) requiere:

• Generar facturas en formato UBL 2.1 XML, con extensiones específicas de Arabia Saudí.
• Calcular una cadena hash SHA-256 que vincule cada factura con la anterior.
• Enviar cada factura a la API de Clearance de ZATCA para su validación y firma digital.
• Incrustar el código QR devuelto por ZATCA en la factura emitida.

Con B2Brouter puedes delegar todo esto. Emites facturas o creas informes fiscales mediante llamadas REST, y B2Brouter se encarga del encadenamiento, el clearance y la generación del código QR.

Requisitos de la cuenta (empresa)

Las facturas ZATCA son emitidas por empresas saudíes. La cuenta debe tener country: "sa". Los siguientes campos son obligatorios para cuentas SA:

Parámetro API	Descripción	Notas
name	Nombre legal de la empresa	Obligatorio
country	Debe ser "sa"	Obligatorio
address	Nombre de la calle	Obligatorio
address2	Número del edificio	Obligatorio — entero de 4 dígitos
city	Ciudad	Obligatorio
postalcode	Código postal	Obligatorio
province	Distrito	Obligatorio
tin_value	Número de registro VAT (15 dígitos)	Obligatorio
tin_scheme	Debe ser 9760 (IVA saudí)	Obligatorio

Nota: Los campos address2 y province corresponden a los conceptos saudíes de número de edificio y distrito respectivamente. Usa address2 y province como nombres de parámetros API — la API devolverá errores haciendo referencia a estos nombres.

Requisitos del contacto

Los contactos (compradores) de facturas ZATCA también deben tener datos de dirección correctos. Los siguientes campos aplican cuando country es "sa":

Parámetro API	Descripción	Notas
name	Nombre legal del comprador	Obligatorio
country	Código de país ISO-2	Obligatorio
address	Nombre de la calle	Obligatorio para contactos SA con ZATCA habilitado
address2	Número del edificio	Obligatorio para contactos SA con ZATCA habilitado
city	Ciudad	Obligatorio para contactos SA con ZATCA habilitado
postalcode	Código postal	Obligatorio para contactos SA con ZATCA habilitado
province	Distrito	Obligatorio para contactos SA con ZATCA habilitado
tin_value	Número de registro VAT	Obligatorio para facturas B2B
tin_scheme	9760 para IVA saudí; consulta Tipos de ID del comprador para compradores extranjeros	Obligatorio

Requisitos de la factura

Las facturas ZATCA utilizan SAR (Riyal saudí) como moneda. Los impuestos deben usar name: "VAT" y category: "S" para el tipo estándar del 15%.

Ejemplo mínimo 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"
            }
          ]
        }
      ]
    }
  }'

Categorías fiscales y códigos de exención

ZATCA define cuatro categorías de IVA. Para las categorías E (Exento) y Z (Tipo cero), es obligatorio un código válido de motivo de exención (comment en la línea de impuesto); la factura será rechazada sin él.

Categoría	Descripción	Tipo	¿Código de exención obligatorio?
S	Tipo estándar	15%	No
E	Exento de IVA	0%	Sí — VATEX-SA-29, VATEX-SA-29-7 o VATEX-SA-30
Z	Tipo cero	0%	Sí — consulta la tabla inferior
O	Fuera de alcance	0%	No

El código de exención se define en el campo comment de la línea de impuesto:

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

Códigos VATEX-SA-* válidos

Categoría E — Exento de IVA

Código	Descripción
VATEX-SA-29	Servicios financieros mencionados en el artículo 29 del reglamento del IVA
VATEX-SA-29-7	Servicios de seguros de vida mencionados en el artículo 29 del reglamento del IVA
VATEX-SA-30	Transacciones inmobiliarias mencionadas en el artículo 30 del reglamento del IVA

Categoría Z — Tipo cero

Código	Descripción
VATEX-SA-32	Exportación de bienes
VATEX-SA-33	Exportación de servicios
VATEX-SA-34-1	Transporte internacional de bienes
VATEX-SA-34-2	Transporte internacional de pasajeros
VATEX-SA-34-3	Servicios directamente relacionados e incidentales al transporte internacional de pasajeros
VATEX-SA-34-4	Suministro de un medio de transporte cualificado
VATEX-SA-34-5	Cualquier servicio relacionado con el transporte de bienes o pasajeros (artículo 25 del reglamento del IVA)
VATEX-SA-35	Medicamentos y equipamiento médico
VATEX-SA-36	Metales cualificados
VATEX-SA-EDU	Educación privada para ciudadanos
VATEX-SA-HEA	Sanidad privada para ciudadanos
VATEX-SA-MLTRY	Suministro de bienes militares cualificados
VATEX-SA-DIPLOMAT	Suministros cualificados para misiones diplomáticas
VATEX-SA-DUTYFREE	Suministro cualificado de bienes en zona Duty Free
VATEX-SA-32(bis)	Suministro bajo acuerdo de suspensión aduanera
VATEX-SA-ROYALDECREE	Suministro en el que el gobierno asume el IVA

Categoría O — Fuera de alcance

Código	Descripción
VATEX-SA-OOS	Servicios fuera del ámbito fiscal / No sujetos a IVA (texto libre según el caso)

Tipos de ID del comprador

Para compradores extranjeros (no SA), utiliza tin_scheme para especificar el tipo de identificador:

tin_scheme	Descripción
9760	Número de registro IVA saudí
0002	Número IVA europeo
0003	Número de pasaporte
0004	Documento oficial de identidad (país de residencia)
0005	Certificado de residencia
0006	Otro documento
0007	No registrado

Ciclo de vida del informe fiscal

Después de crear o enviar una factura, el proceso de clearance ZATCA es asíncrono. El tax_report estará inicialmente en estado processing.

Supervisa el progreso mediante:

• Webhook (recomendado): Suscríbete al webhook de cambio de estado del informe fiscal. Los estados finales son registered, error, registered_with_errors.
• Polling: Llama al endpoint de obtención del informe fiscal hasta que el estado sea final.

Mapeo de campos: API Invoice → XML ZATCA

Campo API Invoice	Elemento XML ZATCA
number	cbc:ID
date	cbc:IssueDate
company.tin_value	Supplier cbc:CompanyID
company.address2	Supplier cbc:BuildingNumber
company.province	Supplier cbc:District
contact.tin_value	Customer cbc:CompanyID
contact.address2	Customer cbc:BuildingNumber
contact.province	Customer cbc:District
tax.percent	cbc:Percent
tax.category	cbc:ID en cac:TaxCategory
tax.comment	cbc:TaxExemptionReasonCode
invoice.total	cbc:TaxInclusiveAmount
invoice.subtotal	cbc:TaxExclusiveAmount