Factuarea API

Recetario fiscal

Seis recetas de extremo a extremo — emitir y esperar la aceptación de la AEAT, corregir un importe, sustituir facturas simplificadas, repercutir un suplido, facturar fuera de la UE y reparar un registro rechazado.

Cada receta de abajo es una secuencia completa de llamadas, con su equivalente en el CLI factuarea, y un enlace a la guía que explica por qué se hace así. Las guías llevan el razonamiento fiscal; esta página lleva el orden de las operaciones.

El árbol de comandos del CLI se genera a partir del documento OpenAPI, así que todo endpoint es alcanzable como comando con nombre propio o mediante la vía de escape genérica factuarea api <method> <path>. Las recetas usan la vía de escape allí donde la forma con nombre sería adivinar; ambas llegan al mismo endpoint de la v1. Ver Uso del CLI.

Fija tu clave una sola vez:

export FACTUAREA_KEY="fact_live_3pXnR2VbY7TcA9eFmN5z8KqW"

Qué relación tiene esta página con las otras cuatro preguntas

Cada guía fiscal responde a cuatro preguntas sobre su escenario. Esta página es un recetario, así que las responde por delegación, y lo dice en vez de omitir las secciones.

Cuándo aplica cada receta

Se declara al principio de cada receta como su objetivo. Las condiciones previas —qué estado de factura admite qué operación, qué tipos de documento son elegibles— pertenecen a la guía enlazada y no se repiten aquí.

Qué envía la API

Es la única dimensión que la página cubre por completo: cada receta muestra la petición íntegra y su equivalente en el CLI, con nombres de campo reales del contrato v1.

Qué sale en el PDF

No se cubre aquí. Ninguna receta cambia el documento impreso más allá de lo que ya describe su guía — el bloque QR legal, las filas de suplidos del bloque de totales, la numeración propia de la rectificativa. Ver Suplidos y Facturas rectificativas.

Qué llega a la AEAT

No se cubre aquí. Las declaraciones que producen estas secuencias se describen en Estados de envío VeriFactu y, por escenario, en cada guía enlazada. La receta 1 es la única cuyo propósito es observar la declaración, y lo hace leyendo el registro de facturación.

1 · Emitir una factura y esperar la aceptación de la AEAT

Objetivo: crear, emitir y confirmar que la Administración tributaria la dio de alta.

Crear y emitir en una sola llamada. options.issue_directly ahorra el paso de envío por separado, y los dos eventos que dispara no pueden producir un alta duplicada — el comando es idempotente por 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}}'

Consultar el registro de facturación hasta que salga de los estados no finales. Lee status y, una vez aceptado, aeat_csv — ese es el valor con el que concilias contra la Administración tributaria.

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 deja de consultar. Suscríbete en su lugar a los eventos de webhook de VeriFactu de la factura y reacciona cuando llegue el desenlace. Ver Webhooks.

Fundamentos: Alta automática en VeriFactu para las compuertas que deciden si llega a crearse un registro, y Estados de envío VeriFactu para el significado de cada estado.

2 · Corregir un error de importe

Objetivo: una factura emitida cobró de más. Reducirla sin anularla.

Una corrección a la baja es una rectificativa por diferencias, con importes negativos. correction_type: "partial" produce esa naturaleza; una sustitución no podría llevar 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}]}'

Respuesta: 201 con la nueva factura rectificativa y una cabecera Location. Lista todas las rectificativas emitidas contra el original con GET /v1/invoices/{id}/correctives.

Fundamentos: Facturas rectificativas. Si la factura sigue sin cobrar y lo que está mal es el documento entero y no un importe, mira antes Anular o rectificar — puede que la operación correcta sea la anulación.

3 · Sustituir facturas simplificadas por una completa

Objetivo: un cliente que ha ido acumulando varios tiques necesita ahora una sola factura deducible.

Una llamada. Pasas el destinatario y las facturas simplificadas que hay que agregar, y recibes una factura sustitutiva completa, ya emitida:

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"}'

Los originales no se anulan: conservan su estado fiscal y dejan constancia de que han sido sustituidos.

Fundamentos: Facturas simplificadas o completas.

4 · Repercutir un suplido

Objetivo: facturar tus honorarios más una tasa que pagaste por cuenta del cliente, sin que la tasa entre en tu base imponible.

La línea de suplido no lleva carga fiscal propia y debe llevar la referencia de origen. Se exige al menos una línea ordinaria junto a ella.

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"}]}'

Comprueba la respuesta: total vale 1210, total_disbursements vale 150 y total_to_pay vale 1360. Cobra y concilia contra total_to_pay, no contra total.

Fundamentos: Suplidos.

5 · Facturar a un cliente de fuera de la UE

Objetivo: una exportación, exenta por el art. 21 LIVA.

Crear el cliente con una identificación alternativa. El tipo tiene que ser legal para el país — un número de IVA intracomunitario no lo es.

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" }
      }'

Emitir con la exención declarada por línea. El régimen de cabecera es de solo lectura en la API pública, así que la exención se declara en la línea:

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" }
        ]
      }'

Fundamentos: Clientes internacionales — y lee su aviso sobre la inversión del sujeto pasivo antes de dar por hecho que la misma forma vale para los servicios.

6 · Reparar un registro que la AEAT rechazó

Objetivo: la Administración tributaria rechazó la declaración por un error de datos. Arreglarlo sin anular la factura.

Confirma que es un rechazo y no un fallo técnico. Un estado rejected significa que la AEAT leyó la declaración; error significa que nunca llegó y se reintenta de forma automática.

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

Corrige el dato en su origen. La declaración se regenera a partir de la factura y de los datos maestros actuales — corrige el NIF o la razón social del cliente y los valores nuevos se recogen solos.

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"}'

Reenvía. Sin cuerpo de petición: el contenido se regenera en el 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 desenlace. El registro se transmite de nuevo y acaba aceptado — o rechazado otra vez si el dato sigue mal, en cuyo caso puedes repetir. Este camino no tiene límite de intentos.

Si la respuesta es un 422 que te dice que hace falta anular, la corrección toca un campo de la huella —el total, el número, la fecha, el NIF del emisor o el tipo de factura— y el registro no se puede reparar en el sitio.

Fundamentos: Subsanación de registros VeriFactu para la tabla completa de errores, y Estados de envío VeriFactu para reintento frente a subsanación.

Trazabilidad

Esta página no declara ninguna regla fiscal propia: encadena llamadas cuyo fundamento está establecido en otro sitio. Cada receta hereda la trazabilidad de la guía que enlaza:

RecetaHereda de
Emitir y esperarAlta automática en VeriFactu · Estados de envío VeriFactu
Corregir un importeFacturas rectificativas · Anular o rectificar
Sustituir simplificadasFacturas simplificadas o completas
Repercutir un suplidoSuplidos
Facturar fuera de la UEClientes internacionales · Clasificación fiscal y exenciones por línea
Reparar un registro rechazadoEstados de envío VeriFactu

Clientes internacionales

Alcance y limitaciones

En esta página

Qué relación tiene esta página con las otras cuatro preguntasCuándo aplica cada recetaQué envía la APIQué sale en el PDFQué llega a la AEAT1 · Emitir una factura y esperar la aceptación de la AEAT2 · Corregir un error de importe3 · Sustituir facturas simplificadas por una completa4 · Repercutir un suplido5 · Facturar a un cliente de fuera de la UE6 · Reparar un registro que la AEAT rechazóTrazabilidad