[Beta] Informa registres d'IVA a l'AEAT via SII (Suministro Inmediato de Información) amb l'API de B2Brouter

[Beta] — només a staging. L’API JSON Tax Report per a SII descrita en aquesta guia està disponible actualment a l’entorn de staging (https://api-staging.b2brouter.net) per a proves d’integració. Encara no està habilitada en producció. Els noms de camps, els endpoints i el comportament poden canviar abans del llançament en producció.

El sistema espanyol Suministro Inmediato de Información (SII) obliga les empreses registrades a mantenir els seus llibres d’IVA — factures emeses, factures rebudes, béns d’inversió, operacions intracomunitàries, operacions en metàl·lic superiors a 6.000 €, i d’altres — enviats en temps quasi real a l’AEAT (“Agencia Estatal de Administración Tributaria”). El SII és obligatori per a les Grans Empreses (facturació > 6.010.121,04 €), els membres de grups d’IVA, els participants al REDEME i altres empreses que s’hi han acollit voluntàriament.

B2Brouter ofereix una API JSON Tax Report per a SII perquè el teu sistema no hagi de gestionar SOAP, certificats de l’AEAT, enviaments per lots, anàlisi de respostes ni els wrappers XML per llibre. Tu fas crides REST; B2Brouter s’encarrega de la resta, agrupant els registres en “Libros de Registro” de l’AEAT i enviant-los amb un certificat de Col·laborador Social.

Què és el SII?

El SII és un sistema d’informació tributària independent de la facturació — la factura subjacent no porta cap codi QR ni hi ha cap pas de verificació de cara al consumidor. Cada registre representa una entrada en un llibre (una factura emesa, una factura rebuda, la prorrata anual d’un bé d’inversió, etc.). L’AEAT recull els registres al llarg de l’any i els utilitza per fer la comprovació creuada de l’IVA.

El SII té nou tipus de llibres (“libros”), cadascun amb el seu propi wrapper XML de l’AEAT i les seves regles de validació:

Tipus de llibre	Què registra	A0 (alta)	A1 (modificación)	B (baja / anul·lació)
Expedida	Factures emeses	✓	✓	✓
Recibida	Factures rebudes	✓	✓	✓
Inversion	Béns d’inversió (bienes de inversión)	✓	✓	✓
Intracomunitaria	Operacions intracomunitàries	✓	✓	✓
Metalico	Operacions en metàl·lic ≥ 6.000 € / contrapart / període	✓	✓	✓
Seguro	Operacions d’assegurances	✓	✓	✓
Viajesagencia	Règim especial d’agències de viatges	✓	✓	✓
Cobro	Cobraments rebuts de factures emeses	✓	—	—
Pago	Pagaments efectuats de factures rebudes	✓	—	—

Cobro i Pago retornen HTTP 422 en PATCH i DELETE — l’XSD de l’AEAT no preveu variants A1 ni B per a aquests llibres.

Expedida i Recibida concentren el 98%+ del volum en producció. Els set llibres restants cobreixen la cua llarga dels requisits d’informació d’IVA.

Configuració i treball amb l’API de B2Brouter

El primer pas és habilitar l’autoritat tributària SII per a l’empresa que reportarà. Pots consultar la Tax Report Settings Guide per a una descripció completa. La crida mínima:

Exemple de petició:

curl --request POST \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_report_settings' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report_setting": {
      "code": "sii",
      "start_date": "2026-04-15",
      "auto_send": true
    }
  }'

Un cop existeix una configuració amb code: "sii" al compte, totes les crides a l’API Tax Report SII d’aquell compte l’utilitzen.

API Tax Report

L’API Tax Report és una família d’endpoints que gestiona els nou llibres SII. El llibre es selecciona amb el camp book_type del cos de la petició. El camp type és SiiDocument per a tots els registres SII independentment del llibre.

Crear un Tax Report

POST /accounts/{ACCOUNT_ID}/tax_reports crea un registre SII. El mateix endpoint l’utilitzen Verifactu, TicketBai i KSeF; el camp type determina quin conjunt de validació + quin wrapper XML de l’AEAT s’aplica.

L’estructura del payload JSON es basa en el PEPPOL Continuous Transaction Control (CTC) — els noms de camps CTC no coincideixen amb els noms de nodes de l’XML de l’AEAT. La secció Equivalència entre els camps interns de tax report de B2Brouter i els nodes XML del SII més avall recull el mapeig per a cada llibre.

Els tax reports tenen desglossaments fiscals (“desglose” en castellà), no línies de factura. El teu sistema agrega les línies de factura subjacents per tipus/categoria fiscal i envia les sumes del desglossament. B2Brouter realitza la validació però no calcula els desglossaments a partir de les dades de les línies.

Cicle de vida

Després d’un POST /tax_reports satisfactori, la resposta porta un state: "processing" i un ledger_id. Els registres SII s’agrupen en “Libros de Registro” (Ledgers) al servidor i s’envien a l’AEAT de manera asíncrona. Per fer el seguiment del cicle de vida:

Recomanat: configura el webhook de tax report. B2Brouter crida el teu endpoint quan el registre arriba a un estat final (registered, error, registered_with_errors, annulled o refused).
Polling: crida GET /tax_reports/{id} repetidament fins que state arribi a un dels valors finals.

La resposta de l’AEAT es reflecteix en tres camps específics de SII al registre un cop rebuda:

csv — el Código Seguro de Verificación assignat per l’AEAT
fecha_presentacion — el timestamp de presentació assignat per l’AEAT
estado — l’estat intern del SII. Comença a Nuevo, passa a Enviando mentre està en trànsit i s’estabilitza en un valor terminal: Correcto, Incorrecto, AceptadoConErrores o Error.

Per als estats d’error, l’array errors del registre s’omple amb el rebuig de l’AEAT, on cada entrada porta un code i una description:

{
  "errors": [
    {
      "code": "4102",
      "description": "El NIF no está identificado en el censo de la AEAT"
    }
  ]
}

Obtenir la representació XML

GET /tax_reports/{id}/download retorna l’XML per registre que B2Brouter inclourà (o ha inclòs) a l’enviament a l’AEAT. L’XML es genera en el moment de la creació i es persisteix, de manera que està disponible immediatament després del POST. El paquet que s’envia realment és l’XML del Ledger concatenat — consulta l’API de Ledgers.

Corregir un Tax Report (A1)

PATCH /tax_reports/{id} amb els camps corregits crea un registre germà amb operacion: A1 (modificación). El registre original es manté; el nou germà s’enllaça via corrected_by_id a l’original i és el que es remet a l’AEAT.

El llibre al qual pertany un registre queda fixat en el moment de la creació — book_type no es pot canviar en un germà A1. Cobro i Pago retornen 422; el seu XSD de l’AEAT no defineix cap wrapper A1.

Cancel·lar un Tax Report (B)

DELETE /tax_reports/{id} crea un registre germà amb operacion: B (baja / anul·lació). L’original s’enllaça via annulled_by_id. Cobro i Pago retornen 422 — el seu XSD de l’AEAT no defineix cap wrapper B.

Llistar Tax Reports

GET /accounts/{ACCOUNT_ID}/tax_reports retorna els tax reports del compte — SII, Verifactu, TicketBai, KSeF, tots en una sola llista. Filtra per rang de dates o altres criteris tal com es documenta a l’endpoint de llistat de tax reports.

Expedida (factures emeses)

El llibre SII més comú. L’empresa que reporta és l’emissora de la factura; el client és la contrapart.

Exemple de petició

curl --request POST \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "SiiDocument",
      "book_type": "Expedida",
      "invoice_number": "INV-2026-001",
      "invoice_date": "2026-04-15",
      "fiscal_year": 2026,
      "fiscal_period": 4,
      "invoice_type_code": "F1",
      "special_regime_key": "01",
      "description": "Servicios de consultoría",
      "customer_party_name": "Cliente Ejemplo S.L.",
      "customer_party_tax_id": "B87654321",
      "customer_party_country": "es",
      "tax_inclusive_amount": 1210.0,
      "tax_amount": 210.0,
      "currency": "EUR",
      "tax_breakdowns": [
        {
          "name": "IVA",
          "category": "S",
          "percent": 21.0,
          "taxable_base": 1000.0,
          "tax_amount": 210.0
        }
      ]
    }
  }'

Camps específics d’Expedida (a més dels camps CTC comuns):

Camp	Mapeja a l’element AEAT	Notes
`simplified_art7273`	`FacturaSimplificadaArticulos7.2_7.3`	Booleà. Emet `S` quan és true.
`reg_previo_ggee`	`RegPrevioGGEEoREDEMEoCompetencia`	Booleà.
`macrodata`	`Macrodato`	Booleà (SII), a diferència de la versió string de Verifactu.
`facturacion_disp_adicional_mercado_gas`	`FacturacionDispAdicionalTerceraYsextayDelMercadoOrganizadoDelGas`	Booleà. Exclusiu d’Expedida.
`sin_identif_destinatario_art_6_1_d`	`FacturaSinIdentifDestinatarioAritculo6.1.d`	Booleà. Exclusiu d’Expedida.
`succession_party_name` + `_tax_id`	`EntidadSucedida` > `NombreRazon` / `NIF`	Tots dos obligatoris conjuntament quan s’utilitzen.
`billing_agreement_number`	`NumRegistroAcuerdoFacturacion`	Màxim 15 caràcters.
`external_reference`	`RefExterna`	Màxim 60 caràcters.
`tax_point_date`	`FechaOperacion`	Opcional; s’omet per defecte.

El wrapper XML de l’AEAT és SuministroLRFacturasEmitidas. Els cinc flags S/N de dalt són opcionals i s’emeten només quan són true.

Recibida (factures rebudes)

Recibida té la inversió emissor/receptor respecte a Expedida: el proveïdor extern és l’emissor (registrat a IDEmisorFactura), i l’empresa que reporta és la receptora (Titular). Utilitza supplier_party_* per al proveïdor extern; customer_party_* no és necessari (els valors per defecte de l’empresa s’utilitzen com a receptor).

Exemple de petició

curl --request POST \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "SiiDocument",
      "book_type": "Recibida",
      "invoice_number": "PROV-555",
      "invoice_date": "2026-04-15",
      "tax_point_date": "2026-04-10",
      "fecha_contable": "2026-04-22",
      "fiscal_year": 2026,
      "fiscal_period": 4,
      "invoice_type_code": "F1",
      "special_regime_key": "01",
      "description": "Compra de material",
      "supplier_party_name": "Proveedor Test S.L.",
      "supplier_party_tax_id": "A12345674",
      "supplier_party_country": "es",
      "tax_inclusive_amount": 1210.0,
      "tax_amount": 210.0,
      "cuota_deducible_in_cents": 21000,
      "currency": "EUR",
      "tax_breakdowns": [
        {
          "name": "IVA",
          "category": "S",
          "percent": 21.0,
          "taxable_base": 1000.0,
          "tax_amount": 210.0
        }
      ]
    }
  }'

Camps específics de Recibida:

Camp	Mapeja a l’element AEAT	Notes
`supplier_party_tax_id` / `_name`	`IDEmisorFactura` > `NIF` / `Contraparte` > `NombreRazon`	El proveïdor extern — l’emissor de la factura rebuda.
`supplier_party_country`	`IDOtro` > `CodigoPais`	Quan no és `es`, l’emissor es renderitza via `IDOtro` en lloc de `NIF`.
`tax_point_date`	`FechaOperacion`	Data de l’operació/servei. S’omet quan no es facilita.
`fecha_contable`	`FechaRegContable`	Data en què la factura es va registrar als teus llibres comptables. Si no hi és, utilitza `tax_point_date` i després `invoice_date` com a fallback.
`cuota_deducible_in_cents`	`CuotaDeducible`	Quota deduïble. Quan s’omet, es deriva de `sum(tax_breakdowns.tax_amount)`. Estableix-la explícitament per sobreescriure (deductibilitat parcial, etc.).
`simplified_art7273`	`FacturaSimplificadaArticulos7.2_7.3`	Booleà. Mateixa forma que Expedida.
`reg_previo_ggee`	`RegPrevioGGEEoREDEMEoCompetencia`	Booleà.
`macrodata`	`Macrodato`	Booleà.
`succession_party_*`	`EntidadSucedida`	Igual que Expedida.
`billing_agreement_number`	`NumRegistroAcuerdoFacturacion`	Igual que Expedida.
`external_reference`	`RefExterna`	Igual que Expedida.

Els dos flags exclusius d’Expedida (facturacion_disp_adicional_mercado_gas, sin_identif_destinatario_art_6_1_d) no apareixen a Recibida — l’XSD de l’AEAT els defineix només a FacturaExpedidaType.

El wrapper XML de l’AEAT és SuministroLRFacturasRecibidas.

Proveïdors no espanyols

Quan supplier_party_country no és es, l’emissor s’emet com a IDOtro en lloc de NIF:

<sii:IDEmisorFactura>
  <sii:IDOtro>
    <sii:CodigoPais>FR</sii:CodigoPais>
    <sii:IDType>04</sii:IDType>
    <sii:ID>FR12345678901</sii:ID>
  </sii:IDOtro>
</sii:IDEmisorFactura>

El bloc Contraparte també es renderitza amb IDOtro per fer-ho coincidir.

Altres llibres (Inversion, Intracomunitaria, Metalico, Seguro, Viajesagencia, Cobro, Pago)

Els set llibres restants cobreixen cada un un requisit d’informació específic. Comparteixen els camps CTC comuns i el mateix cicle de vida, però porten escalars específics del llibre. Consulta la referència OpenAPI per a la llista completa de camps.

Inversion (béns d’inversió)

Registra la prorrata anual + la regularització dels béns d’inversió. Wrapper AEAT: SuministroLRBienesInversion. Camps obligatoris (a més del wrapper CTC comú):

identificacion_bien — identificador del bé (IdentificacionBien, màx. 40 caràcters)
fecha_inicio_utilizacion — data en què el bé va entrar en ús (FechaInicioUtilizacion)
prorrata_anual_definitiva — prorrata anual definitiva (ProrrataAnualDefinitiva, 0–100, 2 decimals)

Opcionals: regularizacion_anual_deduccion_in_cents, identificacion_entrega, regularizacion_deduccion_efectuada_in_cents, external_reference, billing_agreement_number, succession_party_*.

Intracomunitaria (operacions intracomunitàries)

Wrapper AEAT: SuministroLRDetOperacionIntracomunitaria. Obligatoris: clave_declarado (enum D o R), external_reference (per l’XSD de l’AEAT), més description mapejat a DescripcionBienes. Opcionals: plazo_operacion, facturas_o_documentacion.

Metalico / Seguro / Viajesagencia (agregats per període)

Aquests llibres s’agreguen per període: un sol registre representa el total d’una contrapart en un període fiscal. No hi ha invoice_number ni invoice_date — l’XSD de l’AEAT omet el bloc IDFactura. La contrapart es facilita via customer_party_* (B2Brouter el reflecteix a nombre_contraparte al servidor).

Metalico: wrapper SuministroLRCobrosMetalico. Agrega els cobraments en efectiu d’una contrapart ≥ 6.000 € en un període fiscal.
Seguro: wrapper SuministroLROperacionesSeguros. Afegeix un ClaveOperacion obligatori mapejat des d’operation_type.
Viajesagencia: wrapper SuministroLRAgenciasViajes. Estructuralment idèntic a Metalico segons l’XSD de l’AEAT.

Cobro / Pago (seguiment de pagaments)

Cobro: cobraments rebuts de factures emeses. Pago: pagaments efectuats de factures rebudes. Tots dos porten un array de pagaments per registre a payload_data:

{
  "payload_data": {
    "cobros": [
      {
        "fecha": "2026-03-01",
        "importe_in_cents": 50000,
        "medio": "01",
        "cuenta_o_medio": "ES1234..."
      },
      {
        "fecha": "2026-04-01",
        "importe_in_cents": 50000,
        "medio": "01",
        "cuenta_o_medio": "ES1234..."
      }
    ]
  }
}

(Utilitza pagos en lloc de cobros per a Pago.)

No existeixen variants A1 ni B per a aquests llibres segons l’XSD de l’AEAT — PATCH i DELETE retornen 422.

Endpoint massiu (asíncron)

Per a integracions d’alt volum (agregacions de punt de venda, migracions CSV a JSON, etc.), utilitza POST /accounts/{ACCOUNT_ID}/tax_report_batches per enviar fins a 5.000 registres en una sola petició. El processament és asíncron: la crida valida només el wrapper i retorna 202 Accepted amb un id de lot; la construcció, validació i assignació al ledger de cada registre s’executen en un procés en segon pla. Llavors has de consultar l’endpoint d’estat del lot (o confiar en el webhook tax_report.state_change per registre quan l’AEAT respongui).

curl --request POST \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_report_batches' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_reports": [
      { "type": "SiiDocument", "book_type": "Expedida", "invoice_number": "INV-001", ... },
      { "type": "SiiDocument", "book_type": "Expedida", "invoice_number": "INV-002", ... },
      ...
    ]
  }'

Resposta acceptada (202):

{
  "batch_id": 4567,
  "status": "processing",
  "total": 2,
  "status_url": "https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_report_batches/4567"
}

Consulta l’estat del lot a GET /accounts/{ACCOUNT_ID}/tax_report_batches/{BATCH_ID}. Mentre el procés s’executa, status és "processing"; un cop finalitzat és "done" i results s’omple, en ordre d’enviament:

{
  "batch_id": 4567,
  "status": "done",
  "summary": { "total": 3, "accepted": 2, "rejected": 1 },
  "results": [
    { "index": 0, "status": "created", "tax_report": { "id": 12345, ... } },
    { "index": 1, "status": "error", "errors": [{ "code": "invalid_book_type", ... }] },
    { "index": 2, "status": "created", "tax_report": { "id": 12346, ... } }
  ]
}

Semàntica:

Asíncron: el 202 significa únicament que el lot ha estat acceptat per al processament — no que s’hagi creat cap registre. Consulta status_url fins que status sigui "done", o consumeix el webhook tax_report.state_change per al resultat de l’AEAT de cada registre creat.
Èxit parcial: cada registre es valida independentment al procés. Un error en un registre (mal book_type, XML invàlid per XSD, type no suportat) no atura el lot — apareix com a error per registre a results.
Errors de wrapper (clau tax_reports absent, no és un array, més de 5.000 registres) retornen HTTP 400 de manera síncrona, abans que res entri a la cua.
Només SII en v1: aquest endpoint accepta únicament type: "SiiDocument". Un type no SII o absent en qualsevol registre es rebutja síncronament amb HTTP 422 (code: "unsupported_type") abans que res entri a la cua — és un error de contracte d’endpoint, diferent dels errors de dades SII per registre (mal book_type, XML invàlid per XSD), que es notifiquen com a errors parcials a l’estat del lot.
Assignació a ledger + enviament: els registres creats s’assignen a ledgers SII segregats per mode agrupats per (document_type_code, NIF de l'empresa reportadora) — és a dir, pel Titular declarat a la Cabecera de l’AEAT, no pel supplier_party_tax_id per registre. Per a Recibida/Pago, aquest camp conté el proveïdor extern, de manera que els registres de proveïdors diferents comparteixen un ledger sempre que pertanyin al mateix llibre i empresa reportadora. Els ledgers s’envien a l’AEAT pel cron per minuts (consulta l’API de Ledgers) — mai al fil de la petició.

Saber quan ha finalitzat el lot

Dues opcions, utilitza l’una o les dues:

Polling a status_url fins que status sigui "done".
Webhook — subscriu un webhook habilitat al teu grup d’integració a l’event sii_batch.finished. Quan el procés d’ingesta finalitza, B2Brouter fa un POST:
```
{
  "code": "sii_batch.finished",
  "triggered_at": 1748000000,
  "data": {
    "batch_id": 4567,
    "status": "done",
    "summary": { "total": 3, "accepted": 2, "rejected": 1 },
    "status_url": "https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_report_batches/4567"
  }
}
```
El cos del webhook conté només el resum (sempre compacte independentment de la mida del lot); crida GET status_url per als resultats complets per registre. El resultat de l’AEAT de cada registre creat continua arribant via el seu propi webhook tax_report.state_change.

API de Ledgers

Els tax reports SII no s’envien individualment a l’AEAT — s’agrupen en “Libros de Registro” (Ledger en termes de B2Brouter), que contenen fins a 5.000 registres per llibre / empresa reportadora (Titular). Cada tax report té un camp ledger_id que apunta a l’ID intern del Ledger. Amb aquest ID pots:

Obtenir la representació XML del Ledger via l’endpoint de descàrrega del ledger. Aquest és el document que B2Brouter envia a l’AEAT.
Obtenir la resposta XML de l’AEAT a aquell Ledger via l’endpoint de descàrrega de la resposta.

Els Ledgers SII moderns es buiden a l’AEAT exclusivament pel cron per minuts impulsat per la política Strategy::Sii (60 segons entre enviaments, o immediatament un cop un Ledger arriba a 5.000 registres). Ni POST /tax_reports, PATCH/DELETE, ni l’endpoint massiu envien mai a l’AEAT al fil de la petició — assignen el/s registre/s i retornen; el cron fa l’enviament. Preveu fins a ~60 s entre la creació i l’enviament.

Equivalència entre els camps interns de tax report de B2Brouter i els nodes XML del SII

Expedida (`SuministroLRFacturasEmitidas`)

Camp de B2Brouter	Node XML de l’AEAT
`fiscal_year`	`PeriodoLiquidacion > Ejercicio`
`fiscal_period`	`PeriodoLiquidacion > Periodo`
`supplier_party_tax_id`	`IDFactura > IDEmisorFactura > NIF`
`invoice_number`	`IDFactura > NumSerieFacturaEmisor`
`invoice_date`	`IDFactura > FechaExpedicionFacturaEmisor`
`invoice_type_code`	`FacturaExpedida > TipoFactura`
`tax_point_date`	`FacturaExpedida > FechaOperacion`
`special_regime_key`	`FacturaExpedida > ClaveRegimenEspecialOTrascendencia`
`billing_agreement_number`	`FacturaExpedida > NumRegistroAcuerdoFacturacion`
`tax_inclusive_amount`	`FacturaExpedida > ImporteTotal`
`description`	`FacturaExpedida > DescripcionOperacion`
`external_reference`	`FacturaExpedida > RefExterna`
`simplified_art7273`	`FacturaExpedida > FacturaSimplificadaArticulos7.2_7.3`
`succession_party_name`	`FacturaExpedida > EntidadSucedida > NombreRazon`
`succession_party_tax_id`	`FacturaExpedida > EntidadSucedida > NIF`
`reg_previo_ggee`	`FacturaExpedida > RegPrevioGGEEoREDEMEoCompetencia`
`macrodata`	`FacturaExpedida > Macrodato`
`facturacion_disp_adicional_mercado_gas`	`FacturaExpedida > FacturacionDispAdicionalTerceraYsextayDelMercadoOrganizadoDelGas`
`sin_identif_destinatario_art_6_1_d`	`FacturaExpedida > FacturaSinIdentifDestinatarioAritculo6.1.d`
`customer_party_name`	`FacturaExpedida > Contraparte > NombreRazon`
`customer_party_tax_id`	`FacturaExpedida > Contraparte > NIF`
`tax_breakdowns[*].percent`	`DetalleIVA > TipoImpositivo`
`tax_breakdowns[*].taxable_base`	`DetalleIVA > BaseImponible`
`tax_breakdowns[*].tax_amount`	`DetalleIVA > CuotaRepercutida` (s’omet quan és zero)

Recibida (`SuministroLRFacturasRecibidas`)

Camp de B2Brouter	Node XML de l’AEAT
`fiscal_year`	`PeriodoLiquidacion > Ejercicio`
`fiscal_period`	`PeriodoLiquidacion > Periodo`
`supplier_party_tax_id`	`IDFactura > IDEmisorFactura > NIF` (o `IDOtro > ID` per no-ES)
`supplier_party_country`	`IDFactura > IDEmisorFactura > IDOtro > CodigoPais` (només no-ES)
`supplier_party_name`	`FacturaRecibida > Contraparte > NombreRazon`
`invoice_number`	`IDFactura > NumSerieFacturaEmisor`
`invoice_date`	`IDFactura > FechaExpedicionFacturaEmisor`
`invoice_type_code`	`FacturaRecibida > TipoFactura`
`tax_point_date`	`FacturaRecibida > FechaOperacion`
`special_regime_key`	`FacturaRecibida > ClaveRegimenEspecialOTrascendencia`
`billing_agreement_number`	`FacturaRecibida > NumRegistroAcuerdoFacturacion`
`tax_inclusive_amount`	`FacturaRecibida > ImporteTotal`
`description`	`FacturaRecibida > DescripcionOperacion`
`external_reference`	`FacturaRecibida > RefExterna`
`simplified_art7273`	`FacturaRecibida > FacturaSimplificadaArticulos7.2_7.3`
`succession_party_name`	`FacturaRecibida > EntidadSucedida > NombreRazon`
`succession_party_tax_id`	`FacturaRecibida > EntidadSucedida > NIF`
`reg_previo_ggee`	`FacturaRecibida > RegPrevioGGEEoREDEMEoCompetencia`
`macrodata`	`FacturaRecibida > Macrodato`
`tax_breakdowns[*].percent`	`DetalleIVA > TipoImpositivo`
`tax_breakdowns[*].taxable_base`	`DetalleIVA > BaseImponible`
`tax_breakdowns[*].tax_amount`	`DetalleIVA > CuotaSoportada` (s’omet quan és zero)
`fecha_contable`	`FacturaRecibida > FechaRegContable`
`cuota_deducible_in_cents`	`FacturaRecibida > CuotaDeducible`

`category` del desglossament fiscal → bucket de desglose

Cada tax_breakdowns[*].category (el codi de categoria d’IVA estàndard PEPPOL/UN-CEFACT) determina en quin bucket de desglose de l’AEAT aterra la línia. Aquest és el senyal canònic — envia la category correcta; els flags booleants es deriven d’ella.

Expedida (TipoDesglose > DesgloseFactura):

`category`	Bucket AEAT
`S`, `Z`, `H`, `AA`, `AAA`, `N1` (subjecte)	`Sujeta > NoExenta`, `TipoNoExenta` = `S1`
`AE` (inversió del subjecte passiu)	`Sujeta > NoExenta`, `TipoNoExenta` = `S2`
`E`, `K`, `N2.*`, `N3.2`, `N3.6`, `N4`, `N5`, `N7`, `IC` (exempt)	`Sujeta > Exenta > DetalleExenta` (`CausaExencion` ← `exemption_code`)
`NS`, `O`, `G`, `N3.1`, `N3.3`–`N3.5` (no subjecte)	`NoSujeta` (`ImporteTAIReglasLocalizacion` quan `no_subject_code` = `RL`, altrament `ImportePorArticulos7_14_Otros`)

Una combinació de línies S1 i S2 col·lapsa a un únic TipoNoExenta = S3. Una línia sense categoria reconeguda es renderitza com a S1 (totalment subjecta).

Recibida (DesgloseFactura): les línies amb inversió del subjecte passiu (category AE) van a InversionSujetoPasivo; la resta a DesgloseIVA.

Encara no suportat: DesgloseTipoOperacion (la divisió béns/serveis que l’AEAT requereix per a alguns contraparts transfronterers). Les factures que el necessitin han d’utilitzar la ruta CSV legacy fins que una versió posterior n’afegeixi el suport — es replica el diferiment de DatosInmueble per a béns immobles.

Fitxers XSD

L’AEAT publica els XSD canònics del SII. B2Brouter valida l’XML renderitzat contra SuministroInformacion.xsd i SuministroLR.xsd (v1.1) en cada enviament. Els esquemes es troben en aquest repositori a vendor/xsd-validator/lib/xsd/schemas/sii_v11/.

Descripció dels codis per a camps específics

`book_type`

Els valors es llisten a Què és el SII? més amunt. El book_type determina el wrapper XML de l’AEAT, el conjunt de camps obligatoris i les regles de validació.

`invoice_type_code`

Per a Expedida i Recibida:

F1 — Factura (art. 6, 7.2 y 7.3 del RD 1619/2012)
F2 — Factura Simplificada y Facturas sin identificación del destinatario (art. 6.1.d) RD 1619/2012
F3 — Factura emitida en sustitución de facturas simplificadas facturadas y declaradas
F4 — Asiento resumen de facturas
F5 — Importaciones (DUA)
F6 — Otros justificantes contables
R1 — Factura Rectificativa (Error fundado en derecho y Art. 80 Uno Dos y Seis LIVA)
R2 — Factura Rectificativa (Art. 80.3)
R3 — Factura Rectificativa (Art. 80.4)
R4 — Factura Rectificativa (Resto)
R5 — Factura Rectificativa en facturas simplificadas

`special_regime_key` (`ClaveRegimenEspecialOTrascendencia`)

Un codi de dos dígits de l’AEAT que descriu el règim especial aplicat a l’operació. Els valors més habituals són 01 (régimen general), 02 (exportaciones), 03 (régimen especial bienes usados), 04 (régimen especial oro de inversión), 05 (régimen especial agencias de viajes), 06 (régimen especial grupo de entidades), 07 (régimen especial criterio de caja), 08 (operaciones IPSI / IGIC). Consulta les especificacions de l’AEAT per a la llista completa i l’aplicabilitat per llibre.

`clave_declarado` (només Intracomunitaria)

D — Declarante
R — Receptor

Comprovació d’errors

B2Brouter valida els payloads SII contra els XSD de l’AEAT abans de qualsevol enviament. Un error de validació retorna HTTP 422 amb els camps que fallen detallats en JSON. Si l’AEAT mateixa rebutja un enviament (p. ex. NIF de contrapart desconegut), el rebuig es reflecteix a l’state del registre (normalment error o registered_with_errors) i als camps error_code / error_description de l’AEAT. Configura el webhook de tax report per reaccionar als estats finals sense polling.

[Beta] Informa registres d'IVA a l'AEAT via SII (Suministro Inmediato de Información) amb l'API de B2Brouter

Què és el SII?

Configuració i treball amb l’API de B2Brouter

API Tax Report

Crear un Tax Report

Cicle de vida

Obtenir la representació XML

Corregir un Tax Report (A1)

Cancel·lar un Tax Report (B)

Llistar Tax Reports

Expedida (factures emeses)

Exemple de petició

Recibida (factures rebudes)

Exemple de petició

Proveïdors no espanyols

Altres llibres (Inversion, Intracomunitaria, Metalico, Seguro, Viajesagencia, Cobro, Pago)

Inversion (béns d’inversió)

Intracomunitaria (operacions intracomunitàries)

Metalico / Seguro / Viajesagencia (agregats per període)

Cobro / Pago (seguiment de pagaments)

Endpoint massiu (asíncron)

Saber quan ha finalitzat el lot

API de Ledgers

Equivalència entre els camps interns de tax report de B2Brouter i els nodes XML del SII

Expedida (SuministroLRFacturasEmitidas)

Recibida (SuministroLRFacturasRecibidas)

category del desglossament fiscal → bucket de desglose

Fitxers XSD

Descripció dels codis per a camps específics

book_type

invoice_type_code

special_regime_key (ClaveRegimenEspecialOTrascendencia)

clave_declarado (només Intracomunitaria)

Comprovació d’errors

Expedida (`SuministroLRFacturasEmitidas`)

Recibida (`SuministroLRFacturasRecibidas`)

`category` del desglossament fiscal → bucket de desglose

`book_type`

`invoice_type_code`

`special_regime_key` (`ClaveRegimenEspecialOTrascendencia`)

`clave_declarado` (només Intracomunitaria)