API edoobox : Premiers pas

L’API edoobox permet des requêtes automatisées et des intégrations, par exemple pour les sites Web, les rapports, la comptabilité, le CRM, WordPress, Zapier ou vos propres systèmes internes. Commencez toujours par un cas d’utilisation clair et une clé API aux droits aussi restreints que possible.

Gestion d'accès edoobox API réelle avec des clés existantes, le statut et l'action Ajouter une clé dans un compte de démonstration.

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

Préparation

Clarifiez quelles données doivent être lues ou écrites.
Créez une clé API distincte pour chaque intégration.
Accordez uniquement les droits réellement nécessaires.
Prévoyez un stockage sécurisé de Secret Key, d’Access Token et de l’environnement Postman.
Testez d'abord avec des données de démonstration ou dans un environnement sans danger.

Générer une clé API

L’API V2 utilise les clés API du compte V2. Ouvrez Paramètres > Gestion des accès API et sélectionnez Ajouter une clé. Choisissez si la clé doit être active immédiatement, puis déterminez le droit approprié.

Après l’enregistrement, edoobox affiche Public Key et Secret Key dans une fenêtre. Secret Key n’est affichée intégralement qu’à ce moment-là. Copiez immédiatement les deux valeurs dans un gestionnaire de mots de passe ou un coffre de secrets. N’envoyez pas les Secret Keys par e-mail, chat ou capture d’écran.

Gérer les clés API dans la gestion d'accès

La gestion des accès API affiche les clés existantes avec leur état, Public Key et le droit attribué. Public Key peut être copiée dans le tableau. Vous pouvez basculer l’état entre actif et inactif. Les clés inactives restent enregistrées, mais ne doivent plus être utilisées.

Une clé API possède les mêmes autorisations que le droit choisi. La sélection peut comprendre des droits existants et des droits prédéfinis tels que Droit WordPress, Droit Zapier ou Droit de lecture. Si un droit prédéfini n’existe pas encore, edoobox peut le créer lors de la création de la clé.

Si un droit attribué est supprimé ultérieurement ou n’est plus trouvé, l’autorisation de la clé n’est plus clairement traçable sur le plan fonctionnel. Créez alors un nouveau droit adapté ou désactivez la clé jusqu’à clarification de l’autorisation.

Élément	Signification
Public Key	Clé API visible, affichée dans la vue d'ensemble et utilisée pour l'authentification.
Secret Key	Élément secret associé à Public Key, affiché intégralement une seule fois après la création.
Statut	Seules les clés actives peuvent être utilisées pour l'authentification.
Droit	Limite l’accès de la clé à l’API.

Exemple d’utilisation : créer une clé API pour les rapports

Pour une analyse externe, ouvrez la gestion des accès API, cliquez sur Ajouter une clé, laissez l’état actif et choisissez un droit de lecture. Après l’enregistrement, copiez immédiatement Public Key et Secret Key dans le coffre de secrets de l’application de rapports.

Authentification et jeton d'accès

L’authentification s’effectue via https://app2.edoobox.com/v2/auth. Envoyez Public Key, Secret Key et, en option, une date d’expiration. La réponse contient une edid et un access_token valide.

Tous les points de terminaison API-V2 protégés nécessitent ensuite le access_token et la edid. La edid définit quel compte a été authentifié actuellement. Dans la réponse d'authentification, vous trouverez également des informations sur les comptes connectés, l'identifiant du compte et les droits, typiquement sous data.login.data[edid]. Si un accès renvoie plusieurs comptes, utilisez consciemment le edid approprié pour chaque requête ; sinon, vous lisez ou écrivez des données dans le mauvais compte ou vous obtenez des erreurs de droits apparemment inexpliquées.

Structure de réponse après l'authentification

La réponse d'authentification contient, en plus du access_token, la edid. Cette edid définit quel compte a été authentifié actuellement dans la réponse. En cas d'accès multi-session ou multi-comptes, plusieurs comptes peuvent apparaître dans data.login.data.

data.login.data[edid]

Vous y trouverez notamment l'identifiant du compte et les droits qui sont effectifs avec cette clé API. Utilisez toujours le jeton et l'identifiant edid de la même authentification réussie pour les autres appels API.

Authentification avec Node.js

const response = await fetch('https://app2.edoobox.com/v2/auth', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    'grant-type': 'password',
    key: process.env.EDOOBOX_PUBLIC_KEY,
    secret: process.env.EDOOBOX_SECRET_KEY
  })
});
const result = await response.json();
if (!response.ok || result.error || !result.data?.access_token || !result.data?.edid) {
  throw new Error('Échec de l’authentification edoobox');
}
const edid = result.data.edid;
const accessToken = result.data.access_token;
// Utiliser le jeton uniquement côté serveur, en mémoire ou dans un coffre de secrets.

Authentification avec PHP

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://app2.edoobox.com/v2/auth',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_CONNECTTIMEOUT => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_POSTFIELDS => json_encode(array(
    'grant-type' => 'password',
    'key' => getenv('EDOOBOX_PUBLIC_KEY'),
    'secret' => getenv('EDOOBOX_SECRET_KEY')
  )),
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));
$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
$failed = $response === false;
curl_close($curl);
if ($failed || $status < 200 || $status >= 300) {
    throw new RuntimeException('Échec de l’authentification HTTP');
}
$result = json_decode($response, true);
if (!is_array($result) || !empty($result['error']) || empty($result['data']['access_token']) || empty($result['data']['edid'])) {
    throw new RuntimeException('Échec de l’authentification edoobox');
}
$edid = $result['data']['edid'];
$accessToken = $result['data']['access_token'];

Première requête : récupérer une page de la liste des offres

Après une authentification réussie, vous pouvez interroger les points de terminaison protégés. L’exemple https://app2.edoobox.com/v2/offer/list lit la première page de la liste des offres, si le droit sélectionné autorise cette requête. Sans paramètre de liste personnalisé, 100 entrées au maximum sont renvoyées. Pour récupérer l’ensemble des données, lisez ensuite les pages suivantes selon la section consacrée à la pagination.

Le fichier OpenAPI actuel exige Authorization: Bearer <JWT> avec edid pour les ressources protégées courantes. Un en-tête grant-type supplémentaire n'y est pas déclaré. En revanche, lors de l'appel d'authentification, grant-type se trouve dans le corps JSON. Vérifiez les exigences divergentes sur la page du point de terminaison respectif.

const offerResponse = await fetch('https://app2.edoobox.com/v2/offer/list', {
  method: 'GET',
  headers: {
    edid,
    Authorization: `Bearer ${accessToken}`
  }
});
if (!offerResponse.ok) {
  throw new Error('Impossible de charger les offres');
}
const offers = await offerResponse.json();
if (offers.error) {
  throw new Error('edoobox a rejeté la requête des offres');
}

Tester les requêtes avec Postman

Avec Postman ou un outil comparable, vous pouvez vérifier les points de terminaison API avant d'écrire du code. Téléchargez le fichier OpenAPI via la référence API-v2 intégrée et importez-le comme définition OpenAPI. La prise en charge du format OpenAPI 3.2.1 dépend de la version de l'outil utilisée.

Créez vous-même un environnement avec l'hôte de votre environnement, vos identifiants de connexion ainsi que des variables pour le JWT et edid. Sélectionnez le point de terminaison importé POST /v2/auth et adoptez l'exemple de corps approprié de la référence. Un fichier d'environnement supplémentaire ou une récupération automatique de jeton n'est pas fourni avec le fichier OpenAPI. Attribuez manuellement les champs de réponse réels après une vérification réussie ou utilisez un script vérifié pour votre environnement.

Si une requête suivante échoue, vérifiez d'abord si l'environnement correct est actif, si la demande d'authentification a réussi et si les en-têtes edid et Authorization sont effectivement remplis à partir des variables stockées.

Accès API : Utilisez l'exemple de corps apiLogin pour POST /v2/auth.
Connexion administrateur : L'exemple de corps administrator décrit l'e-mail et le mot de passe, si cette voie est prévue pour votre cas de test.
Autres requêtes : à n'exécuter qu'après une authentification réussie.

Sécurité et exploitation

Créez des clés distinctes pour chaque intégration, renouvelez-les en cas de changement de personnel ou de prestataire et désactivez les accès inutilisés. Conservez les secrets uniquement dans les systèmes prévus à cet effet et jamais directement dans du code de navigateur accessible au public.

Documentez pour chaque clé l'objectif, la personne responsable, le système, l'étendue des droits et la date de rotation prévue. Ainsi, même après un changement de prestataire, il reste clair quelle intégration possède quel accès.

Si une intégration écrit des réservations, des factures ou des données de participants en production, planifiez la journalisation, le traitement des erreurs, les données de test, les limites de débit, la protection des données et des responsabilités claires. Vous trouverez les détails sur la gestion sous Gérer les clés API et les droits d'accès.

Demander spécifiquement la page de liste suivante

Le paramètre commun de liste V2 est un objet JSON avec start comme position de départ et reply comme taille de page. Pour la deuxième page de 100 entrées, utilisez par exemple limit={"start":100,"reply":100}. Encodez le JSON comme paramètre d’URL, puis avancez la position de départ de la taille de page demandée.

const url = new URL('https://app2.edoobox.com/v2/offer/list');
url.searchParams.set('limit', JSON.stringify({ start: 100, reply: 100 }));
// Récupérer url avec les mêmes en-têtes edid et Authorization.

Vérifiez pour chaque réponse le statut HTTP, le error et le domaine de données de la ressource spécifique. Utilisez les données de total ou de page existantes de cette ressource pour l'arrêt. Une page échouée ne doit pas être traitée comme une page de fin vide.

Pour un rapprochement de réservations permanent, conservez les filtres et le tri sur toutes les pages et enregistrez l'état de traitement terminé uniquement après le transfert réussi de toutes les pages. La sous-page API : Synchroniser les réservations montre le processus avec des fenêtres temporelles, limit.total, des messages dupliqués, des webhooks et le rapprochement supplémentaire de réservations plus anciennes. Il est également expliqué pourquoi time n'est pas un filtre pour toutes les modifications ultérieures.

Après la première requête : Webhooks ou pages d'offres personnalisées

Pour une connexion d'événements, l'authentification seule ne suffit pas encore. Le guide Configurer et exploiter les webhooks passe par le droit de webhook approprié, POST /v2/webhook, la sélection de sujet, la vérification de signature et l'activation jusqu'à la réception vérifiée. La configuration s'effectue avec les requêtes API décrites.

Pour afficher des offres sur votre propre site Web, consultez Site d’offres et planificateur de cours personnalisés. Le guide distingue une synthèse éditoriale personnalisée obtenue via GET /v2/text/list du champ d’offre dérivé shortdescription.

Guides associés

Durée de vie du jeton et traitement complet des listes

Les exemples s’exécutent sur un serveur et lisent les identifiants d’accès dans des variables d’environnement préparées. Sans valeur expire personnalisée, l’API émet par défaut un jeton valable 30 minutes. Renouvelez-le après expiration via l’authentification ; ne le publiez pas et ne l’inscrivez pas dans les journaux.

Une requête de liste renvoie par défaut 100 entrées. La taille de page maximale est de 2000. Pour des bases de données plus importantes, traitez les pages via les paramètres limit documentés jusqu'à ce que tous les enregistrements nécessaires soient récupérés. Une première page réussie ne prouve pas que toutes les offres ont été chargées.

Pour de nouvelles fonctions telles que les abonnements, les plugins ou les automatisations, vérifiez la ressource respective et votre propre droit d'accès. Le droit Zapier préparé n'est pas un droit d'écriture général pour toutes les fonctions edoobox.