Prepare your software for the 2027 deadlines.   See the timeline →
apiverifactu.eu Try the API ↗
API VERIFACTU

API VeriFactu documentation

API VeriFactu v2 documentation: authentication, invoices, queries and webhooks. JSON examples from the published contract and integration guidance.

Your integration reference, at hand.

Examples based on the published API v2 documentation. Replace URL_API with your assigned environment. Use test data only. Confirm the exact token header with support; the public reference does not specify it.

The original technical descriptions and responses are preserved in Spanish.

API VERIFACTU · Videos

Learn to integrate the API with video tutorials

The two original tutorials: an introduction to the API and the steps to activate the service. Videos in Spanish.

Audio in Spanish

Introduction to API VeriFactu

Learn how to use the API and take the first steps to connect your software to VeriFactu.

· 22:11

Watch on YouTube
Audio in Spanish

Activating API VeriFactu

A practical tutorial on using API VeriFactu and the integration process.

· 6:54

Watch on YouTube

The YouTube player loads when you press play. This connects you to YouTube and its privacy policy applies.

Authentication

POST{{URL_API}}/vapi/v2/

Request an access_token with client credentials. Keep client_secret on your server and out of pages, repositories and logs.

Este endpoint permite obtener el token de acceso necesario para realizar operaciones. Debes enviar tus credenciales de cliente proporcionadas por el equipo de Verifactu.
  • {{CLIENT_ID}}: Dato correspondiente al id de cliente con el que identificará en el API de Verifactu.
  • {{CLIENT_SECRET}}: Dato correspondiente a la clave que en conjunto con el id de cliente permitirán identificarse correctamente en el API de Verifactu.

Request example

JSON · API v2
{
    "action": "auth_api",
    "new_token": "new_token",
    "grant_type": "client_credentials",
    "client_id" : "{{CLIENT_ID}}",
    "client_secret" : "{{CLIENT_SECRET}}"
}

Endpoint responses

HTTP 200
JSON · API v2
{
   "success": true,
   "access_token": "07362229F95F34ADEDE19DF7..."
}
Una respuesta exitosa devuelve en su contenido el valor true en la propiedad success y el respectivo access_token que será utilizado en posteriores consultas del API.
HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Credenciales incorrectas"
}
Una respuesta 401 Unauthorized devuelve un success en false con el correspondiente mensaje msg que indica la situacion en el API.

Submit invoice

POST{{URL_API}}/vapi/v2/

Submit an F1 record with recipient identity, tax breakdown and amounts. The outer id identifies your document; json_data.id contains the invoice number and date.

Solicitud que permite el envío de una factura completa. El campo type debe ser F1. En este tipo de documento el receptor o cliente final tiene que estar identificado en el bloque recipient expresamente para deducirse el IVA, es el formato más habitual para presentar documentos ante la AEAT. Para aclarar cada una de las propiedades diríjase a la sección Tablas de datos tomando como referencia el json en esta ventana en el panel de la derecha.

Request example

JSON · API v2
{
    "action": "send_invoice",
    "id": "1005",
    "json_data": {
        "recipient": {
            "irsId": "Q2826000H",
            "name": "Agencia Tributaria",
            "country": "ES"
        },
        "id": {
            "number": "INT2601-0283",
            "issuedTime": "2026-01-24"
        },
        "description": {
            "text": "Documento verificable",
            "operationDate": "2026-01-24"
        },
        "type": "F1",
        "vatLines": [
            {
                "operation_rating": "S1",
                "exempt_operation": "E0",
                "base": 250.00,
                "rate": 21,
                "amount": 52.50,
                "vatKey": "01"
            },
            {
                "operation_rating": "S1",
                "exempt_operation": "E0",
                "base": 100.00,
                "rate": 21,
                "amount": 21.00,
                "vatKey": "01"
            }
        ],
        "total": 423.50,
        "amount": 73.50
    }
}
success: true and status: pending mean the request is queued. Save queueId and query the status; they do not mean final AEAT acceptance.

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
        "qrcode": "data:image/png;base64,iVB...",
        "verifactuUrl": "https://prewww2.aeat.es...",
        "verifactuJson": "eyJ...",
        "status": "pending",
        "queueId": 1023340
    }
}

La API recibe correctamente la solicitud y la coloca en cola para su procesamiento. La respuesta incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: el código QR codificado en Base64 qrcode y la URL de verificación verifactuUrl asociada a dicho QR. Se facilita de igual forma el Json verifactuJson generado del registro como se presentará a hacienda codificado en Base64. También se devuelve el estado status del registro, que en este punto será siempre Pendiente pending, indicando que la solicitud ha sido encolada pero todavía no ha sido procesada.

Es importante tener en cuenta que este estado solo confirma que el registro de facturación será generado y enviado a la AEAT, pero no garantiza que dicho envío sea finalmente aceptado por esta. Aunque la API aplica múltiples validaciones para reducir al máximo esta posibilidad, la AEAT podría rechazarlo en algunos casos.

El estado del envío puede consultarse mediante el endpoint Consultar estado de documentos, utilizando el queueId devuelto en la respuesta.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Tipo de factura no válido: F6."
}

La API rechaza la solicitud debido a un error en el JSON enviado. En este caso, el registro de facturación no se crea y no se realiza ninguna comunicación con la AEAT. Se ejecutan diversas validaciones para reducir el riesgo de rechazos por parte de la AEAT. La respuesta incluirá un mensaje detallando la causa del error, que puede ir desde la ausencia de campos obligatorios hasta validaciones más avanzadas, como la verificación del formato del NIF del destinatario. Como antesala a presentar el JSON al API también puede como desarrollador colocar los controles más típicos en su sitema a fin de evitar la mayoría de errores, tiene a su disposición en la sección de Control de datos, un listado de los controles más recurrentes que se manejan.

HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Query statuses

POST{{URL_API}}/vapi/v2/

Query up to 20 queueId values per request. The documentation recommends waiting at least one minute, preferably 90 seconds after submission.

Con esta consulta puede obtener el estado de los documentos que se mantengan en estado pending, es decir, aquellos que han sido enviados recientemente al API para su presentación ante la AEAT, se recomienda consultar el estado del documento en un mínimo de 1 minuto o en un tiempo más recomendable 1 minuto y medio, en el arreglo de la consulta se deben indicar máximo 20 registros identificados por el dato queueId devuelto en la respuesta de los diferentes envíos de facturas.

Request example

JSON · API v2
{
    "action": "check_docs",
    "docs": {
        "1": {
            "queueId": "12"
        },
        "5": {
            "queueId": "13"
        }
    }
}

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
        "docs": {
            "1": {
                "success": true,
                "state": "sent",
                "message": "Documento enviado corr..."
            },
            "5": {
                "success": true,
                "state": "sent_warning",
                "message": "Estado: Parcialm...
                |Registro: AceptadoConErrores."
            }
	}
    }
}
Una respuesta exitosa devuelve en su contenido el valor true en la propiedad success y un arreglo denominado docs dentro de data que contiene la lista de documentos consultados con su respectiva información, la propiedad success indica si se ha tenido o no éxito en la consulta del registro, state indica el resultado de la operación de validación o envío a la AEAT de ese registro (puede consultar un listado completo de los estados aquí), y message brinda un detalle más completo del resultado, ya sea un éxito o error. Note que cada registro de consulta está numerado por lo que se puede denominar como un identificador, el cual debe ser único, para reconocer cada registro en la respuesta, por ejemplo en el json de la derecha se pueden observar 2 registros que son consultados, uno con el identificador 1 que consulta por el queueId 12 y otro con el identificador 5 que consulta por el queueId 13, en la respuesta se obtiene el mismo orden con los identificadores 1 y 5 con la respectiva respuesta.
HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Credenciales incorrectas"
}
Una respuesta 401 Unauthorized devuelve un success en false con el correspondiente mensaje msg que indica la situacion en el API.
HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Retrieve by reference

POST{{URL_API}}/vapi/v2/

Retrieve processed documents when their response was not saved. The spelling check_refferences is preserved exactly as in the API.

Con esta consulta puede recibir la información de una factura procesada anteriormente, con el fin de poder obtenerla si por algún motivo su proceso de integración mantuvo un error al capturar los datos y no los almacenó, su uso solo es para este tipo de casos.

Request example

JSON · API v2
{
    "action": "check_refferences",
    "docs": {
        "1": {
            "ref": "FINT-2601-0023"
        },
        "2": {
            "ref": "FINT-2601-0024"
        }
    }
}

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
        "qrcode": "data:image/png;base64,iVB...",
        "verifactuUrl": "https://prewww2.aeat.es...",
        "verifactuJson": "eyJ...",
        "status": "pending",
        "queueId": 1023340
    }
}

Una respuesta existosa al igual que cuando se envía una factura incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: el código QR codificado en Base64 qrcode y la URL de verificación verifactuUrl asociada a dicho QR. Se facilita de igual forma el Json verifactuJson generado del registro codificado en Base64. También se devuelve el estado status del registro.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Credenciales incorrectas"
}
Una respuesta 401 Unauthorized devuelve un success en false con el correspondiente mensaje msg que indica la situacion en el API.
HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Account summary

GET{{URL_API}}/vapi/v2/?action=account_summary

Check your account status, environment and usage. Review request_limit and requests_usage before planning bulk traffic.

Con el fin de conocer los datos pertenecientes a la cuenta Verifactu, se pone a disposiciónizadlas esta consulta para obtener los datos tributarios, estado de la cuenta, ambiente de envío, límite de consultas y consultas realizadas por periodo, de manera que se pueda analizar y gestionar el uso del API, entre otros datos de relevancia.

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
	"company_cif": "B0000000",
	"company_name": "My Company Name",
	"status": "activo",
	"environment": "pruebas",
	"type_company": "autonomo",
	"request_limit": "1000",
	"requests_usage": [
            {
                "period": "202603",
                "quantity": "105"
            },
            {
                "period": "202604",
                "quantity": "167"
            }
	]
    }
}

Este consulta devuelve información general sobre el estado de su cuenta y el uso del servicio.

En primer lugar, indica si la operación fue exitosa mediante success. Si es true, significa que la consulta se realizó correctamente.

Dentro de data encontrarás los detalles de la cuenta:

company_cif: el CIF de la empresa registrada.

company_name: el nombre de la empresa.

status: el estado actual de la cuenta (por ejemplo, activa).

environment: indica si estás trabajando en entorno de pruebas o producción.

type_company: el tipo de empresa, como autónomo o sociedad.

request_limit: el límite de consultas permitidas en el período actual.

Además, en requests_usage se muestra el consumo de consultas. Este es un listado donde cada elemento incluye:

period: el período en formato año y mes (por ejemplo, 202603).

quantity: la cantidad de consultas realizadas en ese período.

En resumen, este endpoint te permite conocer la información básica de tu cuenta y controlar cuántas solicitudes has consumido respecto a tu límite disponible..

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Token inválido..."
}
Una respuesta 401 Unauthorized devuelve un success en false con el correspondiente mensaje msg que indica la situacion en el API.
HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Responsible declaration

GET{{URL_API}}/vapi/v2/?action=declaracion_responsable

Retrieve the responsible declaration PDF encoded in Base64. Check that its scope and version match the system in use.

Para obtener la debida declaración responsable que involucra las funcionalidades y alcances el API puede utilizar esta consulta, la cual devuelve un archivo PDF correspondiente codificado en Base64

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
        "declaracion": "JVBERi0xLjc...lRU9GCg=="
    }
}

Una respuesta existosa incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: el PDF codificado en Base64 en la propiedad declaracion.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Token inválido..."
}
Una respuesta 401 Unauthorized devuelve un success en false con el correspondiente mensaje msg que indica la situacion en el API.
HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Webhook types

GET{{URL_API}}/vapi/v2/?action=webhooks_types

Query available types, register an HTTPS URL and save the returned identifier. Confirm webhook authentication with support and process duplicate events idempotently.

Consulta que devuelve un listado con los tipos de WebHooks que se pueden configurar según el funcionamiento y disponibilidad del API.

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": [
    	{
            "id": 1,
            "name": "Recibir respuesta de alta...",
            "description": "Activa este Webhook para..."
    	}
    ]
}

Una respuesta existosa incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: un conjunto de registros donde cada uno tiene las propiedades: id dato que identifica al WebHook y que al modificarlo debe ser enviado enviado en el endpoint de Actualizar WebHook o para borrarlo en el endpoint Borrar WebHook, la propiedad name que indica una breve descripción sobre la funcionalidad del WebHook y description que brinda un detalle más amplio del mismo.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Token inválido..."
}
Una respuesta 401 Unauthorized devuelve un success en false con el correspondiente mensaje msg que indica la situacion en el API.
HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Create webhook

POST{{URL_API}}/vapi/v2/

Query available types, register an HTTPS URL and save the returned identifier. Confirm webhook authentication with support and process duplicate events idempotently.

Consulta que permite dar de alta una url o enpoint personalizado para recibir la notificacion WebHook que se requiere, debe indicar el dato id obtenido en la consulta Tipos de webHooks en la propiedad type, adicional debe enviar el dato url y token para mantener un nivel de seguridad en su punto de recepción.

Request example

JSON · API v2
{
    "action": "setup_webhook",
    "type": 1,
    "url": "https://erp.dominio.dot/receipt",
    "token": "ABC12345678..."
}

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
        "id": "3"
    }
}

Una respuesta existosa incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: la propiedad id dato que identifica al registro único con el que fue registrado el WebHook, este dato debe ser almacenado para en un futuro aplicar actualización mediante PUT, o eliminar el registro de WebHook mediante DELETE.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Token inválido..."
}
Una respuesta 401 Unauthorized devuelve un success en false con el correspondiente mensaje msg que indica la situacion en el API.
HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Configured webhooks

GET{{URL_API}}/vapi/v2/?action=setup_webhooks

Query available types, register an HTTPS URL and save the returned identifier. Confirm webhook authentication with support and process duplicate events idempotently.

Consulta que devuelve un listado con la información de los WebHooks que ya se han configurado en el API.

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": [
        {
            "id": "3",
            "type": "1",
            "url": "https://erp.dominio.dot/receipt",
            "token": "ABC12345678..."
        }
    ]
}

Una respuesta existosa incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: un conjunto de registros donde cada uno tiene las propiedades: id dato que identifica al WebHook registrado en el API y que debe ser usado al modificarlo en el endpoint de Actualizar WebHook o para borrarlo en el endpoint Borrar WebHook, la propiedad type muestra el identificador de tipo del WebHook como los obtenidos en el endpoint Tipos de webHooks, url que sería la dirección donde se enviará la notificación y token que será el dato que su punto de enlace esperará para mantener un nivel de seguridad en su punto de recepción.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Token inválido..."
}
Una respuesta 401 Unauthorized devuelve un success en false con el correspondiente mensaje msg que indica la situacion en el API.
HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Update webhook

PUT{{URL_API}}/vapi/v2/

The published PUT example omits the webhook identifier. Confirm where to send it with support before updating.

Consulta que permite modificar un WebHook que ya se ha configurado en el API, de manera que se pueda actualizar el punto de enlace o la llave de acceso.

Request example

JSON · API v2
{
    "action": "setup_webhook",
    "url": "https://erp.dominio.dot/receipt2",
    "token": "ABC12345678..."
}

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
        "id": "3"
    }
}

Una respuesta existosa incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: un registro que tiene la propiedad: id dato que identifica al WebHook registrado en el API y que debe ser usado para borrarlo en el endpoint Borrar WebHook o actualizarlo en el presente endpoint.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Token inválido..."
}
Una respuesta 401 Unauthorized devuelve un success en false con el correspondiente mensaje msg que indica la situacion en el API.
HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Delete webhook

DELETE{{URL_API}}/vapi/v2/?action=webhook&id={webhook_id}

Query available types, register an HTTPS URL and save the returned identifier. Confirm webhook authentication with support and process duplicate events idempotently.

Solicitud que permite borrar un registro de WebHook que ya se ha configurado en el API. En el url de la solicitud se debe reemplazar el dato {webhook_id} por el id del WebHook que se obtuvo al registrar con el endpoint de Agregar WebHook o el obtenido de los registros en la consulta Webhooks configurados

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
        "id": "3"
    }
}

Una respuesta existosa incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: un registro que tiene la propiedad: id dato del registro que fue borrado en el API. Tenga en cuenta que al borrar el endpoint ya no recibirá notificaciones a menos que registre uno nuevo con Agregar WebHook.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Token inválido..."
}
Una respuesta 401 Unauthorized devuelve un success en false con el correspondiente mensaje msg que indica la situacion en el API.
HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Other invoice types

Examples from the published contract. Check each transaction’s tax classification with your adviser and validate data in the test environment.

VAT-exempt invoice

POST{{URL_API}}/vapi/v2/

Solicitud que permite el envío de una factura completa. El campo type debe ser F1. En este tipo de documento el receptor o cliente final tiene que estar identificado en el bloque recipient expresamente para deducirse el IVA, se reconoce como exenta debido a que se indica su tipo impositivo rate en 0 y adicional el dato exempt_operation se informa de acuerdo a los valores permitidos por la ley, para aclarar cada una de las propiedades diríjase a la sección Tablas de datos tomando como referencia el json en esta ventana en el panel de la derecha.

Request example

JSON · API v2
{
    "action": "send_invoice",
    "id": "1005",
    "json_data": {
        "recipient": {
            "irsId": "Q2826000H",
            "name": "Agencia Tributaria",
            "country": "ES"
        },
        "id": {
            "number": "FN2601-0282",
            "issuedTime": "2026-01-24"
        },
        "description": {
            "text": "Documento verificable",
            "operationDate": "2026-01-24"
        },
        "type": "F1",
        "vatLines": [
            {
                "operation_rating": "S1",
                "exempt_operation": "E1",
                "base": 250,
                "rate": 0,
                "amount": 0,
                "vatKey": "01"
            }
        ],
        "total": 250,
        "amount": 0
    }
}

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
        "qrcode": "data:image/png;base64,iVB...",
        "verifactuUrl": "https://prewww2.aeat.es...",
        "verifactuJson": "eyJ...",
        "status": "pending",
        "queueId": 1023340
    }
}

La API recibe correctamente la solicitud y la coloca en cola para su procesamiento. La respuesta incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: el código QR codificado en Base64 qrcode y la URL de verificación verifactuUrl asociada a dicho QR. Se facilita de igual forma el Json verifactuJson generado del registro como se presentará a hacienda codificado en Base64. También se devuelve el estado status del registro, que en este punto será siempre Pendiente pending, indicando que la solicitud ha sido encolada pero todavía no ha sido procesada.

Es importante tener en cuenta que este estado solo confirma que el registro de facturación será generado y enviado a la AEAT, pero no garantiza que dicho envío sea finalmente aceptado por esta. Aunque la API aplica múltiples validaciones para reducir al máximo esta posibilidad, la AEAT podría rechazarlo en algunos casos.

El estado del envío puede consultarse mediante el endpoint Consultar estado de documentos, utilizando el queueId devuelto en la respuesta.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Tipo de factura no válido: F6."
}

La API rechaza la solicitud debido a un error en el JSON enviado. En este caso, el registro de facturación no se crea y no se realiza ninguna comunicación con la AEAT. Se ejecutan diversas validaciones para reducir el riesgo de rechazos por parte de la AEAT. La respuesta incluirá un mensaje detallando la causa del error, que puede ir desde la ausencia de campos obligatorios hasta validaciones más avanzadas, como la verificación del formato del NIF del destinatario. Como antesala a presentar el JSON al API también puede como desarrollador colocar los controles más típicos en su sitema a fin de evitar la mayoría de errores, tiene a su disposición en la sección de Control de datos, un listado de los controles más recurrentes que se manejan.

HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Simplified invoice

POST{{URL_API}}/vapi/v2/

Solicitud que permite el envío de una factura simplificada. El campo "type" debe ser F2. Note que el bloque recipient no está definido, ya que el receptor o cliente final no tiene por qué estar identificado, a no ser que este lo solicite expresamente para deducirse el IVA, en tal caso debe crear una factura normal, para aclarar cada una de las propiedades diríjase a la sección Tablas de datos tomando como referencia el json en esta ventana en el panel de la derecha.

Request example

JSON · API v2
{
    "action": "send_invoice",
    "id": "1000",
    "json_data": {
        "id": {
            "number": "FACT-2601-0022",
            "issuedTime": "2026-01-20"
        },
        "description": {
            "text": "Documento verificable",
            "operationDate": "2026-01-20"
        },
        "type": "F2",
        "vatLines": [
            {
                "operation_rating": "S1",
                "exempt_operation": "E0",
                "vatKey": "01",
                "base": 0.75,
                "rate": 21,
                "amount": 0.16
            }
        ],
        "total": 0.91,
        "amount": 0.16
    }
}

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
        "qrcode": "data:image/png;base64,iVB...",
        "verifactuUrl": "https://prewww2.aeat.es...",
        "verifactuJson": "eyJ...",
        "status": "pending",
        "queueId": 1023340
    }
}

La API recibe correctamente la solicitud y la coloca en cola para su procesamiento. La respuesta incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: el código QR codificado en Base64 qrcode y la URL de verificación verifactuUrl asociada a dicho QR. Se facilita de igual forma el Json verifactuJson generado del registro como se presentará a hacienda codificado en Base64. También se devuelve el estado status del registro, que en este punto será siempre Pendiente pending, indicando que la solicitud ha sido encolada pero todavía no ha sido procesada.

Es importante tener en cuenta que este estado solo confirma que el registro de facturación será generado y enviado a la AEAT, pero no garantiza que dicho envío sea finalmente aceptado por esta. Aunque la API aplica múltiples validaciones para reducir al máximo esta posibilidad, la AEAT podría rechazarlo en algunos casos.

El estado del envío puede consultarse mediante el endpoint Consultar estado de documentos, utilizando el queueId devuelto en la respuesta.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Tipo de factura no válido: F6."
}

La API rechaza la solicitud debido a un error en el JSON enviado. En este caso, el registro de facturación no se crea y no se realiza ninguna comunicación con la AEAT. Se ejecutan diversas validaciones para reducir el riesgo de rechazos por parte de la AEAT. La respuesta incluirá un mensaje detallando la causa del error, que puede ir desde la ausencia de campos obligatorios hasta validaciones más avanzadas, como la verificación del formato del NIF del destinatario. Como antesala a presentar el JSON al API también puede como desarrollador colocar los controles más típicos en su sitema a fin de evitar la mayoría de errores, tiene a su disposición en la sección de Control de datos, un listado de los controles más recurrentes que se manejan.

HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Intra-EU invoice

POST{{URL_API}}/vapi/v2/

Solicitud que permite el envío de una factura completa a un cliente de un estado miembro de la Comunidad Europea. El campo type debe ser F1. En este tipo de documento el receptor o cliente final tiene que estar identificado en el bloque recipient, pero a diferencia de una factura normal el bloque contiene en lugar de irsId el dato id donde debe informarse el NIF Intracomunitario y adicional el dato idType que regularmente para estos casos se indica con el valor 04, para aclarar cada una de las propiedades diríjase a la sección Tablas de datos tomando como referencia el json en esta ventana en el panel de la derecha.

Request example

JSON · API v2
{
    "action": "send_invoice",
    "id": "1001",
    "json_data": {
        "recipient": {
            "id": "PT510014805",
            "idType": "04",
            "name": "Carten Marinu",
            "country": "PT"
        },
        "id": {
            "number": "FINT-2601-0023",
            "issuedTime": "2026-01-20"
        },
        "description": {
            "text": "Documento verificable",
            "operationDate": "2026-01-20"
        },
        "type": "F1",
        "vatLines": [
            {
                "operation_rating": "S1",
                "exempt_operation": "E0",
                "base": 250,
                "rate": 0,
                "amount": 0,
                "vatKey": "01"
            },
            {
                "operation_rating": "S1",
                "exempt_operation": "E0",
                "base": 250,
                "rate": 0,
                "amount": 0,
                "vatKey": "01"
            }
        ],
        "total": 500,
        "amount": 0
    }
}

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
        "qrcode": "data:image/png;base64,iVB...",
        "verifactuUrl": "https://prewww2.aeat.es...",
        "verifactuJson": "eyJ...",
        "status": "pending",
        "queueId": 1023340
    }
}

La API recibe correctamente la solicitud y la coloca en cola para su procesamiento. La respuesta incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: el código QR codificado en Base64 qrcode y la URL de verificación verifactuUrl asociada a dicho QR. Se facilita de igual forma el Json verifactuJson generado del registro como se presentará a hacienda codificado en Base64. También se devuelve el estado status del registro, que en este punto será siempre Pendiente pending, indicando que la solicitud ha sido encolada pero todavía no ha sido procesada.

Es importante tener en cuenta que este estado solo confirma que el registro de facturación será generado y enviado a la AEAT, pero no garantiza que dicho envío sea finalmente aceptado por esta. Aunque la API aplica múltiples validaciones para reducir al máximo esta posibilidad, la AEAT podría rechazarlo en algunos casos.

El estado del envío puede consultarse mediante el endpoint Consultar estado de documentos, utilizando el queueId devuelto en la respuesta.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Tipo de factura no válido: F6."
}

La API rechaza la solicitud debido a un error en el JSON enviado. En este caso, el registro de facturación no se crea y no se realiza ninguna comunicación con la AEAT. Se ejecutan diversas validaciones para reducir el riesgo de rechazos por parte de la AEAT. La respuesta incluirá un mensaje detallando la causa del error, que puede ir desde la ausencia de campos obligatorios hasta validaciones más avanzadas, como la verificación del formato del NIF del destinatario. Como antesala a presentar el JSON al API también puede como desarrollador colocar los controles más típicos en su sitema a fin de evitar la mayoría de errores, tiene a su disposición en la sección de Control de datos, un listado de los controles más recurrentes que se manejan.

HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Invoice to a foreign customer

POST{{URL_API}}/vapi/v2/

Solicitud que permite el envío de una factura completa a un cliente extranjero. El campo type debe ser F1. En este tipo de documento el receptor o cliente final tiene que estar identificado en el bloque recipient, pero a diferencia de una factura normal el bloque contiene en lugar de irsId el dato id donde debe informarse el ID del cliente y adicional el dato idType que regularmente para estos casos se indica con el valor 05, para aclarar cada una de las propiedades diríjase a la sección Tablas de datos tomando como referencia el json en esta ventana en el panel de la derecha.

Request example

JSON · API v2
{
    "action": "send_invoice",
    "id": "1004",
    "json_data": {
        "recipient": {
            "id": "88898888",
            "idType": "05",
            "name": "USA client",
            "country": "US"
        },
        "id": {
            "number": "IN2601-0283",
            "issuedTime": "2026-01-20"
        },
        "description": {
            "text": "HOY",
            "operationDate": "2026-01-20"
        },
        "type": "F1",
        "vatLines": [
            {
                "operation_rating": "S1",
                "exempt_operation": "E0",
                "base": 0.75,
                "rate": 7,
                "amount": 0.05,
                "vatKey": "01",
                "tax": "03"
            },
            {
                "operation_rating": "S1",
                "exempt_operation": "E0",
                "base": 250,
                "rate": 10,
                "amount": 25,
                "vatKey": "01"
            },
            {
                "operation_rating": "S1",
                "exempt_operation": "E0",
                "base": 0.75,
                "rate": 7,
                "amount": 0.05,
                "vatKey": "01",
                "tax": "03"
            }
        ],
        "total": 276.6,
        "amount": 25.1
    }
}

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
        "qrcode": "data:image/png;base64,iVB...",
        "verifactuUrl": "https://prewww2.aeat.es...",
        "verifactuJson": "eyJ...",
        "status": "pending",
        "queueId": 1023340
    }
}

La API recibe correctamente la solicitud y la coloca en cola para su procesamiento. La respuesta incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: el código QR codificado en Base64 qrcode y la URL de verificación verifactuUrl asociada a dicho QR. Se facilita de igual forma el Json verifactuJson generado del registro como se presentará a hacienda codificado en Base64. También se devuelve el estado status del registro, que en este punto será siempre Pendiente pending, indicando que la solicitud ha sido encolada pero todavía no ha sido procesada.

Es importante tener en cuenta que este estado solo confirma que el registro de facturación será generado y enviado a la AEAT, pero no garantiza que dicho envío sea finalmente aceptado por esta. Aunque la API aplica múltiples validaciones para reducir al máximo esta posibilidad, la AEAT podría rechazarlo en algunos casos.

El estado del envío puede consultarse mediante el endpoint Consultar estado de documentos, utilizando el queueId devuelto en la respuesta.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Tipo de factura no válido: F6."
}

La API rechaza la solicitud debido a un error en el JSON enviado. En este caso, el registro de facturación no se crea y no se realiza ninguna comunicación con la AEAT. Se ejecutan diversas validaciones para reducir el riesgo de rechazos por parte de la AEAT. La respuesta incluirá un mensaje detallando la causa del error, que puede ir desde la ausencia de campos obligatorios hasta validaciones más avanzadas, como la verificación del formato del NIF del destinatario. Como antesala a presentar el JSON al API también puede como desarrollador colocar los controles más típicos en su sitema a fin de evitar la mayoría de errores, tiene a su disposición en la sección de Control de datos, un listado de los controles más recurrentes que se manejan.

HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Equivalence surcharge

POST{{URL_API}}/vapi/v2/

El recargo de equivalencia es un régimen especial de IVA aplicable a comerciantes minoristas que venden productos sin modificar, mediante el cual pagan a sus proveedores un recargo adicional según el tipo de IVA. Dicho recargo debe figurar en la factura como justificante legal de la operación, por lo que el minorista debe comunicar al proveedor que está acogido a este régimen. En la API de Verifactu se indica estableciendo code class='inline-code'>vatKey=18 en la línea de la factura. El contenido de la consulta es similar a una factura normal. El campo type debe ser F1. En este tipo de documento el receptor o cliente final tiene que estar identificado en el bloque recipient expresamente para deducirse el IVA, es el formato más habitual para presentar documentos ante la AEAT. La particularidad de este documento es que incluye en las líneas de detalle vatLines 2 campos adicionales con los valores respectivos de recargo equivalencia: rate2 y amount2. Para aclarar cada una de las propiedades diríjase a la sección Tablas de datos tomando como referencia el json en esta ventana en el panel de la derecha.

Request example

JSON · API v2
{
    "recipient": {
        "irsId": "G36935931",
        "name": "El Montuno SL",
        "country": "ES"
    },
    "id": {
        "number": "IN2602-0290",
        "issuedTime": "2026-02-15"
    },
    "description": {
        "text": "Documento verificable",
        "operationDate": "2026-02-15"
    },
    "type": "F1",
    "vatLines": [
        {
            "operation_rating": "S1",
            "exempt_operation": "E0",
            "base": 250,
            "rate": 21,
            "amount": 52.5,
            "rate2": 5.2,
            "amount2": 13,
            "vatKey": "18"
        },
        {
            "operation_rating": "S1",
            "exempt_operation": "E0",
            "base": 100,
            "rate": 4,
            "amount": 4,
            "rate2": 0.5,
            "amount2": 0.5,
            "vatKey": "18"
        }
    ],
    "total": 420,
    "amount": 70
}

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
        "qrcode": "data:image/png;base64,iVB...",
        "verifactuUrl": "https://prewww2.aeat.es...",
        "verifactuJson": "eyJ...",
        "status": "pending",
        "queueId": 1023340
    }
}

La API recibe correctamente la solicitud y la coloca en cola para su procesamiento. La respuesta incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: el código QR codificado en Base64 qrcode y la URL de verificación verifactuUrl asociada a dicho QR. Se facilita de igual forma el Json verifactuJson generado del registro como se presentará a hacienda codificado en Base64. También se devuelve el estado status del registro, que en este punto será siempre Pendiente pending, indicando que la solicitud ha sido encolada pero todavía no ha sido procesada.

Es importante tener en cuenta que este estado solo confirma que el registro de facturación será generado y enviado a la AEAT, pero no garantiza que dicho envío sea finalmente aceptado por esta. Aunque la API aplica múltiples validaciones para reducir al máximo esta posibilidad, la AEAT podría rechazarlo en algunos casos.

El estado del envío puede consultarse mediante el endpoint Consultar estado de documentos, utilizando el queueId devuelto en la respuesta.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Tipo de factura no válido: F6."
}

La API rechaza la solicitud debido a un error en el JSON enviado. En este caso, el registro de facturación no se crea y no se realiza ninguna comunicación con la AEAT. Se ejecutan diversas validaciones para reducir el riesgo de rechazos por parte de la AEAT. La respuesta incluirá un mensaje detallando la causa del error, que puede ir desde la ausencia de campos obligatorios hasta validaciones más avanzadas, como la verificación del formato del NIF del destinatario. Como antesala a presentar el JSON al API también puede como desarrollador colocar los controles más típicos en su sitema a fin de evitar la mayoría de errores, tiene a su disposición en la sección de Control de datos, un listado de los controles más recurrentes que se manejan.

HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Rectifying invoice

POST{{URL_API}}/vapi/v2/

Consulta que permite presentar una factura rectificativa que se emite para corregir errores o modificar datos de una factura previamente emitida, como importes, impuestos, fechas o datos del destinatario, cumpliendo con la normativa vigente. En su mayoría la factura rectificativa responde a la misma estructura de la factura normal de la cual es origen, el campo type debe corresponder con uno de tipos indicados admitidos: R1, R2, R3 y R4, los cuales se detallan en la tabla de datos de Facturación type, adicional los detalles propios de la factura rectificativa (tipo, facturas que rectifica,etc.) se incluyen en el elemento creditNote. Hay que identificar las facturas rectificadas por su referencia number completa. Para aclarar cada una de las propiedades diríjase a la sección Tablas de datos tomando como referencia el json en esta ventana en el panel de la derecha.

Request example

JSON · API v2
{
    "action": "send_invoice",
    "id": "1001",
    "json_data": {
        "recipient": {
            "irsId": "Q2826000H",
            "name": "Agencia Tributaria",
            "country": "ES"
        },
        "id": {
            "number": "IC2601-0021",
            "issuedTime": "2026-01-24"
        },
        "description": {
            "text": "Documento verificable",
            "operationDate": "2026-01-24"
        },
        "type": "R1",
        "creditNote": {
            "style": "I",
            "ids": [
                {
                    "number": "FN2601-0282",
                    "issuedTime": "2026-01-24"
                }
            ]
        },
        "vatLines": [
            {
                "operation_rating": "S1",
                "exempt_operation": "E1",
                "base": -250,
                "rate": 0,
                "amount": 0,
                "vatKey": "01"
            }
        ],
        "total": -250,
        "amount": 0
    }
}

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
        "qrcode": "data:image/png;base64,iVB...",
        "verifactuUrl": "https://prewww2.aeat.es...",
        "verifactuJson": "eyJ...",
        "status": "pending",
        "queueId": 1023340
    }
}

La API recibe correctamente la solicitud y la coloca en cola para su procesamiento. La respuesta incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: el código QR codificado en Base64 qrcode y la URL de verificación verifactuUrl asociada a dicho QR. Se facilita de igual forma el Json verifactuJson generado del registro como se presentará a hacienda codificado en Base64. También se devuelve el estado status del registro, que en este punto será siempre Pendiente pending, indicando que la solicitud ha sido encolada pero todavía no ha sido procesada.

Es importante tener en cuenta que este estado solo confirma que el registro de facturación será generado y enviado a la AEAT, pero no garantiza que dicho envío sea finalmente aceptado por esta. Aunque la API aplica múltiples validaciones para reducir al máximo esta posibilidad, la AEAT podría rechazarlo en algunos casos.

El estado del envío puede consultarse mediante el endpoint Consultar estado de documentos, utilizando el queueId devuelto en la respuesta.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Tipo de factura no válido: F6."
}

La API rechaza la solicitud debido a un error en el JSON enviado. En este caso, el registro de facturación no se crea y no se realiza ninguna comunicación con la AEAT. Se ejecutan diversas validaciones para reducir el riesgo de rechazos por parte de la AEAT. La respuesta incluirá un mensaje detallando la causa del error, que puede ir desde la ausencia de campos obligatorios hasta validaciones más avanzadas, como la verificación del formato del NIF del destinatario. Como antesala a presentar el JSON al API también puede como desarrollador colocar los controles más típicos en su sitema a fin de evitar la mayoría de errores, tiene a su disposición en la sección de Control de datos, un listado de los controles más recurrentes que se manejan.

HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Simplified rectifying invoice

POST{{URL_API}}/vapi/v2/

Consulta que permite presentar una factura rectificativa basada en una factura simplificada que se emite para corregir errores o modificar datos de una factura previamente emitida, como importes, impuestos o fechas, cumpliendo con la normativa vigente. En su mayoría la factura rectificativa simplificada responde a la misma estructura de la factura simplificada de la cual es origen, el campo type debe corresponder con el tipo indicado admitido: R5, el cual se detalla en la tabla de datos de Facturación type, adicional los detalles propios de la factura rectificativa simplificada (tipo, facturas que rectifica,etc.) se incluyen en el elemento creditNote. Hay que identificar las facturas rectificadas por su referencia number completa, tenga en cuenta que dichas facturas tambien deben ser simplificadas. Para aclarar cada una de las propiedades diríjase a la sección Tablas de datos tomando como referencia el json en esta ventana en el panel de la derecha.

Request example

JSON · API v2
{
    "action": "send_invoice",
    "id": "1001",
    "json_data": {
        "id": {
            "number": "IC2601-0022",
            "issuedTime": "2026-01-24"
        },
        "description": {
            "text": "Documento verificable",
            "operationDate": "2026-01-24"
        },
        "type": "R5",
        "creditNote": {
            "style": "I",
            "ids": [
                {
                    "number": "TC1-2601-0022",
                    "issuedTime": "2026-01-20"
                }
            ]
        },
        "vatLines": [
            {
                "operation_rating": "S1",
                "exempt_operation": "E0",
                "base": -0.75,
                "rate": 21,
                "amount": -0.16,
                "vatKey": "01"
            }
        ],
        "total": -0.91,
        "amount": -0.16
    }
}

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
        "qrcode": "data:image/png;base64,iVB...",
        "verifactuUrl": "https://prewww2.aeat.es...",
        "verifactuJson": "eyJ...",
        "status": "pending",
        "queueId": 1023340
    }
}

La API recibe correctamente la solicitud y la coloca en cola para su procesamiento. La respuesta incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: el código QR codificado en Base64 qrcode y la URL de verificación verifactuUrl asociada a dicho QR. Se facilita de igual forma el Json verifactuJson generado del registro como se presentará a hacienda codificado en Base64. También se devuelve el estado status del registro, que en este punto será siempre Pendiente pending, indicando que la solicitud ha sido encolada pero todavía no ha sido procesada.

Es importante tener en cuenta que este estado solo confirma que el registro de facturación será generado y enviado a la AEAT, pero no garantiza que dicho envío sea finalmente aceptado por esta. Aunque la API aplica múltiples validaciones para reducir al máximo esta posibilidad, la AEAT podría rechazarlo en algunos casos.

El estado del envío puede consultarse mediante el endpoint Consultar estado de documentos, utilizando el queueId devuelto en la respuesta.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Tipo de factura no válido: F6."
}

La API rechaza la solicitud debido a un error en el JSON enviado. En este caso, el registro de facturación no se crea y no se realiza ninguna comunicación con la AEAT. Se ejecutan diversas validaciones para reducir el riesgo de rechazos por parte de la AEAT. La respuesta incluirá un mensaje detallando la causa del error, que puede ir desde la ausencia de campos obligatorios hasta validaciones más avanzadas, como la verificación del formato del NIF del destinatario. Como antesala a presentar el JSON al API también puede como desarrollador colocar los controles más típicos en su sitema a fin de evitar la mayoría de errores, tiene a su disposición en la sección de Control de datos, un listado de los controles más recurrentes que se manejan.

HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Invoice record correction

POST{{URL_API}}/vapi/v2/

Consulta que permite realizar el proceso de corregir errores técnicos o de datos (como NIF, dirección o formato) en una factura ya enviada a la Agencia Tributaria que ha sido aceptada con errores, en el API se puede identificar una factura que califica para subsanación ya que en su estado obtenido de la consulta Consultar estado de documentos devuelve el estado sent_warning, solo en ese estado exclusivamente. La estructura del json es el mismo que el de una factura normal, ya sea estándar, intracomunitaria, etc., lo que la define como una subsanación es el dato isFix con el valor 1 como indicativo.

Request example

JSON · API v2
{
    "action": "send_invoice",
    "id": "1001",
    "json_data": {
        "recipient": {
            "irsId": "Q2826000H",
            "name": "Agencia Tributaria",
            "country": "ES"
        },
        "id": {
            "number": "IN2601-0286",
            "issuedTime": "2026-01-24"
        },
        "description": {
            "text": "Documento verificable subsanado",
            "operationDate": "2026-01-24"
        },
        "type": "F1",
        "vatLines": [
            {
                "operation_rating": "S1",
                "exempt_operation": "E1",
                "base": 250,
                "rate": 0,
                "amount": 0,
                "vatKey": "01"
            }
        ],
        "total": 250,
        "isFix": "1",
        "amount": 0
    }
}

Endpoint responses

HTTP 200
JSON · API v2
{
    "success": true,
    "data": {
        "qrcode": "data:image/png;base64,iVB...",
        "verifactuUrl": "https://prewww2.aeat.es...",
        "verifactuJson": "eyJ...",
        "status": "pending",
        "queueId": 1023340
    }
}

La API recibe correctamente la solicitud y la coloca en cola para su procesamiento. La respuesta incluye el valor true en la propiedad success, y dentro en un arreglo nombrado data: el código QR codificado en Base64 qrcode y la URL de verificación verifactuUrl asociada a dicho QR. Se facilita de igual forma el Json verifactuJson generado del registro como se presentará a hacienda codificado en Base64. También se devuelve el estado status del registro, que en este punto será siempre Pendiente pending, indicando que la solicitud ha sido encolada pero todavía no ha sido procesada.

Es importante tener en cuenta que este estado solo confirma que el registro de facturación será generado y enviado a la AEAT, pero no garantiza que dicho envío sea finalmente aceptado por esta. Aunque la API aplica múltiples validaciones para reducir al máximo esta posibilidad, la AEAT podría rechazarlo en algunos casos.

El estado del envío puede consultarse mediante el endpoint Consultar estado de documentos, utilizando el queueId devuelto en la respuesta.

HTTP 401
JSON · API v2
{
    "success": false,
    "msg": "Tipo de factura no válido: F6."
}

La API rechaza la solicitud debido a un error en el JSON enviado. En este caso, el registro de facturación no se crea y no se realiza ninguna comunicación con la AEAT. Se ejecutan diversas validaciones para reducir el riesgo de rechazos por parte de la AEAT. La respuesta incluirá un mensaje detallando la causa del error, que puede ir desde la ausencia de campos obligatorios hasta validaciones más avanzadas, como la verificación del formato del NIF del destinatario. Como antesala a presentar el JSON al API también puede como desarrollador colocar los controles más típicos en su sitema a fin de evitar la mayoría de errores, tiene a su disposición en la sección de Control de datos, un listado de los controles más recurrentes que se manejan.

HTTP 500
JSON · API v2
Internal server error

Error interno del servidor. Se trata de un fallo genérico que no debería producirse. Si ocurre, el registro de facturación no se genera y, en consecuencia, no se envía ninguna información a la AEAT. En este caso, el cliente deberá intentar realizar la solicitud nuevamente más adelante.

Data tables

Types, formats and values from the original documentation to prepare your requests.

* Required in the context stated in the description

Invoice structure
FieldType Length / formatDescription
action *stringmax 50Acción que indica la operación a ejecutar en el API.
id *integermax 22Identificador interno único de la factura en el sistema. Que además del dato de referencia de la factura funciona como dato para mantener un trazabilidad llave entre el sistema cliente y el API
json_data *objectBloque principal con los datos de la factura.
json_data.recipientobjectDatos del receptor de la factura.
json_data.recipient.irsId *string9NIF del receptor. Debe responder al formato FormatoNIF válido. (No presentar simultáneo con el dato "id", de este bloque)
json_data.recipient.id *string20Número de identificación del tercero en el país de residencia. (No presentar simultáneo con el dato "irsId", de este bloque)
json_data.recipient.idType *string2Tipo de identificación del tercero en el país de residencia. Ver tabla idType. (Presentar solo obligatoriamente con el dato "id", de este bloque)
json_data.recipient.name *stringmax 120Nombre o razón social del receptor.
json_data.recipient.country *string2Código ISO del país del receptor. Ver tabla country
json_data.id *objectBloque de identificación de la factura.
json_data.id.number *stringmax 60(Campo clave). Número de factura que debe ser único e irrepetible para el sistema informático
json_data.id.issuedTime *dateYYYY-MM-DDFecha de emisión de la factura en formato (YYYY-MM-DD)
json_data.description *objectDescripción y fecha de la operación.
json_data.description.text *stringmax 500Descripción del documento.
json_data.description.operationDate *dateYYYY-MM-DDFecha en la que se realizó la operación en formato (YYYY-MM-DD).
json_data.type *string2Tipo de factura según Verifactu. Ver tabla type
json_data.creditNote *objectBloque de identificación de la(s) factura(s) rectificada(s).
json_data.creditNote.style *string1Campo que indica el motivo de la rectificación. Ver tabla style
json_data.creditNote.idsarrayArreglo con las facturas rectificadas. Solo obligatorio si el campo "style" se indica como el tipo sustitución ("S")
json_data.creditNote.ids.number *stringmax 60(Campo clave). Número de factura a rectificar que debe ser único e irrepetible para el sistema informático
json_data.creditNote.ids.issuedTime *dateYYYY-MM-DDFecha de emisión de la factura a rectificar en formato (YYYY-MM-DD)
json_data.vatLines *arrayDeglose de líneas de IVA. Importante: Límite de hasta 12 registros, procurar agrupar por clave regimen, tipos impositivos, calificaciones de operación y exenciones, API intará agruparlo, pero si rebasa la cantidad se notificará el error.
json_data.vatLines.operation_rating *string2Calificación de la operación. Ver tabla operation_rating
json_data.vatLines.exempt_operation *string2Clave de exención de IVA. Ver tabla exempt_operation
json_data.vatLines.base *decimal12,2Base imponible.
json_data.vatLines.rate *decimal3,2Tipo impositivo aplicado. Ver tabla rate
json_data.vatLines.amount *decimal12,2Importe del IVA.
json_data.vatLines.vatKey *string2Clave régimen de IVA según AEAT. Ver tabla vatKey
json_data.total *decimal12,2Importe total de la factura.
json_data.isFixstring1Indica que la factura es una subsanación. (Solo necesario para subsanación)
json_data.amount *decimal12,2Total de IVA de la factura.

Identificación

idType

Tipo de identificación fiscal
ValueDescription
02NIF-IVA
03Pasaporte
04Documento oficial de identificación expedido por el país o territorio de residencia
05Certificado de residencia
06Otro documento probatorio
07No Censado

country

Código de país (ISO 3166-1 alpha-2), puede ver las lista completa en listados como el de Wikipedia los más utilizados son:
ValueDescription
ESEspaña
PTPortugal
FRFrancia
DEAlemania
USEstados Unidos
...Ver estándar ISO 3166-1

Facturación

type

Tipo de factura
ValueDescription
F1Factura (Art. 6, 7.2 y 7.3 RD 1619/2012)
F2actura Simplificada y Facturas sin identificación del destinatario art. 6.1.d) RD 1619/2012
R1Factura rectificativa (Art 80.1 y 80.2)
R2Factura rectificativa (Art. 80.3)
R3Factura rectificativa (Art. 80.4)
R4Factura rectificativa (Resto)
R5Factura rectificativa en facturas simplificadas

style

Tipo de rectificativa
ValueDescription
SPor sustitución
IPor diferencias

Impuestos (IVA)

operation_rating

Calificación de la operación
ValueDescription
S1Sujeta y no exenta - Sin inversión del sujeto pasivo
S2Sujeta y no exenta - Con inversión del sujeto pasivo
N1No sujeta Art. 7, 14, otros
N2No sujeta por reglas de localización

exempt_operation

Causa de exención
ValueDescription
E0No exenta
E1Exenta por Art. 20
E2Exenta por Art. 21
E3Exenta por Art. 22
E4Exenta por Art. 24
E5Exenta por Art. 25
E6Exenta otros

vatKey

Clave de régimen
ValueDescription
01Operación de régimen general
02Exportación
03Régimen especial bienes usados
04Régimen especial oro de inversión
05Régimen especial agencias de viajes
07Régimen especial criterio de caja
08Operaciones sujetas al IPSI / IGIC
11Arrendamiento de local de negocio
17Operación acogida a regímenes OSS e IOSS
18Recargo de equivalencia
20Régimen simplificado

rate

Tipo de impuesto
ValueDescription
01IVA
02IPSI (Ceuta y Melilla)
03IGIC (Canarias)
05Otros

check_docs

Estados de documentos
ValueDescription
pendingDocumento recibido y aún pendiente de envío a la AEAT.
sentDocumento enviado correctamente.
sent_warningDocumento enviado con advertencias (parcialmente correcto).
errorError en el documento o rechazo en el procesamiento. También puede ser por no encontrar la cola de envío asociada (queueId inexistente).

Data validation

Checks and validations from the original reference to review data before sending it to the API.

Bloque / Campo Cuándo aplica Regla Explicación funcional
recipient Condicional Obligatorio si type es:
  • F1 (Factura completa)
  • R1–R4 (Rectificativas no simplificadas)
 Las facturas no simplificadas deben identificar al receptor
id Obligatorio Debe existir el bloque identificador Permite identificar de forma única el documento
id.issuedTime Obligatorio
  • Formato YYYY-MM-DD
  • No puede ser futura
 Fecha oficial de expedición de la factura
description.operationDate Fiscal
  • Solo informar si es distinta issuedTime
  • No anterior a hoy − 20 años
  • No posterior al 31/12 del año siguiente
 Rango temporal permitido por Verifactu / AEAT
issuedTime / operationDate Lógica issuedTime solo puede ser anterior a operationDate si vatKey es 14 o 15 Excepción válida solo para certificaciones de obra o tracto sucesivo
creditNote.style Condicional Obligatorio si la factura es rectificativa
Valores: S o I 		Indica si la rectificación es por sustitución o diferencias
creditNote.creditBase, creditNote.creditVat Condicional Obligatorios solo si style = S Importes corregidos en rectificativas por sustitución
recipient.irsId Fiscal NIF válido si país es ES y no es factura simplificada Validación fiscal del destinatario
recipient.irsId o recipient.id Fiscal El NIF del destinatario debe ser diferente al del emisor. Validación fiscal del destinatario
recipient.idType Lógica Si es Pasaporte o No censado, el país debe ser ES Restricción oficial Verifactu
id.number Obligatorio Solo caracteres ASCII (32–126) Compatibilidad técnica con AEAT
Factura simplificada Fiscal Total base + impuesto ≤ 3.000 Límite legal para este tipo de factura
vatLines[].operation_rating Fiscal Si es S2, tipo de factura solo puede ser F1, F3 o R1–R4 Inversión del sujeto pasivo solo admitida en ciertos tipos
vatLines[].operation_rating = S2 Lógica Tipo impositivo y cuota deben ser 0 La inversión del sujeto pasivo no genera impuesto
vatLines[].vatKey = 08 Fiscal Calificación operación debe ser N2 Operaciones IGIC/IPSI por reglas de localización
vatLines[].vatKey = 02 Fiscal La operación debe ser exenta Exportaciones siempre exentas
vatLines[].amount Lógica Solo puede ser distinto de 0 si la operación es S1 El impuesto solo se liquida en operaciones sujetas no exentas
Recargo de equivalencia Fiscal Solo permitido para IVA y con porcentajes oficiales Validación específica del régimen de recargo
invoice_json Siempre Debe existir y ser un objeto válido El payload recibido debe tener una estructura JSON válida.
type Siempre Debe ser uno de los tipos oficiales (F1, F2, F3, R1–R5) Define el tipo legal de factura aceptado por el sistema Verifactu.
recipient Facturas no simplificadas Bloque obligatorio Identificación del destinatario cuando la normativa lo exige.
recipient.country Si se informa identificación especial Debe ser ES en ciertos tipos de identificación Algunos tipos de identificación solo son válidos para residentes en España.
recipient.irsId / recipient.id Facturas con destinatario identificado Formato NIF válido si el país es España Evita rechazos por identificación fiscal incorrecta.
recipient.idType Si se informa Si es 07 o 03, el país debe ser España Tipos de identificación “No censado” o “Pasaporte” solo aplican a España.
id Siempre Bloque obligatorio Contiene los datos identificativos de la factura.
id.number Siempre Solo caracteres ASCII (32–126) Garantiza compatibilidad con sistemas de verificación y firma.
id.issuedTime Siempre Formato YYYY-MM-DD
No puede ser superior a la fecha actual 		Fecha oficial de expedición de la factura.
description.operationDate Si se informa No menor a hoy - 20 años
No mayor al 31/12 del año siguiente 		Fecha real en la que se realizó la operación económica.
issuedTime < operationDate Si ocurre Solo permitido con ClaveRegimen 14 o 15 Solo en certificaciones de obra o tracto sucesivo puede emitirse la factura antes de la fecha de operación.
creditNote Facturas rectificativas Bloque obligatorio Identifica que la factura corrige una anterior.
creditNote.style Facturas rectificativas Debe ser S (sustitución) o I (diferencias) Indica el tipo de rectificación aplicada.
creditNote.creditBase
creditNote.creditVat		 Rectificativa por sustitución Obligatorios Importes rectificados exigidos por la AEAT.
vatLines Siempre Debe existir al menos una línea Una factura sin desglose no es válida.
vatLines[].operation_rating En cada línea Debe ser un valor válido (S1, S2, N1, N2) Clasifica la operación según su tratamiento fiscal.
operation_rating = S2 Cuando aplica inversión del sujeto pasivo Tipo impositivo = 0
Importe impuesto = 0 		En inversión del sujeto pasivo no se repercute IVA.
vatKey = 08 Operaciones IGIC / IPSI operation_rating debe ser N2 Operaciones no sujetas por reglas de localización.
vatKey = 02 IPSI Solo permitido con operaciones exentas El IPSI solo admite operaciones exentas.
vatKey = 03 IGIC operation_rating debe ser S1 Las operaciones IGIC deben ser sujetas y no exentas.
vatKey = 07 Régimen criterio de caja No compatible con ciertas exenciones o calificaciones Limita combinaciones inválidas según normativa.
amount En líneas Solo distinto de 0 si
operation_rating = S1 		Solo las operaciones sujetas y no exentas generan impuesto.
rate2 / amount2 Recargo de equivalencia Solo permitido con IVA El recargo de equivalencia solo aplica al impuesto IVA.
Factura simplificada type = F2 Total ≤ 3.000 Límite legal para facturas simplificadas.
Total factura Siempre Debe coincidir con la suma de bases e impuestos Evita inconsistencias contables y rechazos del sistema.