URL base
Tots els endpoints de l’API són relatius a:
Versions
La versió estable actual és v1. Tots els endpoints v1 tenen el prefix /api/v1/.
No existeixen capçaleres de negociació de versió — la versió forma part del camí de la URL.
- Content type:
application/json
- Codificació: UTF-8
- Tots els timestamps han d’estar en format ISO 8601 (
YYYY-MM-DDTHH:MM:SSZ)
- Les dates (sense hora) han de ser
YYYY-MM-DD
Format de resposta
Totes les respostes retornen JSON.
Excepció: GET /api/v1/batch_invoices/{id}/pdf retorna un payload binari application/pdf (el PDF de la factura emesa associada).
La majoria d’endpoints que retornen un únic recurs embolcallen el contingut a la clau data:
{
"data": {
"id": 123,
"status": "received",
...
}
}
POST /api/v1/auth/sessions retorna un objecte JSON pla a nivell arrel — sense envelope data:
{
"session_token": "...",
"expires_at": "2026-03-27T10:30:00Z"
}
meta amb informació de paginació:
{
"data": [...],
"meta": {
"current_page": 1,
"total_pages": 4,
"total_count": 87,
"per_page": 25
}
}
POST /api/v1/invoice_batches pot incloure addicionalment una clau errors juntament amb data quan algunes factures del lot fallen la validació (èxit parcial):
{
"data": { ... },
"errors": {
"inv-bad-001": ["Issuer nif no puede estar en blanco"]
}
}
errors està indexat per external_invoice_id.
Paginació
Els endpoints de llista accepten dos paràmetres de consulta:
| Paràmetre | Tipus | Per defecte | Màxim | Descripció |
|---|
page | integer | 1 | — | Número de pàgina (base 1) |
per_page | integer | 25 | 100 | Resultats per pàgina |
Idempotència
POST /api/v1/invoice_batches requereix la capçalera Idempotency-Key amb un UUID vàlid. Reenviar la mateixa clau dins de la finestra d’idempotència retorna la resposta en memòria cau sense reprocessar el lot.
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Rate limiting
La majoria d’endpoints protegits apliquen límits de taxa per organització. Quan se supera el límit, l’API retorna 429 Too Many Requests amb la capçalera Retry-After indicant els segons d’espera.
HTTP/1.1 429 Too Many Requests
Retry-After: 30
POST /api/v1/invoice_batches està exclòs del rate limiting — la idempotència ja prevé el processament duplicat.
Respostes d’error
Tots els errors segueixen un envelope consistent:
{
"error": {
"code": "string",
"message": "Descripció llegible"
}
}
Codis d’error
| Estat HTTP | Codi | Descripció |
|---|
400 | bad_request | Paràmetre requerit absent o buit |
401 | unauthorized | Autenticació absent, invàlida o expirada |
404 | not_found | Recurs no trobat a l’organització actual |
422 | missing_idempotency_key | La capçalera Idempotency-Key és absent |
422 | invalid_idempotency_key | Idempotency-Key no és un UUID vàlid |
422 | validation_failed | El cos de la sol·licitud ha fallat la validació (vegeu message) |
422 | unprocessable_content | El registre no s’ha pogut desar per errors de validació |
429 | too_many_requests | Massa sol·licituds — consulta la capçalera Retry-After |
