Open API

In ASAP, puoi utilizzare Open API per interagire con soluzioni di terzi. Open API funziona tramite HTTP e offre una serie di metodi di richiesta/risposta.

Le richieste API devono essere inviate al seguente indirizzo:

<URL del portale ASAP, utilizzato per interagire tramite Open API>/openapi/<versione API>/<richiesta>

Come ottenere l'URL di ASAP, utilizzato per interagire tramite l'API

Per ottenere un URL Open API di ASAP:

1. Accedi alla piattaforma web di ASAP.
2. Nella sezione Dashboard, fai clic sul pulsante Importazione e sincronizzazione, quindi apri la scheda Open API.
3. Il link per contattare ASAP tramite Open API si trova nella parte inferiore della finestra. Copialo e salvalo in una posizione comoda per te.

Come abilitare l'accesso tramite l'API e generare un token

Per autorizzare le richieste, queste devono essere firmate da un token creato sulla piattaforma ASAP. Solo gli amministratori dell'azienda possono creare token.

Per creare un token:

1. Accedi alla piattaforma web di ASAP.
2. Nella sezione Dashboard, fai clic sul pulsante Importazione e sincronizzazione, quindi apri la scheda Open API.
3. Fai clic sul pulsante Nuovo token.

   Viene visualizzata la finestra Ottieni token.

4. Copia il token e salvalo in una posizione comoda per te.

Il token non viene archiviato nel sistema ASAP con accesso pubblico. Dopo aver chiuso la finestra Ottieni token, non sarà disponibile per la visualizzazione. Se hai chiuso la finestra senza copiare il token, devi fare di nuovo clic su Nuovo token al fine di generare un nuovo token.

Il token emesso è valido per 12 mesi. Allo scadere di questo periodo, il token viene revocato. Il token emesso viene revocato anche se non viene utilizzato per 6 mesi.

Autorizzazione

Il token ottenuto su ASAP deve essere aggiunto alle intestazioni di tutte le richieste dell'API. L'intestazione deve essere simile alla seguente:

Formato della risposta

JSON è il formato predefinito per le risposte alle richieste dell'API.

Esempio di una chiamata CURL

Di seguito è riportata una richiesta API a https://domain.com/, che utilizza il metodo "GET openapi/v1/groups" (ottenere un elenco di gruppi). La richiesta viene autenticata utilizzando il token e8c699c05d495566a94bbb6841894153.

Metodi Open API di ASAP utilizzati per l'integrazione con i sistemi di gestione dell'apprendimento (LMS, Learning Management System)

Metodi di integrazione disponibili con i sistemi LMS:

1. /users/info: recupera un link personale al portale degli utenti.
2. /groups: recupera un elenco di gruppi disponibili per questa azienda.
3. /users: crea un utente e lo aggiunge al gruppo specificato.
4. /report: genera i dati dei rapporti sugli utenti che sono registrati sul portale e stanno completando la formazione sui programmi ASAP.
5. /user: apporta modifiche ai dati dell'utente. Trasferimento di un dipendente dell'azienda in un altro gruppo di formazione.

Ogni metodo supporta non più di 10 richieste al secondo (RPS, Requests Per Second).

Esempi di utilizzo di Open API

Esempio 1

Il metodo restituisce un errore o un link per consentire all'utente di accedere al portale degli utenti se l'utente ha già avviato la formazione.

Se viene restituito un link, dovrebbe essere mostrato all'utente e non vengono effettuate ulteriori chiamate al metodo.

In tutti gli altri casi viene restituito un errore con vari codici. L'elenco dei codici disponibili è descritto in Swagger come nella documentazione online.

Se viene ricevuto un errore "404 utente non trovato", viene richiamato il metodo n. 2

Qualsiasi errore con il codice 422 indica che il piano di studio è attualmente in fase di calcolo e il link sarà disponibile a breve. In caso contrario, devi contattare l'amministratore dell'account per il quale ASAP ha emesso il token API.

Esempio 2

A questo punto, otteniamo l'elenco dei gruppi a cui l'utente può aggiungersi. Dopo che il metodo riceve l'elenco, deve essere filtrato in modo da mostrare solo i gruppi per i quali il parametro isStarted ha il valore "true".

Solo in questi gruppi è iniziata la formazione e l'utente può unirsi solo a tali gruppi.

Se tali gruppi non sono presenti, viene restituito l'errore "404 gruppi non trovati". In questo caso, devi contattare l'amministratore dell'account per il quale ASAP ha emesso il token API.

Esempio 3

Dopo aver selezionato un gruppo, i dati personali e l'identificativo del gruppo vengono trasmessi al metodo n. 3 Il risultato è un errore o una risposta 201 con l'identificativo dell'utente aggiunto. In questo caso di errore, devi contattare l'amministratore dell'account per il quale ASAP ha emesso il token API.

Esempio 4

Per ricevere i dati del rapporto sulla formazione dei dipendenti:

1. Indirizzo email utilizzato per registrare l'utente.
2. Nome registrato dell'utente.
3. Nome e cognome registrati dell'utente.
4. Gruppo di formazione corrente dell'utente.
5. Durata della formazione in secondi.
6. Categoria di rendimento per il corso principale.
7. Categoria di rendimento per il corso rapido.
8. Stato attuale della formazione.
9. Avanzamento della formazione nel corso principale in percentuale nel formato xx.xx.
10. Avanzamento della formazione nel corso rapido in percentuale nel formato xx.xx.
11. Data prevista per il completamento del corso principale.
12. Data prevista di completamento del corso rapido.
13. Data di completamento del corso principale.
14. Data di completamento del corso principale.
15. Corsi di formazione e stato della formazione per il corso principale.
16. Corsi di formazione e stato della formazione per il corso rapido.
17. Data dell'ultima attività, in un formato che varia in base alla lingua di localizzazione dell'input.
18. Il numero totale di attestati ricevuti dall'utente durante la formazione.

Esempio 5

Per spostare gli utenti tra i gruppi e creare i dati del gruppo di formazione per ciascun dipendente dell'azienda:

1. Gruppo di formazione attuale.
2. Gruppo di formazione precedente.

Esempio 6

Eliminazione di un dipendente dal sistema ASAP.

Metodo "POST /openapi/v1/users/info"

Recupero di un link personale al portale degli utenti.

Richiesta

Intestazione:

• Autorizzazione: token API dell'azienda.

Corpo:

• email – una stringa: indirizzo email dell'utente. Deve essere indicato in lettere minuscole. Un input come AdMiN@DomAn.com produrrà un errore di convalida dell'input.

Risposta

link – una stringa: link personale al portale degli utenti.

Possibili errori

• 400 – common-validation: si è verificato un errore di convalida della richiesta.
• 401 - common-unauthorized: si è verificato un errore di autenticazione.
• 404 – user-not-found: non è stato trovato un utente con l'indirizzo email indicato.
• 422:
  • education-not-started: l'utente non ha iniziato la formazione.
  • processing-education: la formazione è iniziata; il piano di formazione è in fase di generazione.
• 429 – too-many-requests: è presente un numero eccessivo di richieste.

Metodo "GET /openapi/v1/groups"

Recupero dell'elenco di gruppi disponibili per questa azienda.

Richiesta

Intestazione:

• Autorizzazione: token API dell'azienda.

Risposta

• total – un numero: numero di gruppi disponibili nell'azienda.
• result – an array: un array di oggetti con dati sui gruppi disponibili.
  • id – una sequenza: identificativo del gruppo.
  • name – una sequenza: nome del gruppo.
  • isStarted – un boolean: indica se la formazione è iniziata nel gruppo.

Possibili errori:

• 401 - common-unauthorized: si è verificato un errore di autenticazione.
• 404 – groups-not-found: non sono stati trovati gruppi associati a questo token per l'azienda.
• 429 – too-many-requests: è presente un numero eccessivo di richieste.
• 500 – internal-server-error: si è verificato un errore del server interno.

Metodo "POST /openapi/v1/users"

Creazione di un utente aggiunto a un gruppo specificato.

Richiesta

Intestazione:

• Autorizzazione: token API dell'azienda.

Corpo:

• user – un oggetto: un oggetto che contiene informazioni personali sull'utente.
  • fullName – una stringa: nome e cognome dell'utente.
  • shortName – una stringa: nome dell'utente.
  • email – una stringa: indirizzo email dell'utente. Deve essere indicato in lettere minuscole. Un input come AdMiN@DomAn.com produrrà un errore di convalida dell'input.
• group – un oggetto: un oggetto con informazioni sul gruppo a cui verrà assegnato l'utente.
  • id – una sequenza: identificativo del gruppo.

Risposta

• user – un oggetto: un oggetto che contiene informazioni sull'utente creato.
  • id – una stringa: identificativo dell'utente.

Possibili errori:

• 400 – common-validation: si è verificato un errore di convalida della richiesta.
• 401 - common-unauthorized: si è verificato un errore di autenticazione.
• 402 – no-available-license: non sono disponibili licenze sufficienti per assegnare l'utente a un gruppo la cui formazione è iniziata.
• 404 – group-does-not-exists: questa azienda non ha un gruppo con l'identificativo indicato.
• 429 – too-many-requests: è presente un numero eccessivo di richieste.
• 409 – user-email-already-exists-in-company: questa azienda presenta già un utente con l'indirizzo email indicato.

Metodo "POST /openapi/v1/report"

Genera i dati dei rapporti sugli utenti che sono registrati sul portale e stanno completando la formazione sui programmi ASAP.

La dimensione dei dati trasmessi è descritta nel corpo della richiesta.

Richiesta

Intestazione:

• Autorizzazione: token API dell'azienda.

Corpo:

• lng – una sequenza: codice della lingua utilizzata per il rapporto. Una delle lingue di localizzazione disponibili nel formato ISO 639-1. Necessario. È indicato in lettere minuscole.

Mappatura tra la lingua del rapporto e il valore di lng:

• email – un array: indirizzo email dell'utente. Indicato per ottenere dati su un utente specifico. Opzionale.

  Requisiti sugli indirizzi indicati: 1) devono essere indicati in lettere minuscole, 2) devono contenere i simboli "@" e ".".

Risposta

JSON che contiene un array di dati su ciascun utente:

• id – una sequenza: ID assegnato al dipendente sulla piattaforma ASAP.
• email – una sequenza: indirizzo email usato per registrare l'utente.
• shortName – una sequenza: nome registrato dell'utente.
• fullName – una sequenza: nome e cognome registrato dell'utente.
• group – una sequenza: gruppo di formazione corrente dell'utente.
• educationTime – una sequenza: durata della formazione in secondi.
• mainEducationProgress – una sequenza: categoria di rendimento nel corso principale.
• expressEducationProgress – una sequenza: categoria di rendimento nel corso rapido.
• educationStatus – una sequenza: stato attuale della formazione.
• mainEducationProgressPercent – un float: avanzamento della formazione nel corso principale, espresso in percentuale nel formato xx.xx.
• expressEducationProgressPercent – un float: avanzamento della formazione nel corso rapido, espresso in percentuale nel formato xx.xx.
• mainEducationEndPlan – una data: data pianificata per il completamento del corso principale.
• expressEducationEndPlan – una data: data pianificata per il completamento del corso rapido.
• realMainEducationEnd – una data: data di completamento del corso principale.
• realExpressEducationEnd – una data: data di completamento del corso rapido.
• educationMainCourses – un array: corsi di formazione e stato della formazione nel corso principale.

  Formato della risposta:

  [

  {

  code,

  level,

  status,

  startedAt,

  finishedAt

  }

  ]

  in cui:

  • code è il nome del corso, che varia in base alla lingua di localizzazione.
  • level è il livello di formazione. Sono possibile i seguenti valori:
    • 1: "Principiante".
    • 2: "Elementare".
    • 3: "Intermedio".
    • 4: "Avanzato".
  • status è lo stato di formazione nel corso. Sono possibile i seguenti valori:
    • 0 – "Assegnato". Il corso può essere completato dal o dalla dipendente nell'ambito del suo attuale percorso formativo individuale. Il corso sarà disponibile dopo il completamento del modulo corrente o l'inizio della formazione.
    • 1 – "Completato". Il o la dipendente ha ricevuto un attestato di completamento.
    • 2 – "In corso". Il o la dipendente sta seguendo il corso come parte del suo attuale percorso formativo individuale.
  • startedAt: data e ora in cui il o la dipendente ha iniziato il modulo di formazione, espresse in formato ISO 8601: AAAA-MM-GGThh:mm:ss. Il formato della data (AAAA-MM-GG) varia in base alla lingua di input.
  • finishedAt: data e ora di completamento del modulo (per il quale è stato ricevuto un attestato), in formato ISO 8601: AAAA-MM-GGThh:mm:ss. Il formato della data (AAAA-MM-GG) varia in base alla lingua di input. Se mancano alcuni dati, viene restituito un valore vuoto.

  In assenza di dati, viene formato un array vuoto.

• educationMainCourses – un array: corsi di formazione e stato della formazione nel corso rapido.

  Formato della risposta:

  [

  {

  code,

  level,

  status,

  startedAt,

  finishedAt

  }

  ]

  in cui:

  • code è il nome del corso, che varia in base alla lingua di localizzazione.
  • level è il livello di formazione.
  • status è lo stato di formazione nel corso. Sono possibile i seguenti valori:
    • 0 – "Assegnato". Il corso può essere completato dal o dalla dipendente nell'ambito del suo attuale percorso formativo individuale.
    • 1 – "Completato".

    È in corso un controllo per determinare se i test sono abilitati per la formazione corrente. Se i test sono abilitati e il test per il modulo è stato superato, o se i test sono abilitati ed è presente una nota sul conseguimento di un'abilità, "status" è uguale a 1. Altrimenti, "status" è uguale a 0.

  • startedAt: data e ora in cui il o la dipendente ha iniziato il modulo di formazione, espresse in formato ISO 8601: AAAA-MM-GGThh:mm:ss. Il formato della data (AAAA-MM-GG) varia in base alla lingua di input.
  • finishedAt: data e ora di completamento del modulo (per il quale è stato ricevuto un attestato), in formato ISO 8601: AAAA-MM-GGThh:mm:ss. Il formato della data (AAAA-MM-GG) varia in base alla lingua di input. Se mancano alcuni dati, viene restituito un valore vuoto.

  In assenza di dati, viene formato un array vuoto.

• dateLastActive – una data: data dell'attività più recente, in un formato che varia in base alla lingua di localizzazione dell'input.
• certificatesReceived – un int: numero totale di attestati ricevuti dall'utente durante la formazione.

  Se l'utente non ha avviato la formazione o non ha ricevuto alcun attestato, viene restituito "0".

• phishingAttacks – un array: informazioni su un attacco di phishing durante la formazione sulla piattaforma ASAP.

  Formato della risposta:

  [

  {

  code: '''',

  level: '''', 

  startedAt: '''', 

  phishingAttackLetter: '''', 

  phishingAttackResult: '''',

  followPhishingLinkAt: ''" || null

  }

  ]

  in cui:

  • code è il nome dipendente dalle impostazioni locali del modulo di formazione che prevede l'invio di un'email di phishing.
  • level è il livello di formazione. Sono possibile i seguenti valori:
    • 1: "Principiante".
    • 2: "Elementare".
    • 3: "Intermedio".
    • 4: "Avanzato".

    Viene restituito un valore vuoto per le email di phishing inviate come parte di una campagna di phishing.

  • startedAt: data e ora in cui il o la dipendente ha iniziato il modulo di formazione, espresse in formato ISO 8601: AAAA-MM-GGThh:mm:ss. Il formato della data (AAAA-MM-GG) varia in base alla lingua di input.
  • phishingAttackLetter è il titolo dell'email di phishing. Quando le email di phishing vengono inviate utilizzando un modello, viene utilizzato il titolo inserito dall'amministratore. Il titolo varia in base alla lingua di localizzazione dell'input.
  • phishingAttackLetter è il risultato dell'attacco di phishing. Sono possibile i seguenti valori:
    • 0 – È stata inviata un'email di phishing. Al momento si attende una risposta da parte dell'utente.
    • 1 – L'utente ha evitato l'attacco di phishing.
    • 2 – L'utente ha abboccato all'attacco di phishing.
  • followPhishingLinkAt è la data e l'ora in cui è stato visitato il link di phishing. Viene generato solo per "phishingAttackResult": 2. Negli altri casi, viene restituito un valore vuoto.  

  In assenza di dati, viene formato un array vuoto.

Possibili errori:

• 200 – success: l'operazione è andata a buon fine.
• 401 – common-unauthorized: si è verificato un errore di autenticazione. 
• 404 – user not found: è stato inviato un indirizzo email non valido. 
• 400 – bad request: si è verificato un problema con la richiesta.
• 500 – internal-server-error: si è verificato un errore del server interno.

Metodo "PATCH /openapi/v1/user/:userId"

Apporta modifiche ai dati dell'utente. Trasferimento di un dipendente dell'azienda in un altro gruppo di formazione.

Richiesta

Intestazione:

• Autorizzazione: token API dell'azienda.

Parametro:

• userId – una sequenza: codice identificativo dell'utente specifico che viene spostato in un gruppo diverso.

  Deve soddisfare i seguenti criteri:

  • lunghezza massima di 24 caratteri
  • solo lettere minuscole

Corpo

Formato - JSON.

• groupId – una sequenza: ID del gruppo in cui verrà spostato il o la dipendente dell'azienda.

  Corrisponde all'ID del metodo "/openapi/v1/groups".

  L'ID deve soddisfare i seguenti criteri:

  • lunghezza massima di 24 caratteri
  • solo lettere minuscole
• fullName – una sequenza: nome e cognome del dipendente o della dipendente.
• shortName – una sequenza: nome del dipendente o della dipendente.
• email – una sequenza: indirizzo email del o della dipendente.

Risposta

JSON che contiene un array di dati su ciascun utente.

• userId – una sequenza: codice identificativo assegnato all'utente.
• currentGroup – un oggetto: un array di dati sul gruppo di utenti corrente.

  Nel seguente formato:

  {

  id,name

  }

  in cui:

  • id – una sequenza: chiave di identificazione del gruppo corrente.
  • name – una sequenza: nome del gruppo corrente.
• previousGroup – un oggetto: un array di dati sul gruppo di utenti precedente.

  Nel seguente formato:

  {

  id,name

  }

  in cui:

  • id: chiave di identificazione del gruppo precedente.
  • name: nome del gruppo precedente.
• currentFullName – una sequenza: nome e cognome correnti del dipendente o della dipendente.

  Il parametro viene generato solo se fullName è indicato nel JSON sorgente.

• previousFullName – una sequenza: nome e cognome precedenti del dipendente o della dipendente.

  Il parametro viene generato solo se fullName è indicato nel JSON sorgente.

• currentShortName – una sequenza: nome corrente del dipendente o della dipendente.

  Il parametro viene generato solo se shortName è indicato nel JSON sorgente.

• currentShortName – una sequenza: nome precedente del dipendente o della dipendente.

  Il parametro viene generato solo se shortName è indicato nel JSON sorgente.

• currentEmail – una sequenza: indirizzo email corrente del dipendente o della dipendente.

  Il parametro viene generato solo se e-mail è indicato nel JSON sorgente.

• previousEmail – una sequenza: indirizzo email precedente del dipendente o della dipendente.

  Il parametro viene generato solo se email è indicato nel JSON sorgente.

  Esempio di risposta: { userId : "1ab2457896abcc1234567891", "currentGroup" : {id" : "60e050803050c0704080a0e6", "name" : "Rischio ridotto"}, "previousGroup" : {id" : "61e151813151c1714181a1e6", "name" : "Rischio elevato"}, "currentFullName" : "Marvin John Mims", "previousFullName" : "Marvin Jon Mims", "currentShortName" : "Marvin Mims", "previousShortName" : "Marvin", "currentEmail" : "mims@mail.com", "previousEmail" : "johnmims@mail.com" }

Possibili errori:

• 200 – success: l'operazione è andata a buon fine.
• 400 – bad request: si è verificato un problema con la richiesta. Il cliente non deve ripetere la richiesta senza apportare modifiche.
• 400 – user-email-already-exists-in-company: l'indirizzo email specificato è già in uso presso l'azienda.
• 401 - common-unauthorized: si è verificato un errore di autenticazione.
• 402 – PAYMENT_REQUIRED: la licenza non è attiva.
• 403 – forbidden: il token non è autorizzato a utilizzare questo metodo.
• 404 – User not found: è stato trasmesso un indirizzo email non valido.
• 404 – Group not found: è stato trasmesso un ID del gruppo non valido. 
• 409 – Stato dell' utente non supportato per questa operazione: la richiesta non può essere eseguita; lo stato dell'utente non consente l'esecuzione dell'operazione.
• 409 – Il piano formativo dell'utente è in fase di calcolo: la richiesta non può essere eseguita perché il piano formativo è in fase di calcolo.
• 409 – cannot-join-group: il o la dipendente non può essere spostato nel gruppo.
• 500 – internal-server-error: si è verificato un errore del server interno.

Metodo "DELETE /openapi/v1/user/:userId"

Eliminazione di un dipendente dell'azienda.

Richiesta

Intestazione:

• Autorizzazione: token API dell'azienda.

Parametro:

• userId – una sequenza: codice identificativo dell'utente specifico che viene spostato in un gruppo diverso.

  Deve soddisfare i seguenti criteri:

  • lunghezza massima di 24 caratteri
  • solo lettere minuscole

Possibili errori

• 401 - common-unauthorized: si è verificato un errore di autenticazione.
• 500 – internal-server-error: si è verificato un errore del server interno.

In alto