Dos productes: API pública i Verifactu Direct API
Bilteo ofereix dos productes d'integració per a problemes diferents. Comparteixen la mateixa API REST (/api/v1), autenticació amb API key o OAuth2, cadena Veri*Factu i webhooks, però el model de dades i l'objectiu són diferents. Pots utilitzar-ne un o tots dos al mateix tenant.
La pregunta clau és: qui emet la factura?
| API pública de Bilteo | Verifactu Direct API | |
|---|---|---|
| En una frase | Bilteo és el teu sistema de facturació | Bilteo és la teva passarel·la Veri*Factu |
| Qui emet? | Bilteo | El teu programari; la factura ja està emesa |
| Numeració i sèries | Les gestiona Bilteo | Les aportes tu |
| Model de dades | Clients, productes, sèries, activitats i motor d'impostos | Registre Veri*Factu pla i ja classificat |
| Cicle de vida | esborrany → emesa → anul·lar o rectificar | Sense esborrany: registres allò que ja has emès |
| Classificació fiscal | Bilteo la deriva del catàleg | L'aportes tu: S1/S2/N1/N2, exempció i règim |
| Document per al client | PDF, Facturae i email amb QR | No; el document ja el genera el teu programari |
| Endpoint principal | /invoices i catàlegs relacionats | /external-invoices |
| Scopes | invoices:* | verifactu:write / verifactu:read |
Tots dos generen un registre Veri*Factu encadenat per empremta, el remeten a l'AEAT i n'informen el resultat pels mateixos webhooks.
API pública: Bilteo emet
Crees una factura com a esborrany. En emetre-la, Bilteo assigna un número d'una sèrie correlativa, calcula els impostos, genera i remet el registre Veri*Factu i produeix el PDF o Facturae amb QR.
El flux és POST /invoices → editar línies → POST /invoices/:id/actions/issue. També gestiones clients, productes, sèries i activitats econòmiques. Comença per Primers passos i el cicle de vida.
Les factures creades per API apareixen al mateix tenant de l'app de Bilteo. El teu equip les pot consultar, descarregar, enviar o gestionar manualment sense duplicar dades.
Casos habituals:
- SaaS verticals, comerços electrònics o marketplaces sense motor fiscal propi.
- Empreses que volen automatitzar la facturació des del seu backoffice.
Verifactu Direct API: el teu programari emet
/external-invoices registra a Veri*Factu factures ja emeses per un altre programa. Tu aportes sèrie, número, data, tipus i desglossament fiscal ja classificat; Bilteo encadena per empremta i envia. No hi ha esborranys, catàlegs ni documents de Bilteo.
El flux és POST /external-invoices → estat pending → veredicte de l'AEAT per webhooks verifactu.*. També hi ha anul·lació, subsanació i alta en lot. Consulta Verifactu Direct API.
Casos habituals:
- ERP, TPV o programari sectorial que ja numera i genera factures.
- Migracions des d'un altre proveïdor Veri*Factu sense canviar l'emissió.
Quin producte necessito?
- Vols que Bilteo generi, numeri i produeixi el document? → API pública.
- El teu programari ja ha generat i numerat la factura? → Verifactu Direct API.
Pots utilitzar tots dos per a fluxos diferents al mateix tenant.
Què comparteixen
- Autenticació i scopes.
- Webhooks
verifactu.*per al veredicte de l'AEAT. - Idempotència, paginació i errors.
- Entorn de proves contra l'AEAT d'homologació.