edoobox API

L’API edoobox permet un accès direct aux données edoobox pour vos sites Web, systèmes comptables, CRM, rapports, automatisations ou autres intégrations. Tout projet API doit commencer avec un objectif clair, des droits adaptés et une gestion sécurisée des clés.

AGestion des accès APIBAvertissement de sécuritéCÉtat des clés et des droits

Ce que permet l’API edoobox

L’API permet aux systèmes de lire les données edoobox ou de les écrire avec les droits appropriés. Les ressources courantes sont les offres, catégories, réservations, participants, factures, transactions et autres données de base. L’API V2 utilise des JSON Web Tokens et propose, selon la ressource, des opérations courantes de lecture, création, actualisation et suppression.

N’utilisez pas l’API directement depuis du code public de navigateur si des Secret Keys ou des jetons sont nécessaires. Ces requêtes doivent être exécutées dans un serveur applicatif.

Droits et groupes d'autorisation

Avec l’API V2, vous pouvez limiter l’accès au moyen de groupes d’autorisations. Pour un outil comptable, par exemple, seules les données de facturation et de paiement devraient être autorisées, sans ouvrir toutes les fonctions d’administration ou d’offres.

Les rôles principaux connus, comme superadministrateur, administrateur, responsable ou responsable limité, peuvent en principe aussi permettre un accès API lorsqu’un administrateur s’authentifie avec ses identifiants de connexion. Cette solution est toutefois rarement idéale pour les intégrations durables.

Créez si possible des groupes d’autorisations propres aux intégrations. N’utilisez pas sans réflexion les droits d’un administrateur réel : cela peut soit donner trop de droits à l’API, soit retirer à l’administrateur des droits nécessaires à son travail habituel. Un groupe dédié permet de voir les données réellement nécessaires à l’intégration.

Créer une clé API et la conserver en lieu sûr

Créez les clés API dans les paramètres du compte, dans la gestion des accès API. Secret Key n’est affichée qu’une seule fois. Conservez-la immédiatement dans un gestionnaire de mots de passe ou un coffre de secrets.

Créez une clé distincte pour chaque intégration. Vous pourrez ainsi attribuer ultérieurement les droits, les responsables, la rotation et la désactivation de manière claire. Les détails sont disponibles sous Gérer les clés API et les droits d'accès.

API V2, URL de base et Postman

Pour les premiers tests, utilisez Postman ou un outil API comparable. Créez un environnement avec Base URL, API Key, Secret Key, EdID, le jeton et l’expiration. Base URL dépend de l’environnement edoobox utilisé ; pour l’environnement V2 de production, on utilise généralement https://app2.edoobox.com/v2.

Vous trouverez la référence actuelle des points de terminaison dans la documentation API v2 intégrée. Elle propose aussi le fichier OpenAPI à télécharger et une version Markdown pour les LLM. L’adresse serveur fournie correspond à un environnement local de test ; lors de l’import dans votre outil API, indiquez l’hôte de votre environnement edoobox réel.

Postman permet de vérifier l’authentification, les en-têtes, les paramètres et les réponses d’erreur avant de programmer une intégration. Ne partagez jamais de collections Postman contenant de vrais secrets. Dans vos exemples documentés, remplacez API Key, Secret Key, le jeton, les données clients et les données de facturation par des variables de remplacement.

Authentification et jetons

L’API utilise des identifiants pour obtenir un jeton d’accès. On commence généralement par une requête d’authentification vers /auth avec API Key, Secret Key et la durée de validité souhaitée. Utilisez ensuite ce jeton pour les appels API. Les jetons et secrets doivent être traités comme des mots de passe. Enregistrez l’expiration, l’environnement et le groupe d’autorisations attribué dans votre documentation technique afin de cibler plus rapidement les erreurs ultérieures.

La spécification décrit deux possibilités pour la plupart des opérations protégées : un JWT Bearer avec edid ou la session de navigateur existante via _edlogin avec edid. La structure exacte de la réponse de jeton reste partiellement non définie dans le fichier OpenAPI fourni. Utilisez uniquement une implémentation de connexion confirmée pour votre environnement. Pour les intégrations côté serveur, des accès API dédiés sont généralement plus faciles à contrôler que les connexions personnelles d’administrateurs.

Si l’authentification échoue, vérifiez l’environnement, API Key, Secret Key, les droits, l’expiration, les en-têtes et l’activation de la clé.

Identifier les erreurs API

Les erreurs API contiennent un code de statut et un message. Les causes fréquentes sont des droits manquants, des identifiants incorrects, des paramètres invalides, un environnement erroné, des jetons expirés ou des ressources inexistantes.

Journalisez les erreurs sans secrets. La date et l’heure, l’ID de requête ou le contexte fonctionnel sont utiles. Les Secret Keys, les jetons et les données personnelles brutes n’ont pas leur place dans les journaux.

API V1 et intégrations plus anciennes

Les intégrations plus anciennes peuvent encore faire référence à API V1 ou à d'anciennes versions d'application. API V1 n'est plus développée et ne doit plus être utilisée pour de nouveaux projets. Les interfaces existantes peuvent continuer à fonctionner ; les connexions WordPress plus anciennes peuvent encore faire référence aux mécanismes de la V1. Vérifiez pour les nouveaux projets si API V2 peut être utilisée. Documentez les intégrations anciennes afin que les dépendances restent visibles.

Lors de la modernisation d'une intégration existante, planifiez des tests avec des données de démonstration, une vérification des droits et une bascule claire. Vérifiez en particulier si les anciens scripts fonctionnent encore avec une connexion administrateur, d'anciennes URL de base ou des droits trop larges.

Exemple d’utilisation : données d’offres sur votre propre site Web

Une organisation souhaite afficher ses offres publiées sur son propre site Web. Le serveur applicatif utilise une clé API avec des droits de lecture sur les offres et catégories, récupère les données côté serveur et transmet uniquement les champs nécessaires au site Web. Secret Key et le jeton restent sur le serveur.

Interpréter les erreurs d'une requête de lecture ou d'écriture

Vérifiez à la fois le statut HTTP et le champ error de la réponse JSON. Une réponse techniquement reçue peut être rejetée sur le plan métier. En cas de problème d'authentification, vérifiez la clé active, son droit, le jeton et le edid associé au jeton.

En cas de résultat d’écriture incertain, recherchez d’abord l’objet déjà créé ou sa référence externe documentée. Ne recréez pas aveuglément une réservation, une facture ou un paiement après un délai d’attente dépassé. Pour les listes complètes, respectez la position de départ et la taille de page de chaque page.

Créer son propre site web d'offres et son planificateur de cours

Pour les pages propres, lisez les données et les textes d'offres côté serveur, associez-les par l'identifiant d'offre et mettez à jour un cache géré de manière intentionnelle. Les résumés éditoriaux propres peuvent être lus via la ressource de texte à partir d'un texte supplémentaire convenu. Le guide API : Site web d'offres et planificateur de cours propres présente les champs de données, la référence linguistique, les liens de réservation actuels et les limites d'image.

La réservation reste dans le processus edoobox prévu. Un cache local ne réserve pas de place. Pour une mise à jour rapide, des Webhooks appropriés peuvent déclencher une récupération ciblée ; la synchronisation régulière reste partie intégrante de votre intégration.

Modifier les responsables d’un créneau via l’API

L’attribution appartient à la ressource date, donc au créneau précis. Le champ leader est une liste d’ID publiques d’admin. Plusieurs responsables sont enregistrés ensemble dans cette liste.

Lisez le créneau avec GET /v2/date/{id} et reprenez sa liste leader actuelle.
Déterminez la liste complète souhaitée : conservez les personnes encore responsables, ajoutez un nouvel identifiant administrateur ou omettez l'identifiant à supprimer.
Envoyez la liste complète avec PUT /v2/date/{id} dans le champ data.leader.
Vérifiez l’état HTTP et l’état fonctionnel. Relisez ensuite le même créneau et comparez les ID réellement enregistrées à la liste souhaitée.

// currentLeaderIds a été lu depuis la date.
// additionalAdminId et removedAdminId sont des identifiants publics d’administrateurs vérifiés.
const desiredLeaderIds = [...new Set([...currentLeaderIds, additionalAdminId])]
  .filter(id => id !== removedAdminId);
const requestBody = { data: { leader: desiredLeaderIds } };
// Envoyer requestBody au format JSON avec PUT /v2/date/{id}, puis relire le résultat.

La liste envoyée remplace l’attribution précédente. Si vous envoyez uniquement une nouvelle ID, les responsables précédents ne sont pas automatiquement conservés. {"data":{"leader":[]}} supprime toutes les attributions de responsables de ce créneau. Aucun opérateur personnalisé add ou remove n’est prévu pour ce champ.

Coordonnez les modifications simultanées afin de ne pas écraser une attribution de responsables actualisée entre-temps. Vérifiez également l’attribution du créneau dans le calendrier. Modifier ce créneau ne modifie pas automatiquement tous les autres créneaux de l’offre.

Synchroniser les réservations avec le CRM et d'autres systèmes

Pour un aperçu actuel des réservations dans le CRM, combinez une première importation complète, des récupérations continues de nouvelles réservations et des mises à jour régulières des réservations déjà connues. Le moment de la réservation time n'est pas un horodatage de modification : un filtre temporel pour les nouvelles réservations ne capture pas automatiquement les annulations ultérieures de réservations plus anciennes.

Le guide API : Synchroniser les réservations explique les filtres de champs, l'encodage URL, le tri unique, toutes les pages de liste, le traitement répétable et la combinaison avec les webhooks à l'aide d'un exemple de CRM.

Guides associés

Vérifier les fonctions existantes avant un projet API

L’intégration native Bexio est disponible pour la connexion comptable. Vous pouvez configurer des règles internes pour les tags, notes, champs de données et choix de modèles avec les automatisations. Les deux fonctions s’activent via le Plugin Manager.

Des ressources dédiées existent pour les abonnements et les cartes multiples, pour la définition, l'attribution aux utilisateurs, les périodes et les utilisations. Vérifiez avant les accès en écriture la disponibilité du plugin, les autorisations et les flux métier. Une réservation ou une transaction normale ne remplace pas la vérification de la validité de l'abonnement ou des utilisations restantes.