Ejemplos fiscales de factura

La facturación española cubre muchos escenarios fiscales — B2B nacional, bienes y servicios intracomunitarios, ventas a distancia OSS, IGIC en Canarias, IPSI en Ceuta/Melilla, retención IRPF, recargo de equivalencia, operaciones exentas y no sujetas. La parte difícil es acertar la combinación correcta de tax_rate, exemption_reason, regime_key, retention_rate y surcharge_rate en cada línea.

Para hacerlo concreto, la Referencia de la API incluye cuatro ejemplos de request nombrados y listos para enviar en POST /v1/companies/{company}/invoices — un conjunto curado y representativo, no uno por escenario. Cada uno es un payload válido que puedes copiar, adaptar y enviar: elige el más cercano a tu caso en el desplegable de ejemplos del request body y apóyate en la tabla siguiente y en la guía enlazada en cada fila para el resto.

Todas las rutas de esta guía cuelgan de /v1/companies/{company}/…: {company} es el id (UUID v7) del NIF con el que operas, y en los ejemplos curl es $COMPANY_ID. Alcanzar un NIF explica cómo resolverlo.

Los 21 escenarios

Cada fila de abajo es un escenario que puedes expresar línea a línea con los campos anteriores. Los cuatro marcados con ★ son además ejemplos de request nombrados que puedes elegir directamente en el desplegable; los otros diecisiete están documentados aquí y en la guía enlazada, pero no tienen ejemplo nombrado en el spec — constrúyelos a partir del marcado más cercano.

Cada uno de los cuatro ejemplos marcados también se publica como una entrada reutilizable components.examples.invoice_* en el spec OpenAPI, para que los SDK y el tooling puedan resolverlos por $ref.

Una factura completa con datos estructurados

Una factura completa para un cliente público que lleva todos los bloques estructurados del contrato: referencias de cabecera y de línea, periodo de facturación, literales legales, los cuatro centros DIR3 y un calendario de pagos. La línea suma 121.00 (100 más 21% de IVA) y los tres vencimientos suman esos mismos 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é debe cumplir cada bloque:

• business_references (cabecera) tiene exactamente tres claves, de hasta 20 caracteres cada una; las fechas y las referencias del emisor viven en la línea.
• administrative_centres contiene como máximo un centro por role_code (01 oficina contable, 02 órgano gestor, 03 unidad tramitadora, 04 órgano proponente). code es un código DIR3 de 9 o 10 caracteres alfanuméricos que empieza por letra; name es opcional, de hasta 40 caracteres. Enviar [] no selecciona ningún centro.
• Las filas de payment_terms conservan tu orden, las fechas no decrecen, los importes son cadenas de dos decimales y suman exactamente total_to_pay. Los códigos de pago 02 y 04 llevan la account; el resto no.
• delivery_notes_references[].number tiene hasta 30 caracteres y date es opcional.

La respuesta es 201 con la factura, que ahora devuelve la identidad persistida de cada vencimiento (payment_terms[].id, UUID v7), payment_terms_version y administrative_version. Guárdalas: cualquier cambio posterior de un calendario existente o del encaminamiento reenvía la versión (expected_payment_terms_version, expected_version de las revisiones administrativas), y si falta la versión responde 428.

Si un vencimiento es incorrecto, por ejemplo "40.5" en lugar de "40.50", no se escribe nada:

{
  "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 lleva vencimientos con signo con la misma regla: "-20.00" y "-30.00". Consulta Facturas rectificativas y Datos de negocio de la factura.

Facturas rectificativas por código R

Una factura rectificativa lleva el código de rectificación de la AEAT que indica por qué se corrige la original. POST /v1/companies/{company}/invoices/{id}/corrective incluye un ejemplo nombrado por cada código, cada uno un payload válido que produce ese correction_code exacto:

Pasa correction_code explícitamente para seleccionar el código R; R5 solo aplica a facturas simplificadas (F2).