Formato risposte & convenzioni

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.

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}):

{
  "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.

Formato degli errori

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

{
  "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 per il glossario completo.

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.

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):

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

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();

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: è la fonte autorevole per ogni singola rotta.

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
`X-RateLimit-*`, `Retry-After`	risposta	rate limit — vedi Rate limit

Prossimo passo

Vedi Idempotency & rate limit per rendere le scritture ripetibili in sicurezza e gestire i limiti di traffico.