Dos productos: API Pública y Verifactu Direct API
Bilteo ofrece dos productos de integración que resuelven problemas distintos. Comparten plataforma —la misma API REST (/api/v1), la misma autenticación mediante API key u OAuth2, la misma cadena Veri*Factu y los mismos webhooks— pero el modelo de datos y el para qué son muy diferentes. Puedes usar uno, el otro o los dos a la vez en el mismo tenant.
La pregunta que los separa es ¿quién emite la factura?
| API Pública de Bilteo | Verifactu Direct API | |
|---|---|---|
| En una frase | Bilteo es tu sistema de facturación | Bilteo es tu pasarela a Veri*Factu |
| ¿Quién emite la factura? | Bilteo | Tu software (ya está emitida) |
| Numeración y series | Las gestiona Bilteo (legal, correlativa, inmutable) | Las pones tú |
| Modelo de datos | Rico: clientes, productos, series, actividades, motor de impuestos | Plano: el registro Veri*Factu, ya clasificado |
| Ciclo de vida | borrador → emitida → anular / rectificar | Sin borrador: registras lo ya emitido |
| Clasificación fiscal | La deriva Bilteo de tu catálogo | La aportas tú (S1/S2/N1/N2, exención, régimen) |
| Documento para el cliente | Sí: PDF / Facturae / email, con QR | No: el documento ya lo generó tu software |
| App web de Bilteo | Incluida: lo que creas por API se ve y gestiona en la app (mismo tenant) | — (pasarela headless: gestionas en tu software) |
| Endpoint principal | /invoices (+ /partners, /products, /series…) | /external-invoices |
| Scopes | invoices:* | verifactu:write / verifactu:read |
Por debajo, ambos acaban en el mismo sitio: un registro Veri*Factu encadenado por huella y remitido a la AEAT, con el veredicto notificado por los mismos webhooks.
API Pública de Bilteo — Bilteo es tu sistema de facturación
Qué es. Una API REST para emitir facturas legalmente desde cero. Creas la factura como borrador y, al emitirla, Bilteo le asigna el número de una serie correlativa, calcula el desglose de impuestos desde tu catálogo fiscal, genera el registro Veri*Factu, lo remite a la AEAT y produce el documento final (PDF / Facturae con QR) listo para tu cliente.
Qué resuelve. "No tengo —o no quiero construir— un sistema de facturación con Veri*Factu. Quiero que Bilteo lo sea, vía API."
Cómo funciona. POST /invoices (borrador) → editar líneas → POST /invoices/:id/actions/issue (numera + remite) → descargar PDF/Facturae o enviar por email. Gestionas también tus clientes, productos, series y actividades económicas. Empieza por Primeros pasos y el Ciclo de vida de una factura.
Funciona junto a la app de Bilteo. No es una API a ciegas: opera sobre el mismo tenant que la app web de Bilteo, así que las facturas que creas o emites por API aparecen al instante en la app, donde tú o tu equipo podéis consultarlas, descargar el PDF, enviarlas por email, editar borradores o emitir a mano, y ver el panel y el estado Veri*Factu. Automatizas lo repetitivo por API y dejas lo manual o excepcional para la app, sobre los mismos datos — no tienes que elegir entre API o herramienta. (Verifactu Direct API no tiene este componente: es una pasarela; el documento y su gestión siguen viviendo en tu software.)
Casos de uso
- Un SaaS vertical (reservas, clínicas, gimnasios, suscripciones) que necesita facturar legalmente a sus usuarios sin construir su propio motor de facturación + Veri*Factu.
- Un e-commerce o marketplace sin facturación propia que quiere que Bilteo sea su sistema de facturación.
- Una empresa o autónomo que automatiza su facturación desde su backoffice.
Verifactu Direct API — Bilteo es tu pasarela a Veri*Factu
Qué es. Un endpoint plano (/external-invoices) para registrar en Veri*Factu facturas que ya emitió otro programa y remitirlas a la AEAT. Tú aportas serie, número, fecha, tipo y el desglose ya clasificado; Bilteo encadena por huella y envía. No hay borrador, ni series de Bilteo, ni catálogos, ni documento: Bilteo es solo la pasarela legal.
Qué resuelve. "Ya tengo mi sistema de facturación, con su numeración y sus documentos. Solo necesito cumplir Veri*Factu sin rehacerlo."
Cómo funciona. POST /external-invoices con la factura plana → Bilteo la registra (pending) y encola el envío → el veredicto de la AEAT te llega por webhooks verifactu.* y sincroniza el state. También: anulación (/external-invoices/cancel), subsanación (rechazo_previo) y alta en lote (/bulk). Guía completa: Verifactu Direct API.
Casos de uso
- Un ERP o TPV consolidado que ya emite facturas con su numeración y solo necesita cumplir Veri*Factu (adaptarse a la norma sin tocar su facturación).
- Un software de gestión sectorial (talleres, hostelería, despachos) con su propia facturación que necesita la pasarela a la AEAT.
- Una empresa que migra de otro proveedor Veri*Factu y conserva su emisión actual.
¿Qué producto necesito?
Decídelo por quién genera y numera la factura:
- ¿Quieres que Bilteo genere y numere la factura (y te dé el PDF/Facturae)? → API Pública de Bilteo.
- ¿La factura ya la generó tu software (numeración incluida) y solo necesitas registrarla en Veri*Factu? → Verifactu Direct API.
¿Las dos cosas, para flujos distintos? Puedes usar ambos en el mismo tenant: comparten cadena, webhooks y credenciales.
Lo que comparten los dos productos
Da igual el producto: todo pasa por la misma cadena Veri*Factu del tenant y el mismo envío a la AEAT. Además comparten:
- Autenticación por API key u OAuth2 + scopes.
- Webhooks
verifactu.*para el veredicto de la AEAT — ver Webhooks. - Idempotencia, paginación y errores — ver Convenciones y Errores.
- Entorno de pruebas (sandbox) que remite a la AEAT de homologación — ver Pruebas.