> ## 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.

# Descripció general de l'API

> Una introducció bàsica a l'API de YoFacturo.

## 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`:

```json theme={null}
{
  "data": {
    "id": 123,
    "status": "received",
    ...
  }
}
```

**Excepció:** `POST /api/v1/auth/sessions` retorna un objecte JSON pla a nivell arrel — sense envelope `data`:

```json theme={null}
{
  "session_token": "...",
  "expires_at": "2026-03-27T10:30:00Z"
}
```

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

```json theme={null}
{
  "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):

```json theme={null}
{
  "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.

```http theme={null}
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 theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 30
```

<Note>
  `POST /api/v1/invoice_batches` està **exclòs** del rate limiting — la idempotència ja prevé el processament duplicat.
</Note>

## Respostes d'error

Tots els errors segueixen un envelope consistent:

```json theme={null}
{
  "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`          |