Aperçu

La carte APIs & webhooks de la section Intégrations & Applis ouvre la console développeur de Vome. C'est l'outil à utiliser quand vous voulez construire quelque chose sur mesure, plutôt que de passer par un connecteur déjà prêt.

Il y a deux volets, et la plupart des projets utilisent les deux.

• L'API, c'est vous qui demandez des données à Vome, ou qui en envoyez. Vous faites l'appel, Vome répond.

• Les webhooks, c'est Vome qui vous prévient au moment où quelque chose se produit, pour que votre système n'ait pas à vérifier sans arrêt.

Les APIs et les webhooks sont offerts avec le forfait Ultime.

Pourquoi les utiliser

• Envoyer les données de Vome vers des systèmes que nous ne connectons pas directement. Un entrepôt de données, un système financier, un intranet maison, un tableau de bord interne.

• Garder un autre système à jour sans que personne ne ressaisisse quoi que ce soit. Un webhook se déclenche dès qu'un profil est créé ou qu'un quart est réservé.

• Automatiser un travail qui traverse plusieurs outils. La même clé API alimente les connecteurs Zapier et Microsoft Power Automate, vous pouvez donc commencer sans code et passer au sur-mesure plus tard sans changer d'identifiants.

• Produire vos rapports à votre façon. Récupérez les profils, les réservations, les quarts et les soumissions de formulaire dans l'outil d'analyse que votre organisation utilise déjà.

Où le trouver dans Vome

Dans la barre de navigation de gauche, cliquez sur Intégrations & Applis, puis sur APIs & webhooks. La console développeur s'ouvre, avec quatre onglets :

• Clés API, où vous générez et révoquez les clés secrètes qui authentifient vos requêtes.

• Webhook, où vous enregistrez les points finaux que Vome doit notifier et choisissez les événements qu'ils reçoivent.

• Evénements, l'historique des événements produits par votre compte.

• Journaux, où vous voyez ce que Vome a envoyé, ce que votre point final a répondu, et pourquoi une livraison a échoué.

Ce que l'API couvre

C'est une API REST avec des réponses JSON, servie depuis https://api.vomevolunteer.com en HTTPS.

Il y a huit ressources. La plupart offrent les trois mêmes lectures : les lister, en récupérer une par son id, et les rechercher avec des filtres. Certaines acceptent aussi l'écriture. Chaque entrée ci-dessous précise exactement quels appels existent, ce que l'objet contient réellement, et ce qu'on en construit le plus souvent.

Comment les objets s'articulent

La plupart de ces objets se rattachent à une seule hiérarchie. Il vaut la peine de la lire avant de choisir un point de terminaison :

catégorie → opportunité → quart → réservation

Une catégorie regroupe des activités liées, par exemple Banque alimentaire. Une opportunité est un rôle ou un programme à l'intérieur de cette catégorie, par exemple Mentor de fin de semaine. Un quart est un bloc de temps daté sur cette opportunité, par exemple samedi de 9 h à 12 h avec 8 places. Une réservation est une personne inscrite à un quart. Les catégories n'ont pas de point de terminaison propre : elles arrivent imbriquées dans l'objet opportunité.

L'accueil et la sélection fonctionnent sur une paire parallèle. Une séquence est le modèle, et une séquence d'utilisateur est le parcours d'une personne dans ce modèle.

Profils

Le dossier d'une personne dans votre base de données.

Il en existe deux types et l'API renvoie les deux. Un utilisateur Vome possède un compte et se connecte. Un profil hors ligne est un dossier que votre organisation tient pour une personne qui ne se connecte jamais. L'indicateur is_offline permet de les distinguer.

Un profil porte les données d'identité et de contact (nom, courriel, téléphone, date de naissance, genre, occupation, établissement, compétences, langues, adresse et coordonnées géographiques), un contact d'urgence, des renseignements médicaux facultatifs, le total des logged_hours à vie, un compte de completed_shifts, les opportunités auxquelles la personne est affectée, les tags de profil appliqués par vos admins, et tous les champs personnalisés définis par votre organisation.

Lectures : lister, récupérer, rechercher, plus un appel distinct qui liste tous les champs de profil de votre compte. Écritures : création, mise à jour et upsert.

Ce qu'on en construit : un upsert nocturne depuis un système de RH ou de gestion des membres, pour qu'une personne inscrite là-bas apparaisse dans Vome sans être saisie deux fois. Appelez d'abord le point de terminaison des champs de profil pour découvrir les identifiants de vos champs personnalisés : ce sont des UUID propres à votre compte.

Opportunités

Le rôle ou le programme auquel les quarts appartiennent.

Une opportunité est ce à quoi une personne s'inscrit. Elle porte le titre, la description, le statut, la date de création, sa catégorie parente, et une URL de partage publique dès qu'elle est publiée. Une opportunité compte généralement plusieurs quarts.

Lectures : lister, récupérer, rechercher. Écritures : affecter des utilisateurs à des opportunités.

Ce qu'on en construit : publier vos opportunités actives sur votre propre site web à partir de l'URL de partage, au lieu d'entretenir une deuxième liste à la main.

Attention : le chemin vers une opportunité unique est /api/opportunities/{opportunity_role_id}/. Ce paramètre s'appelle opportunity_role_id pour des raisons historiques, mais la valeur attendue est bien l'id de l'opportunité. Vome a retiré le mot « role » de son vocabulaire produit il y a un moment, et le chemin de l'API n'a pas suivi.

Quarts

Un seul bloc de temps daté dans lequel on peut inscrire des personnes.

Un quart appartient à exactement une opportunité, et une opportunité peut en compter plusieurs. Il porte le titre, la description, les heures de début et de fin, la capacité, son opportunité parente, un lieu déduit, et une URL de partage publique. C'est la capacité qui vous dit s'il reste de la place.

Lectures : lister, récupérer, rechercher. Écritures : affecter des utilisateurs à des quarts.

Ce qu'on en construit : reproduire les quarts de la semaine à venir dans un calendrier d'équipe ou sur un écran d'affichage, ou inscrire une personne à un quart depuis un autre système dès qu'elle y est approuvée.

Réservations

La place d'une personne sur un quart.

Si le quart est la place à pourvoir, la réservation est l'inscription qui s'y rattache : un quart porte donc plusieurs réservations, une par personne. C'est là que vivent réellement la présence et les heures, ce qui en fait l'objet que visent la plupart des intégrations de production de rapports.

Elle porte un status qui parcourt tout le cycle de vie (demande de quart en attente, réservé, demande de quart refusée, présence confirmée, absent, arrivée enregistrée, heures consignées, réclamation d'heures en attente, annulé), un arrival_time et un departure_time, les logged_hours qui en résultent, et la personne qui a approuvé ces heures (vide quand c'est une sortie par code QR qui l'a fait). Elle imbrique aussi le quart, la personne et l'opportunité : un seul enregistrement de réservation répond donc à qui a fait quoi, quand, et pendant combien de temps.

Lecture seule. Lister, récupérer, rechercher.

Ce qu'on en construit : extraire les réservations du mois dernier arrivées à l'état heures consignées, et pousser les totaux vers un rapport de subvention, un système financier ou un entrepôt de données.

Séquences

Une liste ordonnée et réutilisable d'étapes d'accueil ou de sélection.

Une séquence est un modèle, pas la progression de quelqu'un. Elle porte le titre, la description, le statut, la visibilité, et un tableau ordonné d'étapes, où chaque étape a une position, un type et ses propres détails. L'étape est l'unité qui représente une exigence : un formulaire à remplir, une décharge à signer, un document à lire, une formation à terminer, une entrevue à passer.

Lectures : lister, récupérer, rechercher. Écritures : affecter des utilisateurs à des séquences.

Ce qu'on en construit : lire une fois la structure de vos séquences pour bâtir les étapes correspondantes dans votre propre outil de suivi, puis affecter automatiquement une personne à la bonne séquence dès qu'elle franchit une étape ailleurs.

Séquences d'utilisateur

La progression d'une personne dans une séquence.

Affecter quelqu'un à une séquence crée une séquence d'utilisateur, et c'est cet objet qu'il faut lire pour suivre la progression. L'inscription elle-même a un status parmi Active, En pause, Inactive ou Terminée, plus des horodatages indiquant quand la personne a été ajoutée et quand quelque chose a changé pour la dernière fois.

À l'intérieur, chaque étape rapporte son propre état : Ajoutée ou Terminée, la date d'achèvement, une date d'expiration s'il y en a une, et si un fichier y a été téléversé. C'est ce détail par étape qui vous permet de répondre « cette personne est-elle autorisée à travailler ? », et pas seulement « a-t-elle commencé ? ».

Lecture seule. Lister, récupérer, rechercher.

Ce qu'on en construit : bloquer la planification dans votre propre système jusqu'à ce que la séquence de sélection d'une personne soit Terminée, ou relancer la seule étape encore en attente.

Soumissions de formulaire

Une réponse complète à l'un de vos formulaires.

Une soumission est créée quand une personne envoie un formulaire que vous avez bâti dans Vome, et elle capture bien plus que les réponses. Outre l'id et le titre du formulaire, le dossier où il se trouve, l'horodatage de l'envoi et un submission_status (Nouveau, En révision, Révisé, Rejeté ou Terminé), elle contient le tableau questions complet : chaque question posée, la réponse de la personne, le type de réponse, et si elle a répondu ou non.

Elle porte aussi tout ce que le formulaire a recueilli autour des réponses : les renseignements médicaux et le contact d'urgence, le consentement numérique et la façon dont il a été donné (saisi, téléversé, ou non fourni), la disponibilité générale par jour et par moment de la journée, les pièces jointes, l'opportunité d'où venait la personne, les quarts qu'elle a demandés, et les sites et catégories rattachés à la soumission.

Lecture seule. Lister, récupérer, rechercher.

Ce qu'on en construit : acheminer chaque nouvelle candidature vers un CRM ou un processus d'approbation dès son arrivée, en emportant la trace du consentement et les pièces jointes.

Sites

Un lieu ou une succursale dans une organisation multi-sites.

Un site est un lieu sous l'égide de votre organisation. La plupart des organisations s'en servent pour une succursale, un campus, une section ou une région. Chacun porte un nom, une description, une adresse, un courriel général, un téléphone général et un site web. Les personnes sont rattachées aux sites par appartenance, et l'API gère cette appartenance directement.

Lectures : lister, récupérer. Il n'y a pas de point de terminaison de recherche pour les sites. Écritures : créer des sites en lot, affecter des personnes à des sites, et retirer des personnes de sites.

Ce qu'on en construit : créer toute votre liste de succursales en un seul appel à la configuration, puis garder l'appartenance aux sites alignée sur votre fournisseur d'identité ou votre système de RH à mesure que les personnes changent de lieu.

Les événements que les webhooks peuvent envoyer

Quand vous créez un point final de webhook, vous choisissez les événements qu'il doit recevoir. Ils sont regroupés en quatre familles :

• Profils

• Réservations

• Formulaires remplissables

• Séquences

Un même point final peut s'abonner à plusieurs familles, ou vous pouvez en créer un par usage.

Comment générer une clé API

1. Dans la barre de navigation de gauche, cliquez sur Intégrations & Applis.

2. Cliquez sur APIs & webhooks.

3. Ouvrez l'onglet Clés API et cliquez sur Générer une clé secrète.

4. Donnez-lui un titre parlant, pour savoir plus tard quel système s'en sert.

5. Copiez la clé et rangez-la en lieu sûr.

La clé n'est affichée qu'une seule fois. Si vous la perdez, impossible de la retrouver : vous en générez une nouvelle et mettez à jour ce qui utilisait l'ancienne. Ne collez jamais une clé dans du code côté client ni dans un dépôt public.

Envoyez la clé à chaque requête dans l'en-tête API-KEY.

Comment créer un point final de webhook

1. Dans la console développeur, ouvrez l'onglet Webhook.

2. Créez un point final de webhook.

3. Saisissez l'URL du point final. Ce doit être une URL en service, capable de recevoir la requête, et non une adresse que vous comptez construire plus tard.

4. Ajoutez une courte description, pour que l'usage du point final soit évident à la prochaine personne qui le consultera.

5. Sélectionnez les événements à recevoir, parmi Profils, Réservations, Formulaires remplissables et Séquences.

6. Enregistrez le point final.

Une fois en service, servez-vous de l'onglet Journaux pour confirmer que les livraisons aboutissent. Un échec vous dit tout de suite si le problème vient de Vome ou de votre point final.

Documentation développeur

La référence technique complète se trouve sur le site de documentation développeur de Vome, distinct de ce centre d'aide. Elle est en anglais. Commencez ici :

• Introduction et démarrage rapide : https://docs.vomevolunteer.com/getting-started/quickstart

• Authentification : https://docs.vomevolunteer.com/getting-started/publish-your-docs

• Erreurs : https://docs.vomevolunteer.com/getting-started/errors

• Pagination : https://docs.vomevolunteer.com/getting-started/pagination

Chaque ressource a sa propre référence d'objet et sa liste de points de terminaison sur le même site, et les guides de connecteur pour Zapier, Microsoft Power Automate et Salesforce se trouvent sous Integrations and Automations : https://docs.vomevolunteer.com

Besoin d'aide ?

Si vous bloquez sur une requête ou sur la livraison d'un webhook, écrivez à notre équipe de support depuis https://support.vomevolunteer.com/. Indiquez le point de terminaison appelé et, si possible, l'entrée correspondante de l'onglet Journaux.

Résumé

• Les APIs et les webhooks font partie du forfait Ultime, sous Intégrations & Applis.

• Huit ressources sont accessibles : profils, opportunités, quarts, réservations, séquences, séquences d'utilisateur, soumissions de formulaire et sites.

• La lecture est offerte sur les huit. L'écriture couvre la création et la mise à jour de profils, la création de sites, et l'affectation de personnes à des opportunités, des quarts, des séquences et des sites.

• Les réservations, les séquences d'utilisateur et les soumissions de formulaire sont en lecture seule, et c'est là que vivent la présence, la progression de sélection et les réponses aux candidatures.

• Les webhooks poussent les événements Profils, Réservations, Formulaires remplissables et Séquences vers une URL qui vous appartient.

• Générez la clé dans l'onglet Clés API, copiez-la immédiatement, et envoyez-la dans l'en-tête API-KEY.

• L'onglet Journaux est l'endroit où diagnostiquer un webhook qui n'arrive pas.

• La référence complète est sur docs.vomevolunteer.com.