Factuarea API

Receptari fiscal

Sis receptes d'extrem a extrem — emetre i esperar l'acceptació de l'AEAT, corregir un import, substituir factures simplificades, repercutir un suplert, facturar fora de la UE i reparar un registre rebutjat.

Cada recepta de baix és una seqüència completa de crides, amb el seu equivalent al CLI factuarea, i un enllaç a la guia que explica per què es fa d'aquesta manera. Les guies porten el raonament fiscal; aquesta pàgina porta l'ordre de les operacions.

L'arbre de comandes del CLI es genera a partir del document OpenAPI, així que cada endpoint és assolible o bé com a comanda amb nom o bé a través de la via d'escapament genèrica factuarea api <method> <path>. Les receptes fan servir la via d'escapament allà on la forma amb nom seria endevinar; totes dues piquen el mateix endpoint de la v1. Vegeu Ús del CLI.

Fixa la teva clau un sol cop:

export FACTUAREA_KEY="fact_live_3pXnR2VbY7TcA9eFmN5z8KqW"

Quina relació té aquesta pàgina amb les altres quatre preguntes

Cada guia fiscal respon quatre preguntes sobre el seu escenari. Aquesta pàgina és un receptari, així que les respon per delegació, i ho diu en lloc d'ometre les seccions.

Quan aplica cada recepta

Es diu al capdamunt de cada recepta com el seu objectiu. Les condicions prèvies —quin estat de factura admet quina operació, quins tipus de document són admissibles— pertanyen a la guia enllaçada i no es repeteixen aquí.

Què envia l'API

És l'única dimensió que la pàgina cobreix del tot: cada recepta mostra la petició completa i el seu equivalent al CLI, amb noms de camp reals del contracte v1.

Què surt al PDF

No es cobreix aquí. Cap recepta no canvia el document imprès més enllà del que la seva guia ja descriu — el bloc QR legal, les files de suplerts al bloc de totals, la numeració pròpia de la rectificativa. Vegeu Suplerts i Factures rectificatives.

Què arriba a l'AEAT

No es cobreix aquí. Les declaracions que produeixen aquestes seqüències es descriuen a Estats d'enviament VeriFactu i, per escenari, a cada guia enllaçada. La recepta 1 és l'única el propòsit de la qual és observar la declaració, i ho fa llegint el registre de facturació.

1 · Emetre una factura i esperar l'acceptació de l'AEAT

Objectiu: crear, emetre i confirmar que l'Administració tributària l'ha donada d'alta.

Crear i emetre en una sola crida. options.issue_directly estalvia el pas d'enviament separat, i els dos esdeveniments que dispara no poden produir una alta duplicada — la comanda és idempotent per factura.

curl -X POST https://api.factuarea.com/v1/invoices \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "client_id": "0197a2a8-4cf0-7a31-9a5e-3f2b8c1d6e42",
        "series_id": "019e5584-7a72-7038-a8f6-561ed180b699",
        "issued_on": "2026-06-01",
        "due_on": "2026-07-01",
        "lines": [
          { "description": "Servicio de consultoría", "quantity": 2, "unit_price": 150, "tax_rate": 21, "regime_key": "01" }
        ],
        "options": { "issue_directly": true }
      }'
factuarea invoices create -d '{"client_id":"…","series_id":"…","issued_on":"2026-06-01","due_on":"2026-07-01","lines":[{"description":"Servicio de consultoría","quantity":2,"unit_price":150,"tax_rate":21,"regime_key":"01"}],"options":{"issue_directly":true}}'

Consulta el registre de facturació fins que surti dels estats no finals. Llegeix status i, un cop acceptat, aeat_csv — aquest és el valor amb què concilies contra l'Administració tributària.

curl https://api.factuarea.com/v1/invoices/{invoice_id}/verifactu \
  -H "Authorization: Bearer $FACTUAREA_KEY"
factuarea api get /v1/invoices/{invoice_id}/verifactu --json

O deixa de consultar. Subscriu-te als esdeveniments de webhook VeriFactu de la factura i reacciona quan arribi el resultat. Vegeu Webhooks.

Fonaments: Alta automàtica a VeriFactu per a les comportes que decideixen si arriba a crear-se cap registre, i Estats d'enviament VeriFactu per a què significa cada estat.

2 · Corregir un error d'import

Objectiu: una factura emesa va cobrar de més. Reduir-la sense anul·lar-la.

Una correcció a la baixa és una rectificativa per diferències, amb imports negatius. correction_type: "partial" produeix aquesta naturalesa; una substitució no podria portar una base negativa.

curl -X POST https://api.factuarea.com/v1/invoices/{invoice_id}/corrective \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "correction_reason": "error_importe",
        "correction_type": "partial",
        "lines": [
          { "description": "Ajuste por error de importe", "quantity": -1, "unit_price": 200, "tax_rate": 21 }
        ]
      }'
factuarea api post /v1/invoices/{invoice_id}/corrective -d '{"correction_reason":"error_importe","correction_type":"partial","lines":[{"description":"Ajuste por error de importe","quantity":-1,"unit_price":200,"tax_rate":21}]}'

Resposta: 201 amb la factura rectificativa nova i una capçalera Location. Llista totes les rectificatives emeses contra l'original amb GET /v1/invoices/{id}/correctives.

Fonaments: Factures rectificatives. Si la factura encara està sense cobrar i el que està malament és el document sencer i no un import, mira abans Anul·lar o rectificar — l'anul·lació pot ser l'operació correcta.

3 · Substituir factures simplificades per una de completa

Objectiu: un client que ha anat acumulant diversos tiquets necessita ara una factura deduïble.

Una sola crida. Passes el destinatari i les factures simplificades que vols agregar, i reps una factura substitutiva completa, ja emesa:

curl -X POST https://api.factuarea.com/v1/invoices/substitute-simplified \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "client_id": "0197a2a8-4cf0-7a31-9a5e-3f2b8c1d6e42",
        "simplified_invoice_ids": [
          "0197b1c2-3d4e-7f50-8a61-b2c3d4e5f601",
          "0197b1c2-3d4e-7f50-8a61-b2c3d4e5f602"
        ],
        "notes": "Consumos de junio"
      }'
factuarea api post /v1/invoices/substitute-simplified -d '{"client_id":"…","simplified_invoice_ids":["…","…"],"notes":"Consumos de junio"}'

Els originals no s'anul·len: conserven el seu estat fiscal i deixen constància que han estat substituïts.

Fonaments: Factures simplificades o completes.

4 · Repercutir un suplert

Objectiu: facturar els teus honoraris més una taxa que vas pagar per compte del client, sense que la taxa entri a la teva base imposable.

La línia de suplert no porta càrrega fiscal pròpia i ha de portar la referència d'origen. Al seu costat es requereix almenys una línia ordinària.

curl -X POST https://api.factuarea.com/v1/invoices \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "client_id": "0197a2a8-4cf0-7a31-9a5e-3f2b8c1d6e42",
        "series_id": "019e5584-7a72-7038-a8f6-561ed180b699",
        "issued_on": "2026-06-01",
        "due_on": "2026-07-01",
        "lines": [
          { "description": "Honorarios de constitución de sociedad", "quantity": 1, "unit_price": 1000, "tax_rate": 21 },
          { "description": "Tasa del Registro Mercantil", "quantity": 1, "unit_price": 150,
            "line_type": "SUPLIDO", "source_invoice_reference": "RM-2026-0451" }
        ]
      }'
factuarea invoices create -d '{"client_id":"…","series_id":"…","issued_on":"2026-06-01","due_on":"2026-07-01","lines":[{"description":"Honorarios","quantity":1,"unit_price":1000,"tax_rate":21},{"description":"Tasa del Registro Mercantil","quantity":1,"unit_price":150,"line_type":"SUPLIDO","source_invoice_reference":"RM-2026-0451"}]}'

Comprova la resposta: total és 1210, total_disbursements és 150 i total_to_pay és 1360. Cobra i concilia contra total_to_pay, no contra total.

Fonaments: Suplerts.

5 · Facturar a un client de fora de la UE

Objectiu: una exportació, exempta per l'art. 21 LIVA.

Crea el client amb una identificació alternativa. El tipus ha de ser legal per al país — un número d'IVA intracomunitari no ho és.

curl -X POST https://api.factuarea.com/v1/clients \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Acme Inc",
        "alternative_id": { "type": "passport", "value": "X1234567", "country_code": "US" }
      }'

Emet amb l'exempció declarada per línia. El règim de capçalera és de només lectura per l'API pública, així que l'exempció es declara a la línia:

curl -X POST https://api.factuarea.com/v1/invoices \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "client_id": "{client_id}",
        "series_id": "019e5584-7a72-7038-a8f6-561ed180b699",
        "issued_on": "2026-06-01",
        "due_on": "2026-07-01",
        "notes": "Operación exenta por exportación (art. 21 LIVA)",
        "lines": [
          { "description": "Suministro de equipos", "quantity": 1, "unit_price": 4000,
            "tax_rate": 0, "exemption_reason": "E2", "regime_key": "02" }
        ]
      }'

Fonaments: Clients internacionals — i llegeix la seva nota sobre la inversió del subjecte passiu abans de donar per fet que la mateixa forma serveix per als serveis.

6 · Reparar un registre que l'AEAT ha rebutjat

Objectiu: l'Administració tributària ha rebutjat la declaració per un error de dades. Arreglar-ho sense anul·lar la factura.

Confirma que és un rebuig, no una fallada tècnica. Un estat rejected vol dir que l'AEAT ha llegit la declaració; error vol dir que no hi va arribar mai i que es reintenta automàticament.

curl "https://api.factuarea.com/v1/verifactu/records?status=rejected" \
  -H "Authorization: Bearer $FACTUAREA_KEY"

Corregeix les dades al seu origen. La declaració es regenera des de la factura i les dades mestres actuals — corregeix el NIF o la raó social del client i els valors nous es recullen.

curl -X PUT https://api.factuarea.com/v1/clients/{client_id} \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tax_id": "B12345678"}'

Reenvia. Sense cos de petició: el contingut es regenera al servidor.

curl -X POST https://api.factuarea.com/v1/verifactu/records/{record_id}/subsanar \
  -H "Authorization: Bearer $FACTUAREA_KEY"
factuarea api post /v1/verifactu/records/{record_id}/subsanar --json

Vigila el resultat. El registre es transmet de nou i acaba acceptat — o rebutjat un altre cop si les dades continuen malament, i en aquest cas pots repetir. En aquest camí no hi ha límit d'intents.

Si la resposta és un 422 que t'indica que cal una anul·lació, la correcció toca un camp de la huella — el total, el número, la data, el NIF de l'emissor o el tipus de factura — i el registre no es pot reparar al lloc.

Fonaments: Esmena de registres VeriFactu per a la taula d'errors completa, i Estats d'enviament VeriFactu per a reintent contra esmena.

Traçabilitat

Aquesta pàgina no declara cap regla fiscal pròpia: seqüencia crides els fonaments de les quals s'estableixen en un altre lloc. Cada recepta hereta la traçabilitat de la guia que enllaça:

ReceptaHereta de
Emetre i esperarAlta automàtica a VeriFactu · Estats d'enviament VeriFactu
Corregir un importFactures rectificatives · Anul·lar o rectificar
Substituir simplificadesFactures simplificades o completes
Repercutir un suplertSuplerts
Facturar fora de la UEClients internacionals · Classificació fiscal i exempcions per línia
Reparar un registre rebutjatEstats d'enviament VeriFactu

Clients internacionals

Abast i limitacions

En aquesta pàgina

Quina relació té aquesta pàgina amb les altres quatre preguntesQuan aplica cada receptaQuè envia l'APIQuè surt al PDFQuè arriba a l'AEAT1 · Emetre una factura i esperar l'acceptació de l'AEAT2 · Corregir un error d'import3 · Substituir factures simplificades per una de completa4 · Repercutir un suplert5 · Facturar a un client de fora de la UE6 · Reparar un registre que l'AEAT ha rebutjatTraçabilitat