Guide technique de l'API Regiondomod
Pour les développeurs et responsables techniques d'opérateurs de tours souhaitant relier Regiondomod à leurs systèmes internes.
Vue d'ensemble
L'API Regiondomod est une interface REST qui permet à vos applications autorisées de lire et écrire dans votre compte opérateur : réservations, disponibilités, tarifs, profils clients, canaux de distribution. Toutes les requêtes doivent être authentifiées et transitent en HTTPS. Les réponses sont retournées en JSON UTF-8.
Base URL et versions
URL de production : https://api.regiondomod.org/v1. URL bac à sable : https://sandbox.regiondomod.org/v1. La version courante est v1. Les évolutions rétro-compatibles restent sur v1. Les changements majeurs feront l'objet d'une version v2 avec une période de coexistence de 12 mois minimum.
Étapes de mise en place
Générer une clé API
Depuis votre espace opérateur, allez dans Paramètres → Intégrations → Accès API. Cliquez sur "Nouvelle clé", nommez-la selon l'intégration cible (ex : "CRM interne", "Power BI"), sélectionnez les permissions minimales nécessaires.
Stocker la clé côté serveur
La clé s'affiche une seule fois à la génération. Copiez-la dans votre gestionnaire de secrets (Vault, AWS Secrets Manager, variables d'environnement chiffrées). Ne jamais la commettre dans un dépôt Git.
Tester dans le bac à sable
Ciblez d'abord sandbox.regiondomod.org. Le bac à sable est peuplé de données de test réinitialisées chaque nuit. Vérifiez le format des réponses, le comportement des erreurs et les limites de débit.
Passer en production
Remplacez l'URL par la production et surveillez les 48 premières heures via les journaux d'appels disponibles dans Paramètres → Intégrations → Journaux.
Authentification
Chaque requête doit inclure l'en-tête X-Api-Key. Exemple : X-Api-Key: tfp_live_a1b2c3d4e5f6.... Les clés bac à sable commencent par tfp_sandbox_. Les clés production commencent par tfp_live_. Une clé compromise doit être révoquée immédiatement depuis l'écran de gestion.
Catégories d'endpoints
- Réservations : GET/POST/PATCH sur
/reservations. Inclut participants, créneau, statut de paiement, canal d'origine, extras achetés. - Disponibilités : GET/PATCH sur
/availability. Consultation et blocage de créneaux, gestion des seuils de départ. - Tarifs : GET/POST sur
/pricing. Grilles par catégorie participant, remises, tarifs saisonniers. - Catalogue : GET sur
/activitieset/categories. Structure du catalogue, attributs, images. - Clients : GET/PATCH sur
/customers. Profils clients, historique de participation, préférences. - Canaux : GET sur
/channels. État des connexions vers GetYourGuide, Viator, Musement, Regiondo, etc. - Webhooks : GET/POST/DELETE sur
/webhooks. Enregistrement d'URL destinataires par type d'événement. - Rapports : GET sur
/reports. Volumes, revenus, marges par canal ou par activité.
Limites de débit
600 requêtes par minute par clé API. Un dépassement renvoie HTTP 429 avec un en-tête Retry-After. Implémentez un recul exponentiel : 1 s, 2 s, 4 s, 8 s. Regroupez vos requêtes (?from=&to=) plutôt que de solliciter l'API pour chaque élément individuellement.
Gestion des erreurs
| Code HTTP | Signification | Action recommandée |
|---|---|---|
| 200 / 201 | Succès | Traiter la réponse normalement |
| 400 | Requête invalide — payload mal formé | Vérifier la structure JSON envoyée |
| 401 | Non authentifié — clé absente ou incorrecte | Vérifier l'en-tête X-Api-Key |
| 403 | Interdit — permissions insuffisantes | Ajuster les permissions de la clé |
| 404 | Ressource introuvable | Vérifier l'identifiant de la ressource |
| 409 | Conflit — état incompatible | Relire la ressource et retenter |
| 429 | Trop de requêtes | Respecter Retry-After, appliquer un recul |
| 500 / 503 | Erreur serveur Regiondomod | Retenter après 60 s, contacter le support si persistant |
Webhooks : signature HMAC
Chaque webhook envoyé par Regiondomod inclut un en-tête X-Regiondomod-Signature contenant un HMAC-SHA256 du corps de la requête, calculé avec le secret partagé de votre endpoint. Validez systématiquement cette signature avant de traiter le payload — sinon un tiers malveillant pourrait falsifier des événements.