Ejemplos

Ejemplos de la API VeriFactu: de la factura básica a la rectificativa

Los tipos de factura que emite un TPV o un ERP, con el JSON que envías a KubiFACTU en cada caso. En cada ejemplo hemos resaltado lo que cambia respecto a la factura básica.

Empezar en pruebas Documentación completa

Antes de empezar

Lo que tienen en común todas las peticiones

Cambia el cuerpo JSON de una factura a otra, pero la forma de llamar a la API es siempre la misma.

POST /api/invoices envía un registro de facturación. La URL base es devapi.kubifactu.com en pruebas y api.kubifactu.com en producción.
X-Qbikode-ClientApiKey lleva la API-KEY de la empresa emisora, y Accept va con application/json.
sif_id identifica el sistema informático de facturación (SIF) de esa empresa, y sender_data a la propia empresa.
Los importes, los números y los NIF son ficticios, los mismos que usa la documentación.

La respuesta con el estado, la huella y el QR la tienes en cómo funciona. Las anulaciones, las consultas y los lotes de hasta 500 registros tienen sus propios endpoints en la documentación (abre en nueva pestaña).

Facturas ordinarias

El caso base: un alta de factura con destinatario identificado, en el momento o en diferido, a un cliente español o extranjero.

Factura ordinaria (F1)

Alta de una factura ordinaria de 121,00 €: un concepto de 100,00 € más IVA del 21 %, a una empresa española.

invoice_type_key con el valor F1: factura de los artículos 6, 7.2 y 7.3 del RD 1619/2012.
recipients identifica al destinatario por su NIF (tax_id_number).
tax_breakdown lleva el desglose del impuesto: base, tipo y cuota del IVA.

Ver este ejemplo en la documentación

POST /api/invoices

{  "sif_id": "9db0bca1-187e-4cf4-b87c-96f2044008d7",  "invoice_type_key": "F1", // Factura (art. 6, 7.2 y 7.3 del RD 1619/2012)  "sender_data": {    "company_name": "Empresa emisora de ejemplo",    "tax_id_number": "J27290840"  },  "recipients": [    {      "company_name": "Empresa receptora de ejemplo",      "tax_id_number": "B99014037"    }  ],  "full_invoice_number": "2026-000001",  "fiscal_year": 2026,  "issue_date": "2026-01-01",  "operation_description": "Factura ordinaria por entrega de mercancías.",  "total_quota": 21.00,  "total_amount": 121.00,  "tax_breakdown": [    {      "tax_type_key": "01", // Impuesto sobre el Valor Añadido (IVA)      "vat_tax_regime_key": "01", // Operación de régimen general      "operation_type_key": "S1", // Operación Sujeta y No exenta - Sin inversión del sujeto pasivo      "tax_base": 100.00,      "tax_rate": 21.00,      "tax_quota": 21.00    }  ]}

Factura ordinaria en diferido

La misma factura de 121,00 €, enviada en modo diferido: no esperas la respuesta de la AEAT, te la comunicamos a tu servidor.

La petición va a /api/invoices/deferred en lugar de /api/invoices.
callback_url es la URL de tu servidor a la que se envía el resultado.
Es el modo pensado para emitir muchas facturas seguidas, como en un TPV.

Ver este ejemplo en la documentación

POST /api/invoices/deferred

{  "callback_url": "https://www.miservidor.com/kubifactu/callbacks/invoiceresult", // URL que apunta a tu servidor  "sif_id": "9db0bca1-187e-4cf4-b87c-96f2044008d7",  "invoice_type_key": "F1", // Factura (art. 6, 7.2 y 7.3 del RD 1619/2012)  "sender_data": {    "company_name": "Empresa emisora de ejemplo",    "tax_id_number": "J27290840"  },  "recipients": [    {      "company_name": "Empresa receptora de ejemplo",      "tax_id_number": "B99014037"    }  ],  "full_invoice_number": "2026-000001",  "fiscal_year": 2026,  "issue_date": "2026-01-01",  "operation_description": "Factura ordinaria por entrega de mercancías.",  "total_quota": 21.00,  "total_amount": 121.00,  "tax_breakdown": [    {      "tax_type_key": "01", // Impuesto sobre el Valor Añadido (IVA)      "vat_tax_regime_key": "01", // Operación de régimen general      "operation_type_key": "S1", // Operación Sujeta y No exenta - Sin inversión del sujeto pasivo      "tax_base": 100.00,      "tax_rate": 21.00,      "tax_quota": 21.00    }  ]}

Factura a una empresa de la UE

Factura ordinaria de 100,00 € a una empresa extranjera de la UE, exenta por el artículo 21.

Sin NIF español: el destinatario lleva other_country_code, other_tax_id_type_key y other_tax_id_number.
vat_tax_regime_key con el valor 02 (exportación) y exemption_cause_key con E2 (exenta por el artículo 21).
Al ser una base exenta no hay tipo ni cuota: total_quota es 0 y el desglose solo lleva tax_base.

Ver este ejemplo en la documentación

POST /api/invoices

{  "sif_id": "9db0bca1-187e-4cf4-b87c-96f2044008d7",  "invoice_type_key": "F1",  "sender_data": {    "company_name": "Empresa emisora de ejemplo",    "tax_id_number": "J27290840"  },  "recipients": [    {      "company_name": "Empresa extranjera de prueba",      "other_country_code": "DE",      "other_tax_id_type_key": "03",      "other_tax_id_number": "L74JF44L2"    }  ],  "full_invoice_number": "2026-000022",  "fiscal_year": 2026,  "issue_date": "2026-01-03",  "operation_description": "Factura ordinaria por entrega de mercancías.",  "total_quota": 0,  "total_amount": 100.00,  "tax_breakdown": [    {      "tax_type_key": "01", // Impuesto sobre el Valor Añadido (IVA)      "vat_tax_regime_key": "02", // Exportación      "exemption_cause_key": "E2", // Exenta por el artículo 21      "tax_base": 100.00    }  ]}

Factura a una empresa de fuera de la UE

Factura ordinaria de 100,00 € a una empresa de fuera de la UE, exenta por el artículo 25.

Es idéntica a la de la UE salvo el país (other_country_code) y la causa de exención.
exemption_cause_key con el valor E5: exenta por el artículo 25, en lugar de E2.

Ver este ejemplo en la documentación

POST /api/invoices

{  "sif_id": "9db0bca1-187e-4cf4-b87c-96f2044008d7",  "invoice_type_key": "F1",  "sender_data": {    "company_name": "Empresa emisora de ejemplo",    "tax_id_number": "J27290840"  },  "recipients": [    {      "company_name": "Empresa extranjera de prueba",      "other_country_code": "CL",      "other_tax_id_type_key": "03",      "other_tax_id_number": "76123456K"    }  ],  "full_invoice_number": "2026-000022",  "fiscal_year": 2026,  "issue_date": "2026-01-03",  "operation_description": "Factura ordinaria por entrega de mercancías.",  "total_quota": 0,  "total_amount": 100.00,  "tax_breakdown": [    {      "tax_type_key": "01", // Impuesto sobre el Valor Añadido (IVA)      "vat_tax_regime_key": "02", // Exportación      "exemption_cause_key": "E5", // Exenta por el artículo 25      "tax_base": 100.00    }  ]}

Facturas simplificadas

Las que se emiten sin identificar al destinatario, como los tickets de un TPV, y la factura completa que puede sustituirlas después.

Factura simplificada (F2)

Factura simplificada de 242,00 €: 200,00 € de base más IVA del 21 %, sin destinatario.

invoice_type_key con el valor F2: factura simplificada y facturas sin identificación del destinatario (artículo 6.1.d del RD 1619/2012).
No se incluye recipients: no hay destinatario que identificar.

Ver este ejemplo en la documentación

POST /api/invoices

{  "sif_id": "9db0bca1-187e-4cf4-b87c-96f2044008d7",  "invoice_type_key": "F2",  "sender_data": {    "company_name": "Empresa emisora de ejemplo",    "tax_id_number": "J27290840"  },  "full_invoice_number": "2026-000010",  "fiscal_year": 2026,  "issue_date": "2026-01-03",  "operation_description": "Factura simplificada por entrega de mercancías.",  "total_quota": 42.00,  "total_amount": 242.00,  "tax_breakdown": [    {      "tax_type_key": "01",      "vat_tax_regime_key": "01",      "operation_type_key": "S1",      "tax_base": 200.00,      "tax_rate": 21.00,      "tax_quota": 42.00    }  ]}

Factura en sustitución de una simplificada (F3)

La factura completa, con destinatario, que sustituye a la simplificada del ejemplo anterior.

invoice_type_key con el valor F3: factura emitida en sustitución de facturas simplificadas facturadas y declaradas.
Ahora sí se incluyen los destinatarios (recipients).
substituted_invoices indica la factura simplificada que se sustituye: su número, su fecha y su NIF.

Ver este ejemplo en la documentación

POST /api/invoices

{  "sif_id": "9db0bca1-187e-4cf4-b87c-96f2044008d7",  "invoice_type_key": "F3",  "sender_data": {    "company_name": "Empresa emisora de ejemplo",    "tax_id_number": "J27290840"  },  "recipients": [    {      "company_name": "Empresa receptora de ejemplo",      "tax_id_number": "B99014037"    }  ],  "full_invoice_number": "2026-000012",  "fiscal_year": 2026,  "issue_date": "2026-01-03",  "operation_description": "Factura ordinaria por entrega de mercancías.",  "substituted_invoices": [    {      "tax_id_number": "J27290840",      "full_invoice_number": "2026-000010",      "issue_date": "2026-01-03"    }  ],  "total_quota": 42.00,  "total_amount": 242.00,  "tax_breakdown": [    {      "tax_type_key": "01",      "vat_tax_regime_key": "01",      "operation_type_key": "S1",      "tax_base": 200.00,      "tax_rate": 21.00,      "tax_quota": 42.00    }  ]}

Facturas rectificativas

Cuando hay que corregir una factura que el reglamento obliga a rectificar con otra, por sustitución o por diferencias.

Rectificativa por sustitución (R1, S)

La factura 2026-000008 tenía una base de 200,00 € y 42,00 € de IVA. La nueva la rectifica y la sustituye con una base de 100,00 € y 21,00 € de IVA.

invoice_type_key con el valor R1: factura rectificativa por error fundado en derecho y artículo 80 Uno, Dos y Seis de la LIVA.
rectificative_type_key con el valor S: sustitución.
rectified_tax_base y rectified_tax_quota recogen la base y la cuota de la factura original.
rectified_invoices identifica la factura rectificada.

Ver este ejemplo en la documentación

POST /api/invoices

{  "sif_id": "9db0bca1-187e-4cf4-b87c-96f2044008d7",  "invoice_type_key": "R1",  "sender_data": {    "company_name": "Empresa emisora de ejemplo",    "tax_id_number": "J27290840"  },  "recipients": [    {      "company_name": "Empresa receptora de ejemplo",      "tax_id_number": "B99014037"    }  ],  "full_invoice_number": "2026-000014",  "fiscal_year": 2026,  "issue_date": "2026-01-03",  "operation_description": "Factura rectificativa.",  "rectificative_type_key": "S",  "rectified_tax_base": 200.00,  "rectified_tax_quota": 42.00,  "rectified_invoices": [    {      "tax_id_number": "J27290840",      "full_invoice_number": "2026-000008",      "issue_date": "2026-01-02"    }  ],  "total_quota": 21.00,  "total_amount": 121.00,  "tax_breakdown": [    {      "tax_type_key": "01",      "vat_tax_regime_key": "01",      "operation_type_key": "S1",      "tax_base": 100.00,      "tax_rate": 21.00,      "tax_quota": 21.00    }  ]}

Rectificativa por diferencias (R1, I)

La factura rectifica la 2026-000008 aplicando una diferencia de 100,00 € en la base imponible y de 21,00 € en el IVA.

rectificative_type_key con el valor I: diferencias.
No se incluyen rectified_tax_base ni rectified_tax_quota.
rectified_invoices sigue identificando la factura rectificada.

Ver este ejemplo en la documentación

POST /api/invoices

{  "sif_id": "9db0bca1-187e-4cf4-b87c-96f2044008d7",  "invoice_type_key": "R1",  "sender_data": {    "company_name": "Empresa emisora de ejemplo",    "tax_id_number": "J27290840"  },  "recipients": [    {      "company_name": "Empresa receptora de ejemplo",      "tax_id_number": "B99014037"    }  ],  "full_invoice_number": "2026-000015",  "fiscal_year": 2026,  "issue_date": "2026-01-03",  "operation_description": "Factura rectificativa.",  "rectificative_type_key": "I",  "rectified_invoices": [    {      "tax_id_number": "J27290840",      "full_invoice_number": "2026-000008",      "issue_date": "2026-01-02"    }  ],  "total_quota": 21.00,  "total_amount": 121.00,  "tax_breakdown": [    {      "tax_type_key": "01",      "vat_tax_regime_key": "01",      "operation_type_key": "S1",      "tax_base": 100.00,      "tax_rate": 21.00,      "tax_quota": 21.00    }  ]}

Subsanaciones

Para corregir un registro sin emitir una factura rectificativa, y para reenviar uno que la AEAT rechazó.

Subsanación de un registro

Se puede subsanar cualquier dato al que el reglamento de facturación no imponga la emisión de una factura rectificativa. El registro enviado pasa a ser el correcto.

correction_key con el valor S indica que el registro es una subsanación.

Ver este ejemplo en la documentación

POST /api/invoices

{  "sif_id": "9db0bca1-187e-4cf4-b87c-96f2044008d7",  "invoice_type_key": "F1",  "correction_key": "S",  "sender_data": {    "company_name": "Empresa emisora de ejemplo",    "tax_id_number": "J27290840"  },  "recipients": [    {      "company_name": "Empresa receptora de ejemplo",      "tax_id_number": "B99014037"    }  ],  "full_invoice_number": "2026-000018",  "fiscal_year": 2026,  "issue_date": "2026-01-03",  "operation_description": "Factura ordinaria por entrega de mercancías.",  "total_quota": 21.00,  "total_amount": 121.00,  "tax_breakdown": [    {      "tax_type_key": "01",      "vat_tax_regime_key": "01",      "operation_type_key": "S1",      "tax_base": 100.00,      "tax_rate": 21.00,      "tax_quota": 21.00    }  ]}

Subsanación con un registro previo rechazado

Para subsanar un registro que se rechazó antes, por rechazo de VeriFactu o por problemas técnicos en el envío.

correction_key con el valor S, como en cualquier subsanación.
previous_rejection_key con el valor X: indica que el registro anterior fue rechazado.
El resto de campos del registro pueden mantenerse idénticos al original.

Ver este ejemplo en la documentación

POST /api/invoices

{  "sif_id": "9db0bca1-187e-4cf4-b87c-96f2044008d7",  "invoice_type_key": "F1",  "correction_key": "S",  "previous_rejection_key": "X",  "sender_data": {    "company_name": "Empresa emisora de ejemplo",    "tax_id_number": "J27290840"  },  "recipients": [    {      "company_name": "Empresa receptora de ejemplo",      "tax_id_number": "B99014037"    }  ],  "full_invoice_number": "2026-000018",  "fiscal_year": 2026,  "issue_date": "2026-01-03",  "operation_description": "Factura ordinaria por entrega de mercancías.",  "total_quota": 21.00,  "total_amount": 121.00,  "tax_breakdown": [    {      "tax_type_key": "01",      "vat_tax_regime_key": "01",      "operation_type_key": "S1",      "tax_base": 100.00,      "tax_rate": 21.00,      "tax_quota": 21.00    }  ]}

Dudas habituales

Preguntas sobre los ejemplos

¿Qué tipo de factura envío para un ticket de TPV?

Las facturas simplificadas se envían con invoice_type_key F2 y sin destinatarios. Si después emites la factura completa a petición del cliente, usa F3 e indica la simplificada que sustituye en substituted_invoices.

¿Cómo envío una factura a un cliente extranjero?

En lugar del NIF, el destinatario lleva other_country_code, other_tax_id_type_key y other_tax_id_number. En los ejemplos de la documentación, la factura a una empresa de la UE usa la causa de exención E2 (artículo 21) y la de fuera de la UE usa E5 (artículo 25).

¿Qué diferencia hay entre una rectificativa por sustitución y por diferencias?

Por sustitución (rectificative_type_key S) la nueva factura sustituye a la rectificada, y se incluyen la base y la cuota de la original en rectified_tax_base y rectified_tax_quota. Por diferencias (I) esos dos campos no se incluyen. En ambos casos rectified_invoices identifica la factura rectificada.

¿Cuándo uso una subsanación y cuándo una rectificativa?

Se puede subsanar cualquier dato al que el reglamento de facturación no imponga la emisión de una factura rectificativa. Si el registro anterior fue rechazado, la subsanación añade previous_rejection_key con el valor X.

¿Puedo probar estos ejemplos?

Los valores son ficticios y los mismos de la documentación. Para enviarlos necesitas la API-KEY y el sif_id de una empresa dada de alta en el entorno de pruebas, que puedes crear al registrarte.

Empieza hoy

Envía tu primer registro a VeriFactu

Regístrate en el entorno de pruebas, sigue el inicio rápido y envía tu primer registro. Cuando todo encaje, das de alta producción.

Empezar en pruebas Alta en producción

¿Dudas antes de empezar? [email protected]