Convencions de l'API

Regles comunes de format, paginació, filtres, idempotència i valors per defecte.

Base i format

Base URL:  https://api.test.bilteo.com/api/v1

• HTTPS i JSON (Content-Type: application/json).
• Authorization: Bearer bk_live_… o Bearer bo_at_…; consulta Autenticació.
• Els IDs de Bilteo són UUID. Per usar els teus, consulta external_id.

Imports decimals com a text

Imports i quantitats viatgen com a string per evitar pèrdua de precisió:

{ "quantity": "1", "unit_price": "100.00", "discount": "10" }

Dates

• Dates d'operació: YYYY-MM-DD.
• Marques de temps: RFC 3339 en UTC, per exemple 2026-01-15T10:00:00Z.

Paginació per cursor

Els llistats retornen:

{
  "data": [],
  "next_cursor": "AAECAwQFBgcICQoLDA0ODw",
  "has_more": true
}

limit accepta d'1 a 100 resultats i val 50 per defecte. A la petició següent, envia next_cursor com a ?cursor= fins que has_more sigui false.

El cursor és opac

No el processis ni el construeixis. Un cursor invàlid retorna 400 (pagination.invalid_cursor).

Filtres

Els filtres es combinen entre ells i amb la paginació:

Recurs	Filtres principals
/invoices	state, type, partner_id
/external-invoices	state, external_id
/verifactu-records	invoice_id, state
/partners	type, is_active, search, external_id
/products	is_active, search, external_id
/series	type, is_active
/taxes	type, tax_use, is_active
/economic-activities	is_active

search fa una coincidència parcial; external_id és exacte i únic per tenant. La referència de l'API defineix tots els valors admesos.

Idempotència

Mecanisme	Objectiu	Abast
Idempotency-Key	Evitar duplicats en reintentar una escriptura	24 h, per petició
external_id	Enllaç permanent entre el teu registre i Bilteo	Persistent, per recurs

Reintents segurs amb Idempotency-Key

Envia una clau opaca nova per operació lògica:

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-operacio" \
  -d '{ "numero": "1", "fecha_expedicion": "2026-06-13", "tipo_factura": "F1" }'

Situació	Resultat
Mateixa clau i cos ja processats	Repeteix la resposta amb Idempotent-Replayed: true.
Mateixa clau encara en procés	409 idempotency.request_in_progress.
Mateixa clau amb un altre cos	422 idempotency.key_reused_with_different_body.

La capçalera és opcional. Reutilitza una clau només per reintentar exactament la mateixa operació.

Sincronització per external_id

partners i products accepten el teu identificador, únic per tenant. Pots adreçar-los amb …/by-external-id/{external_id}:

Operació	Ruta
Crear o actualitzar	PUT /partners/by-external-id/{ext}
Llegir	GET /partners/by-external-id/{ext}
Actualitzar parcialment	PATCH /partners/by-external-id/{ext}
Eliminar	DELETE /partners/by-external-id/{ext}
Cercar	GET /partners?external_id={ext}

El PUT convergeix al mateix estat: retorna 201 quan crea i 200 quan actualitza. El patró és idèntic per a /products.

curl -X PUT "https://api.test.bilteo.com/api/v1/partners/by-external-id/CLI-00042" \
  -H "Authorization: Bearer bk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "type": "com", "name": "Comercial Aldealta SL", "id_num": "B85447761", "country": "ES" }'

external_id és persistent; Idempotency-Key només protegeix un reintent puntual. Per esborrar external_id en un PATCH, envia una cadena buida.

Valors per defecte: sèrie, activitat i moneda

Camp	Cascada
Activitat econòmica	L'única activa → default del tenant → primera activa.
Sèrie	Default de l'activitat per al tipus → primera sèrie del tipus.
Moneda	Default del tenant → EUR.

Envia aquests camps només quan necessitis fixar un valor concret.

Codis HTTP

Codi	Quan
200	Operació correcta.
201	Recurs creat.
204	Operació correcta sense cos.
400	Petició o camps invàlids.
401	Credencial absent, invàlida o caducada.
403	Falta l'scope o el recurs no és editable.
404	El recurs no existeix al tenant.
409	Conflicte amb l'estat o un identificador.
422	L'operació no es pot completar.

Consulta el sobre comú a Errors.