Integrations - API's

L’API VOLAGIC permet à d’autres applications de récupérer des informations depuis VOLAGIC. Il est ainsi possible d’obtenir des informations sur les Auxiliaires, les Evénements, les Tours et les Missions. Il n’est pas possible de modifier les données via l’API.

Les API VOLAGIC permettent aux informaticiens et aux développeurs de récupérer des données depuis VOLAGIC et de les traiter selon leurs propres besoins. L’API est disponible à partir de l’abonnement Pro dans l’administration sous «Organisation» – «API d’intégration». Tous les contenus de cette page sont destinés à des professionnels et doivent être traités en conséquence. VOLAGIC décline toute responsabilité en cas d’analyse erronée des données résultant d’une utilisation incorrecte.

Clé API

Vous devez tout d’abord créer la clé API. Pour cela, cliquez sur le bouton «Clé API», puis sur «Ajouter». Saisissez ensuite un nom et enregistrez. La clé s’affiche alors et vous pouvez la copier directement.

ATTENTION: la clé API est affichée UNIQUEMENT juste après sa création. Conservez-la dans un endroit sûr. La clé API permet d’accéder aux données personnelles des Auxiliaires et doit donc être traitée de manière confidentielle!

Lors des requêtes, la clé API doit être transmise en tant que X-API-KEY dans l’en-tête de la requête. Pour tester l’API, nous vous recommandons d’utiliser un outil tel que Postman.

 

Appels API disponibles

Auxiliaires

Le premier service vous permet de récupérer tous les Auxiliaires:

https://api.helfereinsatz.ch/v1/[ chemin-de-votre-organisation ]/helpers/[no-page]

Vous recevez un fichier JSON contenant trois entrées au niveau supérieur:

  • pageNo: page actuelle (voir no-page)
  • pagesNum: nombre total de pages --> cette information est nécessaire pour récupérer tous les Auxiliaires via l’API
  • entries: un tableau contenant tous les Auxiliaires

entries ( Auxiliaire ) Propriétés

Le tableau des Auxiliaires contient les valeurs suivantes:

  • id: Unique Identifier de l’Auxiliaire
  • firstName: prénom
  • lastName: nom
  • email: E-Mail
  • phone: téléphone
  • additionalEmail1: e-mail supplémentaire 1
  • additionalEmail2: e-mail supplémentaire 2
  • adminRemarks: remarques concernant l’Auxiliaire
  • birthDate: date de naissance (format YYYY-MM-DD)
  • infoFill: tableau pour chacun des champs personnalisés que vous avez créés
  • groups: tableau contenant tous les Groupes
  • stateCache: tableau contenant les valeurs de l’Auxiliaire

Propriétés de infoFill

Chaque élément infoFill contient les valeurs suivantes:

  • label: nom du champ
  • value: variable ou tableau contenant les valeurs de l’Auxiliaire pour ce champ

Propriétés de groups

Chaque élément groups contient les valeurs suivantes:

  • id: Unique Identifier du Groupe
  • name: nom du Groupe

Propriétés de stateCache

Le tableau stateCache contient les valeurs suivantes

  • okAssignmentsNum: nombre de Missions effectuées avec succès
  • nokAssignmentsNum: nombre de Missions manquées (acceptées, mais l’Auxiliaire était absent)
  • confirmedAssignmentsNum: nombre de Missions confirmées (c’est-à-dire des Missions qui auront lieu à l’avenir)
  • reservedAssignmentsNum: avec le double opt-in, nombre de Missions que l’Auxiliaire a réservées mais pas encore confirmées
  • requestedValue: Objectif
  • plannedValue: okAssignmentsNum + confirmedAssignemntsNum 
  • unconfirmedAssignmentsNum: avec le double opt-in, nombre de Missions que l’Auxiliaire avait réservées, mais qu’il n’a pas confirmées dans le délai imparti

Attention : lorsque Num apparaît, la valeur correspond à un nombre. Lorsque Value apparaît, elle correspond à la Valeur de la mission. Si l’Auxiliaire A effectue une Mission pour l’Auxiliaire B, les nombres sont comptabilisés pour l’Auxiliaire A, tandis que les Valeurs de la mission sont créditées à l’Auxiliaire B.

Evénements

Ce service vous permet de récupérer les Evénements et leurs Tours. Les Missions ne sont pas incluses dans ce service, car le volume de données serait trop important.

https://api.helfereinsatz.ch/v1/[chemin-de-votre-organisation]/events/[no-page]

Ce service renvoie un JSON contenant les propriétés suivantes au niveau supérieur:

  • id: unique Identifier de l’Evènement (nécessaire pour le service des Missions)
  • name: nom de l’Evènement
  • date: date de l’Evènement au format YYYY-MM-DD HH-MM-SS → n’est plus pertinente (obsolète)
  • timeStart: date et heure de début de l’Evènement au format YYYY-MM-DD HH-MM-SS
  • timeEnd: date et heure de fin de l’Evènement au format YYYY-MM-DD HH-MM-SS
  • remarks: remarques concernant l’Evènement
  • online: statut en ligne de l’Evènement
  • done: indique si l’Evènement a été traité. Lors du traitement, toutes les Missions passent au statut OK.
  • stateCache: valeurs mises en cache de l’Evènement (voir ci-dessous)
  • category: Domaine de l’Evènement (si disponible)
  • shifts: Tours de l’Evènement

Propriétés de stateCache de l’Evènement

  • confirmedHelperAssignmentsNum: nombre de Missions confirmées (pour les Evénements futurs)
  • okHelperAssignmentsNum: nombre de Missions effectuées avec succès (pour les Evénements passés)
  • totalHelperAssignmentsNum: nombre total de Missions

Propriétés de category (Domaines)

  • id: unique Identifier du Domaine
  • name: nom du Domaine

Propriétés de shifts (Tours)

  • id: unique Identifier du Tour
  • name: nom du Tour
  • startDateTime: date et heure de début du Tour au format YYYY-MM-DD HH-MM-SS
  • endDateTime: date et heure de fin du Tour au format YYYY-MM-DD HH-MM-SS
  • remarks: remarques concernant le Tour
  • stateCache: valeurs mises en cache du Tour

Propriétés de stateCache du Tour

  • confirmedHelperAssignmentsNum: nombre de Missions confirmées du Tour (pour les Evénements futurs)
  • okHelperAssignmentsNum: nombre de Missions du Tour effectuées avec succès (pour les Evénements passés)
  • totalHelperAssignmentsNum: nombre total de Missions
  • misfit: true si des Auxiliaires ont accepté des Missions qui ne correspondaient pas à leurs Groupes

HelperAssignements: Missions d’un Evènement

Ce service vous permet de récupérer les Missions d’un Evènement. Vous avez besoin de l’ID de l’Evènement que vous souhaitez récupérer. Vous pouvez obtenir cet ID via l’endpoint Events.

https://api.helfereinsatz.ch/v1/[chemin-de-votre-organisation]/helperassignments/[id-evenement]/[no-page]

Ce service renvoie un JSON contenant les propriétés suivantes:

  • pageNo: page actuelle
  • pagesNum: nombre total de pages de ce service
  • entries: Missions

entries (Missions)

  • id: unique Identifier de la Mission
  • responsible: true, si cet Auxiliaire est responsable de la Mission
  • remarks: remarques destinées à la personne qui accepte cette Mission
  • value: Valeur de la mission
  • plannedValue: reprend la valeur de value si la Mission a le statut confirmed, reserved ou ok
  • status: statut de la Mission → les valeurs possibles sont indiquées ci-dessous
  • startDateTime: heure de début de la Mission
  • endDateTime: heure de fin de la Mission
  • hours: nombre d’heures de la Mission
  • role: Fonction de la Mission
  • shift: propriétés du Tour
  • helper: si une personne a déjà accepté la Mission, ses propriétés sont indiquées ici
  • helpAsHelper: si la personne qui accepte la Mission l’effectue pour quelqu’un d’autre, la personne à laquelle la Mission est créditée est indiquée ici
  • stateCache: valeurs mises en cache de la Mission

Valeurs de status

Le statut d’une Mission peut avoir les valeurs suivantes :

  • open: Mission ouverte
  • confirmed: un Auxiliaire a accepté la Mission
  • reserved: avec le double opt-in, la Mission est considérée comme reserved dès qu’une personne l’a acceptée mais ne l’a pas encore confirmée
  • unconfirmed: avec le double opt-in, une Mission est considérée comme unconfirmed lorsque le délai de réservation (24 heures) a expiré
  • ok: la Mission a été effectuée
  • nok: la Mission n’a pas été effectuée

Propriétés de role

  • id: unique Identifier de la Fonction
  • name: nom de la Fonction

Propriétés de shift

Les propriétés du Tour sont identiques à celles du service Evènements. Elles ne sont donc pas répétées ici. Vous les trouverez décrites ci-dessus.

ATTENTION: les propriétés du Tour sont présentes sur chaque Mission. Si vous avez un Evènement comprenant 30 Missions réparties sur 3 Tours de 10 Missions chacun, les 10 Missions d’un même Tour auront toutes les mêmes propriétés shift!

Propriétés de helper et helpAsHelper

  • id: unique Identifier de l’Auxiliaire
  • firstName: prénom de l’Auxiliaire
  • lastName: nom de l’Auxiliaire
  • email: e-mail de l’Auxiliaire
  • phone: numéro de téléphone de l’Auxiliaire

Attention : si vous avez besoin de plus d’informations sur l’Auxiliaire, vous devez les récupérer via le service Helper!

Propriétés de stateCache de la Mission

  • misfit: true, si l’Auxiliaire accepte une Mission qui ne correspond PAS à ses Groupes