Préparez votre logiciel aux échéances de 2027.   Consulter le calendrier →
apiverifactu.eu Essayez l’API ↗
API VERIFACTU

Documentation de l’API VeriFactu

Documentation API VeriFactu v2 : authentification, factures, consultations et webhooks. Exemples JSON et guide d’intégration.

Votre référence d’intégration, à portée de main.

Exemples issus de la documentation publique de l’API v2. Remplacez URL_API par votre environnement. Utilisez des données de test. Confirmez l’en-tête exact du jeton avec l’assistance ; il n’est pas précisé publiquement.

Les descriptions techniques et les réponses originales sont conservées en espagnol.

API VERIFACTU · Vidéos

Apprenez à intégrer l’API en vidéo

Les deux tutoriels originaux : une présentation de l’API et les étapes d’activation du service. Vidéos en espagnol.

Audio en espagnol

Présentation de l’API VeriFactu

Découvrez l’utilisation de l’API et les premières étapes pour connecter votre logiciel à VeriFactu.

· 22:11

Voir sur YouTube
Audio en espagnol

Activation de l’API VeriFactu

Tutoriel pratique sur l’utilisation de l’API VeriFactu et son intégration.

· 6:54

Voir sur YouTube

Le lecteur YouTube se charge lorsque vous lancez la lecture. Vous vous connectez alors à YouTube et sa politique de confidentialité s’applique.

Authentification

POST{{URL_API}}/vapi/v2/

Demandez un access_token avec vos identifiants. Conservez client_secret sur le serveur, hors des pages, dépôts et journaux.

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.

Exemple de requête

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

Réponses de l’endpoint

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.

Envoyer une facture

POST{{URL_API}}/vapi/v2/

Envoyez un enregistrement F1 avec le destinataire, les taxes et les montants. L’id externe identifie le document ; json_data.id contient le numéro et la 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.

Exemple de requête

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 et status: pending indiquent une mise en file d’attente. Conservez queueId et consultez le statut ; ce n’est pas une acceptation définitive de l’AEAT.

Réponses de l’endpoint

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.

Consulter les statuts

POST{{URL_API}}/vapi/v2/

Consultez jusqu’à 20 queueId par requête. La documentation conseille d’attendre au moins une minute, de préférence 90 secondes après l’envoi.

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.

Exemple de requête

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

Réponses de l’endpoint

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.

Retrouver par référence

POST{{URL_API}}/vapi/v2/

Retrouvez les documents traités dont la réponse n’a pas été conservée. L’orthographe check_refferences est celle de l’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.

Exemple de requête

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

Réponses de l’endpoint

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.

Résumé du compte

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

Consultez le statut, l’environnement et la consommation du compte. Vérifiez request_limit et requests_usage avant des envois massifs.

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.

Réponses de l’endpoint

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.

Déclaration responsable

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

Récupérez le PDF de la déclaration responsable en Base64. Vérifiez que son périmètre et sa version correspondent au système utilisé.

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

Réponses de l’endpoint

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.

Types de webhook

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

Consultez les types, enregistrez une URL HTTPS et conservez l’identifiant. Confirmez l’authentification des notifications et traitez les doublons de manière idempotente.

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

Réponses de l’endpoint

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.

Créer un webhook

POST{{URL_API}}/vapi/v2/

Consultez les types, enregistrez une URL HTTPS et conservez l’identifiant. Confirmez l’authentification des notifications et traitez les doublons de manière idempotente.

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.

Exemple de requête

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

Réponses de l’endpoint

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.

Webhooks configurés

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

Consultez les types, enregistrez une URL HTTPS et conservez l’identifiant. Confirmez l’authentification des notifications et traitez les doublons de manière idempotente.

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

Réponses de l’endpoint

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.

Mettre à jour un webhook

PUT{{URL_API}}/vapi/v2/

L’exemple public PUT ne contient pas l’identifiant du webhook. Confirmez son emplacement avec l’assistance avant une mise à jour.

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.

Exemple de requête

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

Réponses de l’endpoint

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.

Supprimer un webhook

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

Consultez les types, enregistrez une URL HTTPS et conservez l’identifiant. Confirmez l’authentification des notifications et traitez les doublons de manière idempotente.

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

Réponses de l’endpoint

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.

Autres types de facture

Exemples du contrat publié. Vérifiez la qualification fiscale avec votre conseil et validez les données dans l’environnement de test.

Facture exonérée

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.

Exemple de requête

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

Réponses de l’endpoint

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.

Facture simplifiée

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.

Exemple de requête

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

Réponses de l’endpoint

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.

Facture intracommunautaire

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.

Exemple de requête

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

Réponses de l’endpoint

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.

Facture à un client étranger

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.

Exemple de requête

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

Réponses de l’endpoint

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.

Surtaxe d’équivalence

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.

Exemple de requête

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
}

Réponses de l’endpoint

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.

Facture rectificative

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.

Exemple de requête

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

Réponses de l’endpoint

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.

Facture rectificative simplifiée

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.

Exemple de requête

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

Réponses de l’endpoint

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.

Correction d’un enregistrement

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.

Exemple de requête

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

Réponses de l’endpoint

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.

Tables de données

Types, formats et valeurs de la documentation originale pour préparer vos requêtes.

* Obligatoire dans le contexte indiqué dans la description

Structure de la facture
ChampType Longueur / 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
ValeurDescription
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:
ValeurDescription
ESEspaña
PTPortugal
FRFrancia
DEAlemania
USEstados Unidos
...Ver estándar ISO 3166-1

Facturación

type

Tipo de factura
ValeurDescription
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
ValeurDescription
SPor sustitución
IPor diferencias

Impuestos (IVA)

operation_rating

Calificación de la operación
ValeurDescription
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
ValeurDescription
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
ValeurDescription
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
ValeurDescription
01IVA
02IPSI (Ceuta y Melilla)
03IGIC (Canarias)
05Otros

check_docs

Estados de documentos
ValeurDescription
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).

Validation des données

Contrôles et validations de la référence originale pour vérifier les données avant leur envoi à l’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.