Panoramica

Le API REST di Askme Chat ti permettono di integrare la piattaforma nelle tue applicazioni, gestire conversazioni, operatori e automatizzare interazioni con i clienti.

URL Base

https://chat.askme.it

Ambiente di Test

Per testare le integrazioni senza impattare i dati di produzione, utilizza 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. Consulta la guida all'autenticazione per i dettagli.

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

Hai domande sulle API? Contattaci:

• 📧 [email protected]
• 💬 Tramite la chat di supporto Askme