Exemples fiscals de factura

La facturació espanyola cobreix molts escenaris fiscals — B2B nacional, béns i serveis intracomunitaris, vendes a distància OSS, IGIC a Canàries, IPSI a Ceuta/Melilla, retenció IRPF, recàrrec d'equivalència, operacions exemptes i no subjectes. La part difícil és encertar la combinació correcta de tax_rate, exemption_reason, regime_key, retention_rate i surcharge_rate a cada línia.

Per fer-ho concret, la Referència de l'API inclou quatre exemples de request amb nom i llestos per enviar a POST /v1/companies/{company}/invoices — un conjunt curat i representatiu, no un per escenari. Cadascun és un payload vàlid que pots copiar, adaptar i enviar: tria el més proper al teu cas al desplegable d'exemples del request body i recolza't en la taula següent i en la guia enllaçada a cada fila per a la resta.

Totes les rutes d'aquesta guia pengen de /v1/companies/{company}/…: {company} és l'id (UUID v7) del NIF amb què operes, i als exemples curl és $COMPANY_ID. Arribar a un NIF explica com resoldre'l.

Els 21 escenaris

Cada fila de sota és un escenari que pots expressar línia a línia amb els camps anteriors. Els quatre marcats amb ★ són a més exemples de request amb nom que pots triar directament al desplegable; els altres disset estan documentats aquí i a la guia enllaçada, però no tenen exemple amb nom al spec — construeix-los a partir del marcat més proper.

Cadascun dels quatre exemples marcats també es publica com una entrada reutilitzable components.examples.invoice_* al spec OpenAPI, perquè els SDK i el tooling els puguin resoldre per $ref.

Una factura completa amb dades estructurades

Una factura completa per a un client públic que porta tots els blocs estructurats del contracte: referències de capçalera i de línia, període de facturació, literals legals, els quatre centres DIR3 i un calendari de pagaments. La línia suma 121.00 (100 més 21% d'IVA) i els tres venciments sumen aquests mateixos 121.00.

curl -X POST https://api.factuarea.com/v1/companies/$COMPANY_ID/invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "019e0000-0000-7000-8000-0000000000f1",
    "series_id": "019e0000-0000-7000-8000-0000000000f2",
    "issued_on": "2026-01-15",
    "due_on": "2026-04-15",
    "business_references": {
      "receiver_contract_reference": "CON-2026-1",
      "receiver_transaction_reference": "PED-2026-1",
      "file_reference": "EXP-2026-1"
    },
    "invoicing_period": { "start_date": "2026-01-01", "end_date": "2026-01-31" },
    "legal_literals": ["Pago sujeto al contrato indicado."],
    "administrative_centres": [
      { "role_code": "01", "code": "L01000001", "name": "Oficina contable" },
      { "role_code": "02", "code": "L01000002", "name": "Órgano gestor" },
      { "role_code": "03", "code": "L01000003", "name": "Unidad tramitadora" },
      { "role_code": "04", "code": "L01000004", "name": "Órgano proponente" }
    ],
    "lines": [
      {
        "description": "Servicio contratado",
        "quantity": 1,
        "unit_price": 100,
        "tax_rate": 21,
        "business_references": {
          "issuer_contract_reference": "REF-2026-01",
          "issuer_contract_date": "2026-01-10"
        },
        "delivery_notes_references": [{ "number": "ALB-2026-1", "date": "2026-01-10" }]
      }
    ],
    "payment_terms": [
      { "due_date": "2026-02-15", "amount": "40.00", "payment_means": "01" },
      { "due_date": "2026-03-15", "amount": "30.00", "payment_means": "04",
        "account": { "iban": "ES9121000418450200051332", "bic": "CAIXESBBXXX" } },
      { "due_date": "2026-04-15", "amount": "51.00", "payment_means": "04",
        "account": { "iban": "ES9121000418450200051332", "bic": "CAIXESBBXXX" } }
    ]
  }'

Què ha de complir cada bloc:

• business_references (capçalera) té exactament tres claus, de fins a 20 caràcters cadascuna; les dates i les referències de l'emissor viuen a la línia.
• administrative_centres conté com a màxim un centre per role_code (01 oficina comptable, 02 òrgan gestor, 03 unitat tramitadora, 04 òrgan proposant). code és un codi DIR3 de 9 o 10 caràcters alfanumèrics que comença per lletra; name és opcional, de fins a 40 caràcters. Enviar [] no selecciona cap centre.
• Les files de payment_terms conserven el teu ordre, les dates no decreixen, els imports són cadenes de dos decimals i sumen exactament total_to_pay. Els codis de pagament 02 i 04 porten l'account; la resta no.
• delivery_notes_references[].number té fins a 30 caràcters i date és opcional.

La resposta és 201 amb la factura, que ara retorna la identitat persistida de cada venciment (payment_terms[].id, UUID v7), payment_terms_version i administrative_version. Desa-les: qualsevol canvi posterior d'un calendari existent o de l'encaminament reenvia la versió (expected_payment_terms_version, expected_version de les revisions administratives), i si falta la versió respon 428.

Si un venciment és incorrecte, per exemple "40.5" en lloc de "40.50", no s'escriu res:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_invoice_payment_terms",
    "message": "Las condiciones de pago de la factura no son válidas.",
    "param": "payment_terms.1.amount",
    "request_id": "req_..."
  }
}

Una factura rectificativa de -50.00 porta venciments amb signe amb la mateixa regla: "-20.00" i "-30.00". Consulta Factures rectificatives i Dades de negoci de la factura.

Factures rectificatives per codi R

Una factura rectificativa porta el codi de rectificació de l'AEAT que indica per què es corregeix l'original. POST /v1/companies/{company}/invoices/{id}/corrective inclou un exemple amb nom per cada codi, cadascun un payload vàlid que produeix aquest correction_code exacte:

Passa correction_code explícitament per seleccionar el codi R; R5 només aplica a factures simplificades (F2).