# API — Catalogo e convenzioni

Ultimo aggiornamento: **{{DATA}}**

Il contratto è [`openapi.yaml`](openapi.yaml), **fonte di verità**: in caso di differenza fra
questo documento, il codice e il contratto, vale il contratto. Si scrive il contratto **prima**
del codice (contract-first).

---

## 1. Convenzioni

| Aspetto | Regola |
|---|---|
| Prefisso | `/api/v1` |
| Formato | JSON, UTF-8, date ISO 8601 in UTC |
| Nomi | <!-- DA COMPILARE: snake_case o camelCase, una sola scelta --> |
| Autenticazione | <!-- DA COMPILARE --> |

## 2. Errori

Forma unica per tutti gli errori:

```json
{ "error": { "code": "stringa_stabile", "message": "testo leggibile", "details": {} } }
```

| Codice HTTP | Quando |
|:-:|---|
| 400 | Richiesta malformata |
| 401 | Non autenticato |
| 403 | Autenticato ma non autorizzato |
| 404 | Risorsa inesistente **o di un altro tenant** (non si rivela l'esistenza) |
| 409 | Conflitto (duplicato, stato non compatibile) |
| 422 | Validazione fallita |

## 3. Paginazione

<!-- DA COMPILARE: parametri (page/size o cursore), limiti massimi, forma della risposta. -->

## 4. Catalogo

### <!-- Gruppo --> — `SPEC-…`

| Metodo | Percorso | Ruolo minimo | Descrizione |
|---|---|---|---|
| <!-- DA COMPILARE --> | | | |

## 5. API interne — non esposte

<!-- DA COMPILARE o «nessuna». -->

## 6. Idempotenza e concorrenza

<!-- DA COMPILARE: chiavi di idempotenza, controllo delle versioni, comportamento in caso di doppio invio. -->

## 7. Limiti

<!-- DA COMPILARE: rate limit, dimensioni massime dei corpi e dei file. -->