---
title: Formato risposte & convenzioni
description: JSON raw senza envelope, formato canonical degli errori con status HTTP significativi, paginazione e filtri delle liste.
---

Le rotte canonical dell'API partner condividono un insieme di convenzioni
coerenti per il formato delle risposte, degli errori e per la lettura delle
liste. Questa pagina copre le convenzioni trasversali; lo schema esatto di ogni
risorsa resta sullo [Swagger](https://api.audin.ai/docs/partners).

## Formato delle risposte

Le rotte canonical ritornano **JSON raw**, nella stessa identica shape che il
dashboard consuma. **Non** c'è un envelope `{ success, data }`: il corpo della
risposta è direttamente la risorsa (o l'array di risorse).

Esempio di risposta di successo (`GET /leads/{id}`):

```json
{
  "id": "9b1c…",
  "fullName": "Mario Rossi",
  "phoneNumber": "+393331234567",
  "email": "mario@acme.example.com",
  "companyId": "3f2a…",
  "createdAt": "2026-06-01T09:00:00.000Z",
  "updatedAt": "2026-06-01T09:00:00.000Z"
}
```

I campi effettivi variano per risorsa: fai riferimento allo schema completo sullo
[Swagger](https://api.audin.ai/docs/partners).

## Formato degli errori

Sulle rotte canonical, gli errori tornano in forma **raw** con uno status HTTP
significativo:

```json
{
  "error": "Lead not found"
}
```

Lo **status code** è la fonte di verità per la gestione automatica:

| Status | Significato |
|--------|-------------|
| `400` | Bad request — validazione fallita / campi mancanti |
| `401` | Non autenticato — header `X-API-Key` mancante o invalido |
| `403` | Forbidden — la risorsa non appartiene all'Account |
| `404` | Not found — risorsa inesistente |
| `409` | Conflict — es. violazione di un unique constraint |
| `422` | Unprocessable — es. mismatch di `Idempotency-Key` |
| `429` | Rate limited — troppe richieste |
| `500` | Errore interno |

Alcuni errori con gestione automatica dedicata (es. `429` e `422` da
idempotency) espongono anche un `code` machine-readable: vedi
[Errori & deprecati](/docs/api-rest/errori) per il glossario completo.

<Callout type="info">
  Le rotte **legacy `/external/*`** (deprecate) usano un envelope storico diverso
  — `{ "success": false, "error": { "code", "message" } }`. Non costruire nuove
  integrazioni su quelle rotte: vedi la sezione sugli
  [endpoint deprecati](/docs/api-rest/errori).
</Callout>

## Paginazione e filtri

Gli endpoint che ritornano **liste** supportano paginazione e filtri tramite
**query parameter**. Le convenzioni più diffuse:

- **Paginazione**: i principali endpoint di lista (es. `/leads`, `/companies`,
  `/deals`, `/quotes`) accettano `page` e `pageSize`. Il `pageSize` ha un
  **massimo di 100**.
- **Filtri**: i filtri sono **specifici per risorsa** e si passano come query
  parameter — ad esempio `GET /pipelines?type=DEAL` per filtrare le pipeline per
  tipo, o `GET /document-templates?type=QUOTE` per i soli template di preventivo.

Esempio (prima pagina di lead, 50 per pagina):

<Tabs items={["curl", "JavaScript"]}>
<Tab value="curl">

```bash
curl "https://api.audin.ai/leads?page=1&pageSize=50" \
  -H "X-API-Key: $API_KEY"
```

</Tab>
<Tab value="JavaScript">

```js
const params = new URLSearchParams({ page: "1", pageSize: "50" });
const res = await fetch(`https://api.audin.ai/leads?${params}`, {
  headers: { "X-API-Key": process.env.AUDIN_API_KEY },
});
const leads = await res.json();
```

</Tab>
</Tabs>

<Callout type="warn">
  I parametri di paginazione **non sono uniformi su tutte le risorse**: alcuni
  endpoint di lista usano forme diverse (es. `limit`, oppure paginazione a
  cursore con `cursor`/`limit`). Prima di consumare un endpoint, **verifica i
  query parameter esatti e la shape della risposta sullo**
  [Swagger](https://api.audin.ai/docs/partners): è la fonte autorevole per ogni
  singola rotta.
</Callout>

## Header comuni

| Header | Direzione | Quando |
|--------|-----------|--------|
| `X-API-Key` | richiesta | sempre — autenticazione |
| `Content-Type: application/json` | richiesta | sui `POST`/`PUT`/`PATCH` con body |
| `Idempotency-Key` | richiesta | opzionale sui `POST` — vedi [Idempotency](/docs/api-rest/idempotency-e-rate-limit) |
| `X-RateLimit-*`, `Retry-After` | risposta | rate limit — vedi [Rate limit](/docs/api-rest/idempotency-e-rate-limit) |

## Prossimo passo

Vedi [Idempotency & rate limit](/docs/api-rest/idempotency-e-rate-limit) per
rendere le scritture ripetibili in sicurezza e gestire i limiti di traffico.