REST versionnée
Toutes les routes sont publiées sous /api/v1. Les évolutions restent rétrocompatibles ; une rupture passerait par une nouvelle version.
Une API de distribution pour vos plateformes
Les plateformes de voyage, comme MODJA, et les partenaires techniques accèdent à l’inventaire des compagnies par une API REST documentée, avec des droits accordés compagnie par compagnie.
Principes
Spécification OpenAPI
Description complète des requêtes, réponses, statuts et erreurs, avec console interactive pour vos développeurs.
Identité machine
Chaque partenaire dispose de sa propre identité, authentifiée par OAuth 2.0 (identifiants client), distincte de tout compte humain.
Droits par compagnie
Chaque compagnie accorde à chaque partenaire des droits précis ; une requête ne peut jamais atteindre les données d’une compagnie non autorisée.
Bac à sable
Identifiants de test séparés de la production, avec billets et paiements simulés clairement signalés.
Traçabilité
Chaque requête reçoit un identifiant de corrélation renvoyé dans les réponses et les erreurs, pour un support efficace.
Opérations disponibles
Exposées seulement si la compagnie les autorise et si son système les prend en charge.
| Opération | Point d’accès | Droit requis |
|---|---|---|
| Obtenir un jeton | POST /partner/oauth/token | — |
| Compagnies, capacités et droits | GET /partner/airlines | — |
| Rechercher des vols (aller simple ou aller-retour) | POST /partner/flights/search | flights:search |
| Revalider une offre / combiner aller et retour | POST /partner/offers/{id}/revalidate, /partner/offers/combine | offers:read |
| Créer une réservation | POST /partner/bookings | bookings:create |
| Consulter une réservation | GET /partner/bookings/{ref} | bookings:read |
| Confirmer après paiement | POST /partner/bookings/{ref}/confirm | bookings:confirm |
| Émettre les billets | POST /partner/bookings/{ref}/ticket | tickets:issue |
| Consulter un billet, reçu-itinéraire PDF | GET /partner/tickets/{n}, /partner/bookings/{ref}/documents/itinerary.pdf | tickets:read |
| Changer de vol | POST /partner/bookings/{ref}/exchange/quote, /exchange | tickets:issue |
| Plan de cabine et choix des sièges | GET / PUT /partner/bookings/{ref}/seats | bookings:read / bookings:create |
| Enregistrement en ligne, carte d’embarquement | POST /partner/bookings/{ref}/checkin | checkin:perform |
| Annuler ou demander l’annulation | POST /partner/bookings/{ref}/cancel | tickets:cancel |
| S’abonner aux événements (webhooks) | POST /partner/webhooks, /partner/webhooks/{id}/test | — |
Règles d’intégration
Ce qui garantit une intégration sans doublon ni erreur de caisse.
- ✓Envoyez un en-tête
Idempotency-Keysur les créations : une requête rejouée renvoie la même réponse, sans nouvelle réservation. - ✓Après un délai dépassé, interrogez l’état de la réservation au lieu de renvoyer l’opération.
- ✓Une référence de réservation ne vaut pas billet : vérifiez le statut de billetterie et chaque billet.
- ✓Les montants sont des chaînes décimales (« 125.50 ») et les dates sont en temps universel.
- ✓Si le prix a changé, l’API renvoie la nouvelle offre : présentez-la au voyageur avant de poursuivre.
- ✓Limite de 120 requêtes par minute et par partenaire ; au-delà, l’API répond 429.
Webhooks : soyez prévenus en temps réel
Abonnez une adresse de votre plateforme aux événements de vos réservations : plus besoin d’interroger l’API en boucle.
| Événement | Déclenché quand |
|---|---|
booking.held, booking.confirmed | Sièges retenus, paiement confirmé |
booking.expired, booking.cancelled | Délai de paiement dépassé, réservation annulée |
ticket.issued, ticket.reissued, ticket.issuance_failed | Billets émis, réémis après échange, émission en échec |
flight.delayed, flight.cancelled | Retard ou annulation d’un vol de la réservation |
checkin.completed | Passager enregistré |
refund.decided, cancellation.decided, payment.failed | Décisions de la compagnie, paiement non abouti |
- ✓Gestion en libre-service par l’API : jusqu’à 5 adresses, choix des événements, événement de test, rotation du secret.
- ✓Chaque envoi porte un en-tête
X-CConnect-Signature(HMAC-SHA256 du corps et d’un horodatage) à vérifier avec votre secret. - ✓Événements enregistrés dans la même transaction que le changement d’état : aucun événement perdu.
- ✓Nouvelles tentatives automatiques pendant plusieurs heures, historique des livraisons et relivraison manuelle.
- ✓Aucune donnée de contact du voyageur dans les événements : référence, statuts, billets et segments uniquement.
Exemple : rechercher puis réserver
requête partenaire
POST /api/v1/partner/flights/search
Authorization: Bearer <jeton>
{ "origin": "FIH", "destination": "FBM",
"departureDate": "2026-11-20", "returnDate": "2026-11-24",
"passengers": { "ADT": 2, "CHD": 0, "INF": 0 } }
POST /api/v1/partner/bookings
Idempotency-Key: 6f1c-…-a91e
{ "offerId": "<offre combinée>",
"passengers": [ … ], "contact": { … } }Questions fréquentes
Comment obtenir des identifiants ?
Après échange avec notre équipe, la plateforme crée votre identité de partenaire et vous transmet un identifiant et un secret de test. Le secret n’est affiché qu’une fois et n’est conservé que sous forme protégée.
Qui encaisse le voyageur ?
Dans l’intégration MODJA, la plateforme partenaire encaisse le voyageur et confirme la réservation avec sa référence de paiement ; le règlement avec la compagnie est suivi séparément.
Toutes les compagnies proposent-elles l’émission ?
Non. Chaque compagnie déclare ses capacités réelles ; l’API indique pour chacune ce qui est disponible et refuse les opérations non prises en charge.
Existe-t-il des notifications vers notre plateforme ?
Oui. Abonnez-vous aux événements de vos réservations par webhooks (voir ci-dessus) : chaque envoi est signé et renvoyé automatiquement en cas d’échec.
Connecter votre plateforme
Nous vous ouvrons un accès de test et accompagnons votre intégration.