Integrations - API's

L’API VOLAGIC consente ad altre applicazioni di recuperare informazioni da VOLAGIC. È quindi possibile ottenere informazioni sugli Assistenti, sugli Eventi, sui Turni e sugli Impieghi. Non è possibile modificare i dati tramite l’API.

Le API VOLAGIC consentono agli informatici e agli sviluppatori di recuperare dati da VOLAGIC e di elaborarli in base alle proprie esigenze. L’API è disponibile a partire dall’abbonamento Pro nell’amministrazione in «Organizzazione» – «API di integrazione». Tutti i contenuti di questa pagina sono destinati a professionisti e devono essere gestiti di conseguenza. VOLAGIC non si assume alcuna responsabilità per analisi errate dei dati dovute a un utilizzo improprio.

Chiave API

Per prima cosa dovete creare la chiave API. Per farlo, fate clic sul pulsante «Chiave API» e successivamente su «Aggiungi». Inserite quindi un nome e salvate. La chiave verrà visualizzata e potrete copiarla direttamente.

ATTENZIONE: la chiave API viene visualizzata SOLO immediatamente dopo la sua creazione. Conservatela in un luogo sicuro. La chiave API consente di accedere ai dati personali degli Assistenti e deve pertanto essere trattata in modo riservato!

Per le richieste, la chiave API deve essere trasmessa come X-API-KEY nell’header della richiesta. Per testare l’API, vi consigliamo di utilizzare uno strumento come Postman.

 

Chiamate API disponibili

Helpers: Assistenti

Il primo servizio vi consente di recuperare tutti gli Assistenti:

https://api.helfereinsatz.ch/v1/[percorso-della-vostra-organizzazione]/helpers/[no-pagina]

Riceverete un file JSON contenente tre voci al livello superiore:

  • pageNo: pagina attuale (vedi no-pagina)
  • pagesNum: numero totale di pagine → questa informazione è necessaria per recuperare tutti gli Assistenti tramite l’API
  • entries: un array contenente tutti gli Assistenti

Proprietà di entries (Assistente)

L’array degli Assistenti contiene i seguenti valori:

  • id: identificatore univoco dell’Assistente
  • firstName: nome
  • lastName: cognome
  • email: e-mail
  • phone: telefono
  • additionalEmail1: e-mail aggiuntiva 1
  • additionalEmail2: e-mail aggiuntiva 2
  • adminRemarks: note sull’Assistente
  • birthDate: data di nascita (formato YYYY-MM-DD)
  • infoFill: array per ciascun campo personalizzato creato
  • groups: array contenente tutti i Gruppi
  • stateCache: array contenente i valori dell’Assistente

Proprietà di infoFill

Ogni elemento infoFill contiene i seguenti valori:

  • label: nome del campo
  • value: variabile o array contenente i valori dell’Assistente per questo campo

Proprietà di groups

Ogni elemento groups contiene i seguenti valori:

  • id: identificatore univoco del Gruppo
  • name: nome del Gruppo

Proprietà di stateCache

L’array stateCache contiene i seguenti valori:

  • okAssignmentsNum: numero di Impieghi completati con successo
  • nokAssignmentsNum: numero di Impieghi mancati (accettati, ma l’Assistente non si è presentato)
  • confirmedAssignmentsNum: numero di Impieghi confermati (ovvero Impieghi che si svolgeranno in futuro)
  • reservedAssignmentsNum: con il double opt-in, numero di Impieghi che l’Assistente ha prenotato ma non ancora confermato
  • requestedValue: Valore target
  • plannedValue: okAssignmentsNum + confirmedAssignmentsNum
  • unconfirmedAssignmentsNum: con il double opt-in, numero di Impieghi che l’Assistente aveva prenotato ma non ha confermato entro il termine previsto

Attenzione: quando compare Num, il valore indica una quantità. Quando compare Value, indica il Valore di impiego. Se l’Assistente A svolge un Impiego per l’Assistente B, le quantità vengono conteggiate per l’Assistente A, mentre i Valori di impiego vengono accreditati all’Assistente B.

Eventi

Questo servizio vi consente di recuperare gli Eventi e i relativi Turni. Gli Impieghi non sono inclusi in questo servizio, poiché il volume di dati sarebbe troppo elevato.

https://api.helfereinsatz.ch/v1/[percorso-della-vostra-organizzazione]/events/[no-pagina]

Questo servizio restituisce un JSON con le seguenti proprietà al livello superiore:

  • id: identificatore univoco dell’Evento (necessario per il servizio degli Impieghi)
  • name: nome dell’Evento
  • date: data dell’Evento nel formato YYYY-MM-DD HH-MM-SS → non più rilevante (deprecato)
  • timeStart: data e ora di inizio dell’Evento nel formato YYYY-MM-DD HH-MM-SS
  • timeEnd: data e ora di fine dell’Evento nel formato YYYY-MM-DD HH-MM-SS
  • remarks: note sull’Evento
  • online: stato online dell’Evento
  • done: indica se l’Evento è stato elaborato. Durante l’elaborazione, tutti gli Impieghi vengono impostati sullo stato OK.
  • stateCache: valori dell’Evento memorizzati nella cache (vedi sotto)
  • category: Area dell’Evento (se disponibile)
  • shifts: Turni dell’Evento

Proprietà di stateCache dell’Evento

  • confirmedHelperAssignmentsNum: numero di Impieghi confermati (per Eventi futuri)
  • okHelperAssignmentsNum: numero di Impieghi completati con successo (per Eventi passati)
  • totalHelperAssignmentsNum: numero totale di Impieghi

Proprietà di category (Aree)

  • id: identificatore univoco dell’Area
  • name: nome dell’Area

Proprietà di shifts (Turni)

  • id: identificatore univoco del Turno
  • name: nome del Turno
  • startDateTime: data e ora di inizio del Turno nel formato YYYY-MM-DD HH-MM-SS
  • endDateTime: data e ora di fine del Turno nel formato YYYY-MM-DD HH-MM-SS
  • remarks: note sul Turno
  • stateCache: valori del Turno memorizzati nella cache

Proprietà di stateCache del Turno

  • confirmedHelperAssignmentsNum: numero di Impieghi confermati del Turno (per Eventi futuri)
  • okHelperAssignmentsNum: numero di Impieghi del Turno completati con successo (per Eventi passati)
  • totalHelperAssignmentsNum: numero totale di Impieghi
  • misfit: true se alcuni Assistenti hanno assunto Impieghi che non corrispondevano ai loro Gruppi

HelperAssignments: Impieghi di un Evento

Questo servizio vi consente di recuperare gli Impieghi di un Evento. È necessario l’ID dell’Evento che desiderate recuperare. Potete ottenere l’ID tramite l’endpoint Events.

 https://api.helfereinsatz.ch/v1/[percorso-della-vostra-organizzazione]/helperassignments/[id-evento]/[no-pagina]

Questo servizio restituisce un JSON con le seguenti proprietà:

  • pageNo: pagina attuale
  • pagesNum: numero totale di pagine di questo servizio
  • entries: Impieghi

entries (Impieghi)

  • id: identificatore univoco dell’Impiego
  • responsible: true se questo Assistente è responsabile dell’Impiego
  • remarks: note per la persona che assume questo Impiego
  • value: Valore di impiego
  • plannedValue: assume il valore di value se l’Impiego ha lo stato confirmed, reserved oppure ok
  • status: stato dell’Impiego → i possibili valori sono elencati di seguito
  • startDateTime: ora di inizio dell’Impiego
  • endDateTime: ora di fine dell’Impiego
  • hours: numero di ore dell’Impiego
  • role: Compito dell’Impiego
  • shift: proprietà del Turno
  • helper: se una persona ha già assunto l’Impiego, qui sono indicate le sue proprietà
  • helpAsHelper: se la persona che assume l’Impiego lo svolge per conto di un’altra persona, qui viene indicata la persona a cui viene accreditato l’Impiego
  • stateCache: valori dell’Impiego memorizzati nella cache

Valori di status

Lo stato di un Impiego può avere i seguenti valori:

  • open: Impiego disponibile
  • confirmed: un Assistente ha assunto l’Impiego
  • reserved: con il double opt-in, l’Impiego è considerato reserved non appena una persona lo ha assunto ma non lo ha ancora confermato
  • unconfirmed: con il double opt-in, un Impiego è considerato unconfirmed quando il periodo di prenotazione (24 ore) è scaduto
  • ok: l’Impiego è stato svolto
  • nok: l’Impiego non è stato svolto

Proprietà di role

  • id: identificatore univoco del Compito
  • name: nome del Compito

Proprietà di shift

Le proprietà del Turno sono le stesse del servizio Eventi e pertanto non vengono ripetute qui. Le trovate descritte sopra.

ATTENZIONE: le proprietà del Turno sono presenti in ogni Impiego. Se avete un Evento con 30 Impieghi distribuiti su 3 Turni da 10 Impieghi ciascuno, tutti i 10 Impieghi dello stesso Turno avranno le stesse proprietà shift!

Proprietà di helper e helpAsHelper

  • id: identificatore univoco dell’Assistente
  • firstName: nome dell’Assistente
  • lastName: cognome dell’Assistente
  • email: e-mail dell’Assistente
  • phone: numero di telefono dell’Assistente

Attenzione: se avete bisogno di maggiori informazioni sull’Assistente, dovete recuperarle tramite il servizio Helper!

Proprietà di stateCache dell’Impiego

  • misfit: true se l’Assistente assume un Impiego che NON corrisponde ai suoi Gruppi.