Saltar al contingut principal

Documentation Index

Fetch the complete documentation index at: https://docs.yofacturo.es/llms.txt

Use this file to discover all available pages before exploring further.

​
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. 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àmetreTipusPer defecteMàximDescripció
pageinteger1—Número de pàgina (base 1)
per_pageinteger25100Resultats 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 HTTPCodiDescripció
400bad_requestParàmetre requerit absent o buit
401unauthorizedAutenticació absent, invàlida o expirada
404not_foundRecurs no trobat a l’organització actual
422missing_idempotency_keyLa capçalera Idempotency-Key és absent
422invalid_idempotency_keyIdempotency-Key no és un UUID vàlid
422validation_failedEl cos de la sol·licitud ha fallat la validació (vegeu message)
422unprocessable_contentEl registre no s’ha pogut desar per errors de validació
429too_many_requestsMassa sol·licituds — consulta la capçalera Retry-After