Verifactu Direct API

Verifactu Direct API és el producte de Bilteo per registrar a Veri*Factu factures que ja has emès amb un altre programa —un ERP, TPV o programari de gestió— i remetre-les a l'AEAT. Bilteo actua com a passarel·la legal, no com a emissor: tu aportes la factura acabada, amb la sèrie, el número, la data, el tipus i el desglossament ja classificat, mitjançant un model pla. Bilteo l'encadena per empremta i l'envia. No hi ha esborranys, sèries de Bilteo ni catàlegs. Els imports són strings i les dates tenen format ISO, com ara 2026-06-13.

És el producte que necessites?

Utilitza Verifactu Direct API si el teu programari ja genera i numera les factures i només et falta complir Veri*Factu. Si vols que Bilteo emeti i numeri la factura i et proporcioni el PDF/Facturae, utilitza l'API pública de Bilteo. Consulta la introducció per comparar-los.

Requisits

• Una clau API o token OAuth2 amb l'scope verifactu:write.
• El gate de compte vf_direct_api.enabled activat. Bilteo l'habilita després de verificar la integració. Si està desactivat, l'endpoint respon 403.

Dades d'exemple

Els NIF, VAT-IES, passaports, noms i imports d'aquesta pàgina són ficticis. Canvia'ls per les dades de la factura real.

L'alta, camp a camp

Una factura de Verifactu Direct API és plana: inclou la identitat, el tipus, el total, el destinatari i les línies. No s'envia l'emissor, perquè l'aporta el tenant.

Camp	Descripció
serie / numero	Identitat de la factura. La proporciones tu i és única per tenant. serie pot quedar buida.
fecha_expedicion	Data ISO YYYY-MM-DD.
fecha_operacion	Opcional, quan és diferent de la data d'expedició.
tipo_factura	F1, F2, F3 o R1–R5.
descripcion	Descripció de l'operació.
importe_total	Total de la factura com a string; negatiu en abonaments.
nif + nombre	Destinatari espanyol. Per a estrangers, utilitza id_otro. Opcional en F2/R5.
lineas[]	El desglossament fiscal, ja classificat.

Com es classifica cada línia

Cada línia declara com tributa. Bilteo no ho deriva de cap catàleg: ho aportes tu.

Camp de la línia	Finalitat
impuesto	01 IVA, per defecte · 02 IPSI · 03 IGIC
base_imponible	Base imposable o import no subjecte. Negativa en abonaments.
tipo_impositivo + cuota_repercutida	Operació subjecta: percentatge i quota.
operacion_exenta	Operació exempta: E1–E6, en lloc de tipus i quota.
calificacion_operacion	S1 subjecta · S2 ISP · N1 no subjecta · N2 no subjecta per localització
clave_regimen	Règim: 01 general · 02 exportació · 03 REBU · 17 OSS · 18 recàrrec d'equivalència…
tipo_recargo_equivalencia + cuota_recargo_equivalencia	Recàrrec d'equivalència.

Regla pràctica: una línia conté o bé tipo_impositivo i cuota_repercutida (subjecta), o bé operacion_exenta (exempta), o bé una calificacion_operacion N1/N2 (no subjecta).

Alta pas a pas: F1 nacional

Cas bàsic: una factura ordinària a un client espanyol amb una línia al 21 %.

curl -X POST https://api.test.bilteo.com/api/v1/external-invoices \
  -H "Authorization: Bearer bk_live_xxx" -H "Content-Type: application/json" \
  -d '{
    "serie": "FV", "numero": "1042", "fecha_expedicion": "2026-02-10",
    "tipo_factura": "F1", "descripcion": "Manteniment mensual",
    "nif": "B72648193", "nombre": "Tallers Marverd SL",
    "lineas": [
      { "base_imponible": "350", "tipo_impositivo": "21", "cuota_repercutida": "73.50" }
    ],
    "importe_total": "423.50"
  }'
# → 201
# { "id": "EXT…", "serie": "FV", "numero": "1042", "state": "pending",
#   "verifactu_record_id": "VF…" }

La factura entra a la mateixa cadena Veri*Factu que les factures natives i es remet a l'AEAT. Neix amb estat pending; utilitza verifactu_record_id per seguir-ne el veredicte.

Validar el client amb el cens de l'AEAT

Si el destinatari té un NIF espanyol i vols comprovar que consta al cens abans de registrar la factura, afegeix "validar_cliente": true:

{ "serie": "FV", "numero": "1060", "fecha_expedicion": "2026-04-10",
  "tipo_factura": "F1", "descripcion": "Serveis",
  "nif": "B72648193", "nombre": "Tallers Marverd SL",
  "validar_cliente": true,
  "lineas": [ { "base_imponible": "350", "tipo_impositivo": "21", "cuota_repercutida": "73.50" } ],
  "importe_total": "423.50" }
// Si el NIF no està identificat al cens → 422 i no es registra res

Bilteo consulta el cens de l'AEAT i, si el NIF no està identificat, rebutja l'alta amb 422 sense registrar res. Per defecte, el flag és false. No s'aplica als destinataris estrangers (id_otro) ni a les simplificades sense destinatari.

El contracte complet és a la Referència de l'API.