bilteo

Català

Español
English

Català

Español
English

Aparença

Verifactu Direct API · lot, estat, errors i idempotència ​

Operativa posterior a l'alta: registre en lot, seguiment del veredicte de l'AEAT, errors i prevenció de duplicats.

Alta en lot ​

Pots registrar fins a 75 factures en una petició a POST /external-invoices/bulk. És una operació de tot o res: si una factura falla per validació o duplicat, no se'n registra cap i no queden buits a la cadena Veri*Factu. Cada factura admet els mateixos camps que una alta individual.

bash
curl -X POST https://api.test.bilteo.com/api/v1/external-invoices/bulk \
  -H "Authorization: Bearer bk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "facturas": [
        { "serie": "FV", "numero": "1070", "fecha_expedicion": "2026-04-15",
          "tipo_factura": "F1", "descripcion": "Servei mensual", "nif": "A39208155",
          "nombre": "Gráficas Belmar SA",
          "lineas": [ { "base_imponible": "120", "tipo_impositivo": "21", "cuota_repercutida": "25.20" } ],
          "importe_total": "145.20" },
        { "serie": "TPV", "numero": "5588", "fecha_expedicion": "2026-04-15",
          "tipo_factura": "F2", "descripcion": "Venda a botiga",
          "lineas": [ { "base_imponible": "40", "tipo_impositivo": "10", "cuota_repercutida": "4" } ],
          "importe_total": "44" }
      ] }'
# → 201, { "facturas": [ { "id": "EXT…", "numero": "1070", "verifactu_record_id": "VF…" }, … ] }

El registre és síncron; l'enviament a l'AEAT es fa després, igual que en l'alta individual. Per a volums de milers de factures, divideix-les en lots o contacta'ns.

Seguir l'estat ​

L'alta és asíncrona: neix en estat pending i l'AEAT respon després. Rep el veredicte per webhooks verifactu.accepted / verifactu.rejected / verifactu.error, o consulta'l amb el verifactu_record_id:

bash
# Registre Veri*Factu (detall del veredicte)
curl https://api.test.bilteo.com/api/v1/verifactu-records/VF… \
  -H "Authorization: Bearer bk_live_xxx"

# La factura: el seu `state` se sincronitza amb el veredicte de l'AEAT
#   (pending → registered | rejected | cancelled)
curl https://api.test.bilteo.com/api/v1/external-invoices/EXT… \
  -H "Authorization: Bearer bk_live_xxx"
# I el llistat amb filtres:
curl "https://api.test.bilteo.com/api/v1/external-invoices?state=rejected" \
  -H "Authorization: Bearer bk_live_xxx"

Errors ​

CodiQuan es produeix
403 permission_errorEl gate vf_direct_api.enabled està desactivat o la clau no té verifactu:write.
409 conflict_errorJa has registrat una factura amb la mateixa (serie, numero) o external_id, o hi ha un reintent amb la mateixa Idempotency-Key en curs.
400 validation_errorFalta un camp, la data no és ISO o el desglossament és incoherent.
422 verifactu_errorEl desglossament no és vàlid fiscalment o, amb validar_cliente, el NIF del destinatari no consta al cens de l'AEAT.

Idempotència ​

Hi ha dos mecanismes complementaris:

  • Idempotency-Key (capçalera): evita que un reintent de l'alta o anul·lació dupliqui el registre. Envia una clau opaca única per operació; un reintent amb la mateixa clau i cos reprodueix la resposta original.

    bash
    curl -X POST https://api.test.bilteo.com/api/v1/external-invoices \
  -H "Authorization: Bearer bk_live_xxx" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7e9f…-uuid-per-operació" \
  -d '{ … }'

  • external_id (camp): enllaç permanent amb el teu sistema. Una segona alta amb el mateix external_id retorna 409; serveix de protecció contra duplicats a llarg termini i per consultar-la després (GET /external-invoices?external_id=…).

Bilteo · Documentació

© Bilteo