Guía rápida de integración de las APIs de Verifacti

Esta guía explica paso a paso cómo integrar tu software con la API Verifactu, la API TicketBAI o la API SII, de la cuenta gratuita a producción. La cuenta, los NIFs, el modelo de representación y el paso a producción son comunes a todas; en los pasos que cambian según la API (envío, estado y correcciones) elige la tuya y la guía muestra solo lo que te aplica.

1. Crea una cuenta gratuita

Crea una cuenta gratuita en 30 segundos:

  1. Haz clic en el botón regístrate gratis.
  2. Introduce tu email y contraseña.
  3. Verifica tu email haciendo clic en el correo que te enviamos.

Una vez dentro accederás al panel de empresas, donde hay una empresa de prueba ya configurada para enviar facturas al entorno de prueba de la AEAT con Verifactu, desde nuestra interfaz o mediante la API. Se puede completar toda la integración básica con la cuenta gratuita.

panel de empresas
Panel de empresas con la empresa de prueba

La empresa de prueba es de Verifactu. Para probar TicketBAI o el SII necesitas un NIF de test de esa hacienda: pídelo a soporte@verifacti.com indicando cuál (Álava, Bizkaia, Gipuzkoa o SII) y te lo activamos.

Consulta qué incluye la cuenta gratuita y si puedo probar TicketBAI con la cuenta gratuita.

2. Envía una factura de prueba

Cuando entres a la empresa de prueba, verás una terminal integrada para enviar facturas a la AEAT. Dicha terminal ofrece una interfaz sencilla para cargar todo tipo de ejemplos de facturas y enviarlas con un solo clic al entorno de prueba de la AEAT.

terminal integrada
Terminal integrada para enviar facturas a la AEAT

La respuesta trae el código QR (como string en base 64) del registro de facturación generado, para que lo pegues en tu factura. El QR contiene la URL de la AEAT que permite ver si la factura ya está registrada en sus sistemas.

API - Crear facturas

Para generar un registro de facturación y enviarlo a la AEAT, llama a POST /verifactu/create con la API key del NIF de prueba (B75777847, el mismo en todas las cuentas), que está en su pestaña API key. Más detalle en la documentación.

POST /verifactu/create

Factura normal
{
  "serie": "Ejemplos",
  "numero": "1",
  "fecha_expedicion": "19-11-2026",
  "tipo_factura": "F1",
  "descripcion": "Factura normal",
  "nif": "A15022510",
  "nombre": "Nombre destinatario",
  "lineas": [
    {
      "base_imponible": "200",
      "tipo_impositivo": "21",
      "cuota_repercutida": "42"
    }
  ],
  "importe_total": "242"
}

3. Confirma el estado

En todas las APIs, la forma recomendada de saber el resultado es con los webhooks, que te avisan de cada cambio de estado. También puedes consultarlo con el endpoint de estado de cada API, o verlo en la tabla de registros del panel.

Tabla de registros - Correcto
Tabla de registros con un registro enviado correctamente

Al enviar la factura, la API devuelve el estado Pendiente: el registro se ha generado y está en cola para enviarse a la AEAT, normalmente en uno o dos minutos. Por el propio funcionamiento de Verifactu, los registros no se envían de forma inmediata. Consulta el estado con GET /verifactu/status y el uuid que devuelve la creación, y lista las facturas presentadas con POST /verifactu/list. Ver la documentación de la API Verifactu.

4. Corrige o anula facturas

Si la factura no exige una rectificativa, subsánala con PUT /verifactu/modify y el registro corregido. Si exige una rectificativa, créala con POST /verifactu/create y el tipo_factura que corresponda (R1 a R5). Para anular, POST /verifactu/cancel con serie, número y fecha de expedición; una factura anulada no se puede volver a crear con los mismos datos. Casos en las rectificativas de Verifactu.

POST /verifactu/cancel

/verifactu/cancel
{
  "serie": "A",
  "numero": "1",
  "fecha_expedicion": "25-02-2025"
}

PUT /verifactu/modify

Descripcion modificada
{
  "rechazo_previo": "N",
  "serie": "Ejemplos",
  "numero": "1",
  "fecha_expedicion": "19-11-2026",
  "tipo_factura": "F1",
  "nif": "A15022510",
  "nombre": "Nombre destinatario",
  "descripcion": "Descripcion modificada",
  "lineas": [
    {
      "base_imponible": "200",
      "tipo_impositivo": "21",
      "cuota_repercutida": "42"
    }
  ],
  "importe_total": "242"
}

5. Activa la suscripción de pago

Para preparar el paso a producción, activa tu suscripción de pago:

  1. Navega a la página de precios.
  2. Haz clic en el botón de "Comprar primer NIF". Se te redirigirá a la página de pago.
  3. Marca la casilla "Estoy comprando como empresa" para introducir tu CIF, que aparecerá en las facturas.
Checkout de Stripe
Página de activación de la suscripción

El SII tiene precio a medida, fuera de la página de precios: pide una propuesta en contacto. Consulta cuándo empiezo a pagar.

6. Da de alta tus NIFs

Con la suscripción activa puedes crear tantas empresas emisoras en modo test como quieras, sin coste adicional. Accede al panel de empresas y haz clic en "+ Añadir empresa".

Añadir empresa
Página para añadir una empresa

Elige bien el entorno y la hacienda. Las empresas de test envían al entorno de prueba y las de producción al real; solo estas últimas cuentan para la factura mensual. La hacienda fija el destino: verifactu, alava, vizcaya, guipuzcoa o sii. Cada combinación de NIF, entorno y hacienda es un NIF independiente con su propia API key, y un mismo NIF puede estar en varias haciendas a la vez.

API - Añadir NIFs emisores de facturas

Para enviar facturas de cientos o miles de empresas o autónomos, créalas con POST /nifs y la API key de tu cuenta, que está en los ajustes de la cuenta (sección API key). Cómo añadir, modificar o desactivar NIFs, en la documentación de la API de gestión de NIFs.

Recuerda que cada empresa tiene su propia API key para enviar sus facturas. Consulta cómo funcionan las API keys, los entornos y la gestión de NIFs.

7. Gestiona el modelo de representación

Para que Verifacti pueda enviar facturas en nombre de una empresa, hay que firmar un documento que nos autorice. Es el mismo para la AEAT (Verifactu y SII) y para las tres haciendas forales. Las empresas de prueba no lo necesitan, pero puedes rellenarlo desde la empresa de test y valdrá cuando la crees en producción.

Descarga el modelo ya cumplimentado desde la página de la empresa, donde se explica cómo rellenarlo, firmarlo y enviarlo. También se puede firmar online, con verificación por vídeo y sin certificado digital (2,90 € + IVA por firma, solo personas físicas): firma online.

Rellenar el modelo de representación
Página para rellenar el modelo de representación

API - Modelo de representación

Los modelos se pueden rellenar y enviar por API con la API key de tu cuenta (ajustes de la cuenta, sección API key). Detalle en la documentación.

Consulta cómo funciona la gestión de certificados y modelos de representación.

8. Pasa a producción

Con la integración completa y el modelo de representación firmado, crea la misma empresa en el entorno de producción, con su hacienda, y cambia la API key de test por la de producción. Los NIFs de producción son los que cuentan para la suscripción; un mismo NIF dado de alta en dos haciendas cuenta como dos NIFs.

API - Crear empresas en producción

Para pasar tus empresas de test a producción por API, encadena los endpoints de listar NIFs, obtener cada uno y crearlo en producción, con la API key de tu cuenta. Detalle en la documentación de la API de gestión de NIFs.

  • TicketBAI en Bizkaia: la API envía cada factura emitida al LROE de Batuz (modelo 140 o 240). Más en TicketBAI en Bizkaia.
  • SII: cuenta con el plazo de cuatro días naturales desde la expedición de cada factura, sin contar sábados, domingos ni festivos nacionales (ocho en las facturas expedidas por el destinatario o por un tercero). Detalle en los plazos del SII.

9. Publica la declaración responsable (solo Verifactu)

Para cumplir con Verifactu no hay homologación externa ni verificación por parte de la AEAT: cada software de facturación debe incluir un documento que autocertifique que cumple los requisitos. TicketBAI y el SII no la piden.

Con una API como la nuestra, tanto tu software como Verifacti deben tener su declaración responsable. Puedes descargar la de Verifacti (PDF) y usar nuestra plantilla para preparar la tuya. Consulta cómo publicar la declaración responsable.

Sigue con la integración

Ya tienes el flujo completo. Para seguir, lee la documentación de tu API y copia los ejemplos de facturas.

Preguntas frecuentes

Más preguntas frecuentes

¿Cuánto tiempo se tarda en hacer la integración?

En la mayor parte de los casos la integración queda realizada con el trabajo de un solo desarrollador en uno a tres días a tiempo completo, y posteriormente unos días adicionales a tiempo parcial.

¿Son diferentes las URLs de los endpoints en los entornos de test y producción?

Las URLs de los endpoints no cambian, son las mismas para los entornos de test y de producción. Lo que determina qué entorno se usa es la API key que se utilice.
Cada API key tiene un entorno asociado: test o producción.
  • En entorno de test, la API key de la empresa empieza por vf_test_
  • En entorno de producción, la API key de la empresa empieza por vf_prod_

¿Debo realizar una nueva integración para TicketBAI o es una misma integración para TicketBAI y Verifactu?

¿Por qué existen dos APIs diferentes para integrar con Verifactu y con TicketBAI?
Hemos decidido diseñar dos APIs diferenciadas, una para Verifactu y otra para TicketBAI, siguiendo en gran medida la estructura de las APIs oficiales de las administraciones.
Esto aporta varias ventajas:
  • Consistencia: los endpoints, campos y mensajes de error que presentamos a nuestros usuarios son prácticamente los mismos que en las APIs de las administraciones.
  • Facilidad en consultas fiscales: esta similitud elimina interpretaciones o sesgos derivados de una API intermedia, lo que agiliza la comunicación con asesores y con las propias administraciones.
¿Qué implica esto a la hora de integrar?
Es necesario integrar con dos APIs diferentes.
Sin embargo, en la práctica, tras integrar con Verifactu, la integración posterior con TicketBAI suele requerir solo un 10%-20% adicional de esfuerzo. Esto se debe a que varias llamadas coinciden y, cuando no lo hacen, mantienen una estructura muy similar.
Por ejemplo, al crear una factura será necesario contar con dos JSON diferentes, utilizando uno u otro según la API de destino.
Lo que sí es común es la API de gestión de NIFs (alta de NIFs, modelo de representación y webhooks): se integra una vez y vale para las dos APIs.

¿Puedo probar TicketBAI con la cuenta gratuita?

Sí. La cuenta gratuita incluye el entorno de test de TicketBAI, así que puedes hacer la integración sin coste. Para el NIF de test de la hacienda foral, escribe a soporte@verifacti.com. Para enviar facturas de NIFs reales a la hacienda foral necesitas una suscripción de pago.

¿Cuándo empiezo a pagar? ¿Tengo que pagar ya si Verifactu todavía no es obligatorio?

No. Puedes hacer toda la integración con la cuenta gratuita y solo empiezas a pagar cuando activas tu suscripción para dar de alta NIFs en producción.
Tú decides cuándo: puedes esperar a la fecha de obligatoriedad que te corresponda o empezar a enviar facturas a la AEAT de forma voluntaria antes.

¿Cómo hago mi declaración responsable?

La AEAT ha publicado un ejemplo de declaración responsable en PDF.
Nosotros hemos adaptado este ejemplo para nuestros usuarios. Lo puedes descargar aquí:
  • Proporcionamos un documento de Word editable.
  • Incluimos notas informativas para los apartados más complicados.
  • Añadimos una sección para explicar el papel de la API Verifacti.
Información clave para rellenar el documento:
  1. Los títulos de sección están en negrita y con letra más grande.
  2. Sustituye las respuestas de ejemplo con tus propios datos.
  3. Borra las notas informativas al completar el documento.
Es obligatorio mencionar a Verifacti como componente externo. Hemos incluido una sección específica para arquitecturas mixtas con componente externo. Tienes que indicar nuestra versión de software vigente, que puede cambiar: la devuelve GET /verifactu/declaracion junto con nuestra declaración.
👉 Ver vídeo corto: Declaración responsable parte 2: guía para completar la declaración responsable fácilmente
Más sobre la declaración responsable.

Empieza con la cuenta gratuita

El primer paso de la guía: entorno de test y NIF de prueba incluidos.

Entorno de test y NIF de prueba incluidosLee la documentación