Hunext Visitatori espone un insieme di Web API pubbliche che permettono a sistemi esterni di interrogare e aggiornare i dati del gestionale senza passare dall’interfaccia utente.
Sono pensate per integrazioni applicative (comunicazione da programma a programma): chi chiama non è una persona che fa login, ma un’applicazione che si identifica con una propria coppia di credenziali. Per questo motivo un’integrazione non ha un utente e non ha un ruolo del gestionale: dispone solo delle credenziali che gli vengono rilasciate.
Per iniziare a utilizzarle servono tre passaggi.
1. Creare le credenziali dell’applicazione client
Le credenziali si creano dal gestionale, nella pagina Manutenzione › Altro › Client API. La voce è visibile ai soli utenti con ruolo Admin.
Nella pagina:
- Premere il pulsante di aggiunta nella barra degli strumenti della griglia.
- Compilare la Descrizione: serve a riconoscere l’integrazione (ad esempio il nome del sistema che si collegherà).
- Il client_id e il client_secret vengono generati automaticamente e non vanno scritti a mano.
- Copiare subito il client_secret e consegnarlo a chi realizza l’integrazione.
- Lasciare l’opzione Attivo selezionata e salvare.
⚠️ Il client_secret è visibile una sola volta. Dopo il salvataggio il sistema ne conserva solo una versione cifrata e non è più possibile rileggerlo: è una misura di sicurezza, non un limite tecnico. Se il valore viene perso, non va creato un nuovo client: si usa il comando Rigenera client_secret sulla riga corrispondente, che produce un nuovo segreto e mostra anch’esso una sola volta.
2. Recuperare il link della documentazione
Ogni installazione di Hunext Visitatori pubblica la documentazione delle proprie API a un indirizzo univoco, diverso da installazione a installazione.
Per ottenerlo, sempre dalla pagina Manutenzione › Altro › Client API, premere il pulsante con l’icona del mappamondo nella barra degli strumenti in alto. Si apre una finestra con l’indirizzo completo e un pulsante per copiarlo negli appunti.
L’indirizzo ha questa forma:
https://<indirizzo-del-portale>/<codice-installazione>/api/docs
Caratteristiche da conoscere e da comunicare a chi realizza l’integrazione:
- Non richiede autenticazione: si apre direttamente dal browser, senza fare login al gestionale.
- È in sola lettura. La pagina elenca gli endpoint disponibili, i parametri accettati e il formato delle risposte, ma non consente di eseguire chiamate di prova. Per provare le chiamate occorre un client HTTP esterno (ad esempio Postman).
- Va trattato come un’informazione riservata. L’indirizzo va condiviso solo con chi realizza l’integrazione.
3. Richiedere il token di accesso
Ogni chiamata alle API deve essere accompagnata da un token di accesso, che si ottiene presentando le credenziali del passaggio 1.
La chiamata
| Metodo | POST |
| Indirizzo | https://<indirizzo-del-portale>/api/token |
| Formato dei dati | application/x-www-form-urlencoded |
Parametri da inviare
| Parametro | Valore |
|---|---|
grant_type | client_credentials (valore fisso) |
client_id | il client_id generato al passaggio 1 |
client_secret | il client_secret generato al passaggio 1 |
Esempio di chiamata:
curl -X POST https://portale.azienda.it/api/token \
-d "grant_type=client_credentials" \
-d "client_id=a1b2c3....api.hxvms" \
-d "client_secret=IL_SEGRETO_RICEVUTO"
La risposta
{
"token_type": "bearer",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 1800
}
access_tokenè il token da utilizzare.expires_inindica per quanti secondi resta valido (1800 secondi, cioè 30 minuti, nella configurazione predefinita). Alla scadenza va semplicemente richiesto un nuovo token ripetendo la stessa chiamata: per le integrazioni non è previsto il refresh token.
Se le credenziali non sono corrette, oppure l’integrazione è stata revocata, la risposta è:
{
"error": "unauthorized",
"error_description": "Client credentials invalid or disabled."
}
Il messaggio è volutamente identico nei due casi e non rivela quale dei due si sia verificato.
Usare il token
Il token va inviato a ogni chiamata nell’intestazione Authorization, preceduto dalla parola Bearer e uno spazio:
curl https://portale.azienda.it/api/v1/<risorsa> \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
L’elenco delle risorse disponibili e dei relativi parametri è nella documentazione del passaggio 2.
Note conclusive
Indirizzi delle API. Gli endpoint contengono sempre il numero di versione (/api/v1/...). Una versione pubblicata resta stabile nel tempo: eventuali modifiche non compatibili vengono introdotte con una versione nuova, lasciando funzionare le integrazioni esistenti.
Esiti più frequenti.
| Codice | Significato | Cosa fare |
|---|---|---|
401 | token assente, scaduto o non valido | richiedere un nuovo token |
403 | token valido, ma l’integrazione non è abilitata a quell’operazione | verificare con l’amministratore le abilitazioni del client |
404 | la risorsa richiesta non esiste | controllare l’identificativo usato nella chiamata |
409 | l’operazione è in conflitto con un dato già presente | verificare i dati inviati |
Sempre in HTTPS. Le chiamate vanno indirizzate unicamente all’indirizzo https://.