> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.eis.it/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.eis.it/_mcp/server.

# Convenzioni API

> Convenzioni delle API Hive per ambienti, versionamento, formati dei body, parametri e risposte.

## Ambienti e versione

| Ambiente   | URL di base                  |
| ---------- | ---------------------------- |
| Produzione | `https://api.eis.it`         |
| Staging    | `https://api.staging.eis.it` |

Gli endpoint applicativi pubblicati usano il prefisso `/v1`. L'autenticazione usa `/auth/api-key/login`.

## Formati delle richieste

Il formato dipende dall'operazione:

* `application/json` per i body strutturati;
* `application/x-www-form-urlencoded` per il login e le operazioni indicate nella reference;
* `multipart/form-data` per upload di file e moduli misti.

Usa esattamente nomi, tipi e obbligatorietà riportati nella reference. Questo vale anche per i parametri `path` e `query` e per i campi legacy.

## Risposte

I payload di risposta sono definiti per singola operazione. Alcuni endpoint restituiscono un oggetto, altri una lista o una risposta senza body. Il codice client deve quindi basarsi sullo schema dell'endpoint e sul relativo status HTTP.

## Date e identificativi

Il formato di date, orari e identificativi non è uniforme tra tutti i moduli. Non applicare conversioni globali: verifica il tipo e l'esempio dichiarati nello schema specifico.

Il contratto pubblicato non dichiara un limite di frequenza globale. Non assumere soglie non presenti nella reference.