Web API Pubbliche

Le Web API pubbliche di Hunext Mensa permettono a sistemi esterni di integrarsi al gestionale senza passare per l’interfaccia utente.

Queste API lavorano solo su ruolo ‘Utente’. Le utenze amministrative — non sono visibili né modificabili da qui, nemmeno conoscendone l’identificativo.

Prima di iniziare: i codici esterni

A differenza di altri prodotti, Mensa richiede un passaggio preliminare di configurazione che va fatto dall’amministratore dell’impianto prima di consegnare le credenziali a chi integra.

Mense e aziende si indicano con il codice esterno, cioè il codice con cui quella mensa o quella azienda sono già note al gestionale del cliente.

Il campo è facoltativo nell’anagrafica, ma senza di esso l’integrazione non può funzionare: ogni richiesta che nomina una mensa o una azienda verrebbe rifiutata.

Cosa fare

Cosa Fare

  1. Concordare con l’utilizzatore i codici da usare: stringhe alfanumeriche parlanti dal consumer.
  2. In Anagrafiche › Mense aziendali, aprire ogni mensa coinvolta e compilare il campo Cod. Esterno.
  3. In Anagrafiche › Aziende, fare lo stesso su ogni azienda coinvolta.
  4. Comunicare l’elenco dei codici a chi realizza l’integrazione, insieme alle credenziali.
Cosa sapere

Cosa sapere

  • Il codice è univoco: non possono esistere due mense, o due aziende, con lo stesso codice. Al salvataggio il sistema lo verifica.

  • Modificarlo a posteriori interrompe senza alcun errore visibile dall’anagrafica: il sistema esterno continuerà a inviare il codice vecchio e si vedrà rifiutare le richieste. Se va cambiato, va cambiato su entrambi i lati e in modo concordato.

  • Vanno compilate solo le mense e le aziende che l’integrazione deve toccare. Le altre possono restare senza codice.

1 · Creare le credenziali dell’applicazione client

Le credenziali si generano nel gestionale, in Manutenzione › Client, voce riservata agli utenti con ruolo Amministratore.

  1. Premere il pulsante di aggiunta nella barra degli strumenti.
  2. Compilare la Descrizione: serve a riconoscere l’integrazione nell’elenco, conviene indicare il sistema che la userà.
  3. Compilare client_id e client_secret.
  4. Selezionare gli scope e, se serve, l’azienda — vedi la tabella qui sotto.
  5. Lasciare Attivo selezionato e salvare.

Il client_secret è visibile una sola volta. Dopo il salvataggio ne resta solo la versione cifrata. Copiarlo e consegnarlo prima di salvare; se va perso occorre rigenerarlo, e il valore precedente smette di funzionare.

Scope e azienda: quale combinazione scegliere

La combinazione determina cosa l’integrazione potrà fare. È la decisione più importante di questo passaggio.

Tipo di integrazioneScopeAzienda
Servizio esterno di una singola aziendaex. Gestione Utentiselezionata
Servizio esterno a livello di impiantoex. Gestione Utentilasciare vuota
Tablet self-serviceGestione Token—
Gateway Hunextnessunoselezionata

Dalla stessa pagina Manutenzione › Client, il pulsante con l’icona del mappamondo mostra l’indirizzo della documentazione tecnica di questo impianto, con il comando per copiarlo.

L’indirizzo ha questa forma:

https://<indirizzo-del-portale>/<codice-installazione>/api/docs

Il <codice-installazione> è diverso per ogni impianto. Caratteristiche da comunicare a chi integra:

  • non richiede autenticazione;
  • è in sola lettura: descrive le chiamate disponibili, non consente di eseguirle;
  • va trattato come informazione riservata, anche se non protegge l’accesso alle API: a farlo sono le credenziali.

3 · Richiedere il token di accesso

Ogni chiamata alle API deve portare un token, che l’integrazione ottiene dalle proprie credenziali.

La chiamata

  • Metodo: POST
  • Indirizzo: https://<indirizzo-del-portale>/api/v1/token
  • Formato: application/x-www-form-urlencoded

Parametri da inviare

ParametroValore
grant_typeclient_credentials (valore fisso)
client_idil client_id definito al passaggio 1
client_secretil client_secret definito al passaggio 1
curl -X POST https://portale.azienda.it/api/v1/token \
  -d "grant_type=client_credentials" \
  -d "client_id=IL_CLIENT_ID" \
  -d "client_secret=IL_SEGRETO_RICEVUTO"

La risposta

{
  "token_type": "bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 1800
}
  • access_token è il token da usare;
  • expires_in è la sua validità in secondi. Scaduto, se ne richiede un altro con la stessa chiamata: le credenziali non cambiano.

Se le credenziali non sono valide, oppure il client è stato disattivato:

{
  "error": "unauthorized",
  "error_description": "Credenziali client non valide o disabilitate."
}

Il messaggio è volutamente identico nei due casi: non si deve poter capire da fuori se un client esiste.

Usare il token

Va inviato nell’intestazione Authorization, preceduto da Bearer:

curl https://portale.azienda.it/api/v1/users \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Esiti più frequenti

CodiceSignificatoCosa verificare
400Dati della richiesta non validiLa risposta indica i campi in errore. Spesso è un codice mensa o azienda non compilato in anagrafica
401Token assente, scaduto o non validoRichiedere un token nuovo
403Token valido, operazione non abilitataControllare gli scope assegnati al client
404Entità non trovata o non disponibileVerificare l’identificativo e l’azienda associata al client
409Operazione in conflitto con un dato esistenteEx. Username o email già in uso; in cancellazione, dipendente con rendicontazioni associate

Avvertenze

Solo HTTPS. Le chiamate vanno indirizzate unicamente a https://.

Gli indirizzi contengono la versione (/api/v1/...). Finché l’integrazione resta su quella versione, il formato delle risposte non cambia in modo incompatibile.

Revocare un’integrazione. Disattivare o eliminare il client impedisce di ottenere nuovi token, ma quelli già emessi restano validi fino alla scadenza.

Related Articles