Descripció general de l'API

URL base

Tots els endpoints de l’API són relatius a:

https://app.yofacturo.es

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.

Format de sol·licitud

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",
    ...
  }
}

Excepció: 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"
}

Les respostes de llista inclouen un objecte meta amb informació de paginació:

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "total_pages": 4,
    "total_count": 87,
    "per_page": 25
  }
}

L’endpoint 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"]
  }
}

L’objecte 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`

👋 Introducció

🔌 API REST

🤖 MCP

Descripció general de l'API

URL base

Versions

Format de sol·licitud

Format de resposta

Paginació

Idempotència

Rate limiting

Respostes d’error

Codis d’error

​URL base

​Versions

​Format de sol·licitud

​Format de resposta

​Paginació

​Idempotència

​Rate limiting

​Respostes d’error

​Codis d’error

URL base

Versions

Format de sol·licitud

Format de resposta

Paginació

Idempotència

Rate limiting

Respostes d’error

Codis d’error