Introduzione alle API

01Base URL e formato

Tutti gli endpoint stanno sotto il prefisso /api della tua istanza e parlano JSON:

https://crm.tuodominio.it/api

• Richieste con body: header Content-Type: application/json.
• Richieste autenticate: header Authorization: Bearer <accessToken> (vedi Autenticazione).
• Metodi: GET lettura, POST creazione e azioni, PATCH modifica parziale, DELETE eliminazione (soft delete sui record).

02Envelope delle risposte

Ogni risposta, di successo o di errore, usa lo stesso involucro. Successo:

{ "success": true, "data": … }

Le liste incapsulano righe e paginazione dentro data:

{
  "success": true,
  "data": {
    "items": [ … ],
    "pagination": { "limit": 50, "offset": 0, "count": 50, "sortBy": "id", "sortDir": "desc" }
  }
}

03Errori

Gli errori hanno sempre questa forma: details e requestId compaiono solo quando disponibili (il requestId è utile per correlare l'errore ai log del server):

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field \"name\" is required",
    "details": { … },
    "requestId": "…"
  }
}

Basa il branching su error.code e sullo stato HTTP. I più comuni: 401 UNAUTHORIZED, 403 FORBIDDEN, 404 NOT_FOUND (che copre anche il fuori-scope, per non rivelare l'esistenza), 422 VALIDATION_ERROR. Il catalogo completo dei codici, la struttura di details e la diagnostica via requestId sono in Errori e envelope.

04Paginazione e ordinamento

Tutte le liste accettano gli stessi parametri query: limit (default 50, massimo 200), offset, sort_by e sort_dir (asc/desc). Le colonne ordinabili le dichiara ogni modulo (una non ammessa → 422).

curl "https://crm.tuodominio.it/api/deals?limit=50&offset=50&sort_by=amount&sort_dir=desc" \
  -H "Authorization: Bearer <accessToken>"

Parametri, semantica di count e regole complete in Paginazione e filtri.

05Filtri avanzati

Le liste accettano il parametro advanced_filters: un array JSON (URL-encoded) di condizioni { column, op, value }, combinate in AND:

[
  { "column": "stage",  "op": "eq",       "value": "negotiation" },
  { "column": "amount", "op": "gte",      "value": 10000 }
]

Gli operatori dipendono dal tipo di colonna (testo, enum, numero, data); i limiti (25 condizioni, in fino a 200 valori, semantica di is_null) e la tabella completa degli operatori sono in Paginazione e filtri.

06Permessi e visibilità

Ogni richiesta è valutata dal motore dei permessi su tre assi, in base al ruolo dell'utente:

• Azione: read / create / update / delete / export / admin, per modulo.
• Scope: own (solo i propri record), team (i record del proprio team), all. Applicato direttamente nelle query: un record fuori scope risponde 404, come se non esistesse.
• Campo: permessi di lettura/scrittura per singolo campo: i campi non leggibili vengono omessi dalle risposte; scrivere un campo non scrivibile → 403 con l'elenco dei campi negati.

07Rate limiting

Le rotte di autenticazione (/auth/login, /auth/refresh, reset password, verifica MFA) hanno un limitatore per IP: contano solo i tentativi falliti (default: 10 in 15 minuti). In più, 5 login falliti consecutivi sullo stesso account lo bloccano temporaneamente (15 minuti). In entrambi i casi la risposta è 429 TOO_MANY_REQUESTS: gestiscila con attesa, non con retry immediati.