Verifactu Direct API

Verifactu Direct API es el producto de Bilteo para registrar en Veri*Factu facturas que ya emitiste en otro programa (otro ERP, TPV o software de gestión) y remitirlas a la AEAT. Aquí Bilteo es la pasarela legal, no el emisor: tú aportas la factura ya hecha —serie, número, fecha, tipo y el desglose ya clasificado— en un modelo plano, y Bilteo la encadena por huella y la envía. Sin borradores, sin series de Bilteo, sin catálogos. Importes como string; fechas en ISO 2026-06-13.

¿Es este el producto que necesitas?

Usa Verifactu Direct API si tu software ya genera y numera las facturas y solo te falta cumplir Veri*Factu. Si lo que quieres es que Bilteo emita y numere la factura (y te dé el PDF/Facturae), eso es la API Pública de Bilteo, el otro producto. Comparativa y casos de uso: Dos productos.

Requisitos

• Una API key o un token OAuth2 con el scope verifactu:write.
• El gate de cuenta vf_direct_api.enabled activado (lo habilita Bilteo tras verificar tu integración). Si está desactivado, el endpoint responde 403.

Datos de ejemplo

Los NIF, VAT-IES, pasaportes, nombres e importes de esta sección son ficticios, solo para ilustrar cada caso. Sustitúyelos por los de tu factura real.

El alta, pieza a pieza

Una factura de Verifactu Direct API es plana: su identidad, el tipo, el total, el destinatario y las líneas. El emisor no se envía (lo pone tu tenant).

Campo
serie / numero	Identidad de la factura. La pones tú; única por tenant. serie puede ir vacía.
fecha_expedicion	ISO YYYY-MM-DD.
fecha_operacion	Opcional, si difiere de la expedición.
tipo_factura	F1, F2, F3, R1–R5 (ver Tipos de factura).
descripcion	Descripción de la operación.
importe_total	Total de la factura (string; negativo en abonos).
nif + nombre	Destinatario español. Para extranjeros, usa id_otro. Opcional en F2/R5.
lineas[]	El desglose, ya clasificado (ver abajo).

Cómo se clasifica cada línea

Cada línea declara cómo tributa. Bilteo no lo deriva de ningún catálogo: lo aportas tú.

Campo de la línea	Para qué
impuesto	01 IVA (por defecto) · 02 IPSI · 03 IGIC
base_imponible	Base imponible (o importe no sujeto). Negativa en abonos.
tipo_impositivo + cuota_repercutida	Operación sujeta: el % y su cuota.
operacion_exenta	Operación exenta: E1–E6 (en vez de tipo/cuota).
calificacion_operacion	S1 sujeta · S2 ISP · N1 no sujeta · N2 no sujeta por localización
clave_regimen	Régimen: 01 general · 02 exportación · 03 REBU · 17 OSS · 18 recargo eq.…
tipo_recargo_equivalencia + cuota_recargo_equivalencia	Recargo de equivalencia.

Regla práctica: una línea lleva o tipo_impositivo+cuota_repercutida (sujeta), o operacion_exenta (exenta), o calificacion_operacion N1/N2 (no sujeta). Los ejemplos por escenario están en Tipos de operación.

Alta paso a paso (F1 nacional)

El caso base: una factura ordinaria a un cliente español, una línea 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": "Mantenimiento mensual",
    "nif": "B72648193", "nombre": "Talleres Marverde 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…" }   ← usa verifactu_record_id para seguir el estado

La factura entra en la misma cadena Veri*Factu que tus facturas nativas y se remite a la AEAT; nace pending y el veredicto llega después (ver Seguir el estado).

El envelope se repite

En los ejemplos de Tipos de factura y Tipos de operación se muestra solo lo que cambia. El resto del cuerpo —cabeceras, serie, numero, fecha_expedicion, tipo_factura, descripcion, importe_total— va igual que aquí.

Validar el cliente contra el censo de la AEAT

Si el destinatario lleva un NIF español y quieres asegurarte de que está censado en la AEAT antes de registrar (la AEAT rechaza las facturas a destinatarios no censados), añade "validar_cliente": true:

{ "serie": "FV", "numero": "1060", "fecha_expedicion": "2026-04-10",
  "tipo_factura": "F1", "descripcion": "Servicios",
  "nif": "B72648193", "nombre": "Talleres Marverde SL",
  "validar_cliente": true,
  "lineas": [ { "base_imponible": "350", "tipo_impositivo": "21", "cuota_repercutida": "73.50" } ],
  "importe_total": "423.50" }
// Si el NIF no está identificado en el censo → 422 (no se registra nada)

Bilteo consulta el censo de la AEAT (con la misma caché que la validación de clientes nativa) y, si el NIF no está identificado, rechaza el alta con 422 sin registrar nada. Por defecto el flag es false: respondes tú de los datos. No aplica a destinatarios extranjeros (id_otro) ni a simplificadas sin destinatario.