Panoramica
Le API REST di Askme Chat consentono di integrare la piattaforma nelle applicazioni dei clienti, gestire conversazioni e operatori e automatizzare le interazioni con gli utenti finali.
Questa sezione documenta le API di Askme Chat, incluso il gruppo /api/ai/... (vedi Endpoints): si tratta di un livello interno legacy, mantenuto per compatibilità. Per integrare le funzionalità di intelligenza artificiale (agenti, chat con RAG, knowledge base, analisi) in una nuova integrazione, utilizzare le API di Askme AI (/api/v2, autenticazione con API key dedicata): vedere Panoramica API di Askme AI.
URL Base
https://chat.askme.it
Per testare le integrazioni senza impattare i dati di produzione, è disponibile l'ambiente sandbox fornito dal team Askme.
Autenticazione
Le API supportano due modalità di autenticazione:
Token API (X-AskmeToken)
Per le chiamate server-to-server, utilizza il token API tramite header:
X-AskmeToken: {api_token}
Il token può essere generato dalla sezione Amministrazione → API Keys dell'interfaccia Askme Chat.
OAuth 2.0 (Bearer Token)
Per integrazioni avanzate, è disponibile il flusso OAuth 2.0 Client Credentials tramite Keycloak. Per i dettagli, vedere la guida all'autenticazione.
Authorization: Bearer {access_token}
Codici di Stato HTTP
| Codice | Descrizione |
|---|---|
200 | Richiesta completata con successo |
201 | Risorsa creata con successo |
204 | Richiesta completata, nessun contenuto da restituire |
400 | Richiesta non valida (parametri mancanti o errati) |
401 | Autenticazione fallita o token non valido |
403 | Accesso negato (permessi insufficienti) |
404 | Risorsa non trovata |
429 | Troppe richieste (rate limit superato) |
500 | Errore interno del server |
503 | Servizio temporaneamente non disponibile |
Paginazione
Gli endpoint che restituiscono liste utilizzano la paginazione Spring. Parametri disponibili:
| Parametro | Tipo | Default | Descrizione |
|---|---|---|---|
page | integer | 0 | Numero della pagina (0-based) |
size | integer | 20 | Elementi per pagina |
Esempio di Risposta Paginata
{
"content": [...],
"totalElements": 150,
"number": 0,
"size": 20,
"totalPages": 8
}
Rate Limiting
Le API hanno dei limiti di utilizzo per garantire la stabilità del servizio. Quando superi il limite, riceverai un errore 429 Too Many Requests.
Headers nelle risposte:
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 285
X-RateLimit-Reset: 1639224600
Formato Risposte
- Le risposte sono in formato JSON
- I timestamp sono in formato ISO 8601 UTC (es.
2025-01-15T10:30:00Z) - Gli array in query string si passano come parametri multipli (es.
?users=1&users=2)
Client HTTP Consigliati
- cURL: Per test rapidi da terminale
- Postman/Insomnia: Per testing e debugging interattivo
- Axios/Fetch: Per JavaScript/Node.js
- Requests: Per Python
- HttpClient: Per Java/.NET
Risorse
- Autenticazione — Come autenticarti alle API
- Endpoints — Lista completa degli endpoint disponibili
Supporto
Per domande sulle API, è possibile contattare il supporto Askme:
- [email protected]
- Tramite la chat di supporto Askme