Authentification

L’accès passe par un compte partenaire défini par HMS. Un compte partenaire reçoit une apiKey et un apiSecret, et HMS détermine les hôtels auxquels il peut accéder. L’endpoint de connexion échange ces identifiants contre un jeton lié à un hôtel.

Connexion et jeton#

Requête
POST /external/public/login HTTP/1.1
Host: test.hms.gen.tr
Content-Type: application/x-www-form-urlencoded

apiKey=5y94tLmALIKDyUVdEPlAAjg5xWGQNgQtnALlV4%2BAm7Q%3D&apiSecret=a143d640…&hotelCode=1000
Réponse · 200
{
    "success": true,
    "hotelCode": "1000",
    "token": "eyJlbmREYXRlIjp7ImRhdGUiOiIyMDI2LTA5LTE1IDEwOjI0OjMxLjAwMDAwMCIs…",
    "hotelSeoUrl": "demo-otel"
}
ChampDescription
apiKeyClé partenaire. Elle contient des caractères base64 et doit donc être encodée pour l’URL dans un corps de formulaire (+ → %2B, = → %3D). Les bibliothèques HTTP le font pour vous.
apiSecretClé secrète. À conserver uniquement côté serveur ; ne l’intégrez jamais dans un navigateur ou une application mobile.
hotelCodeIdentifiant HMS de l’hôtel. Si le partenaire n’est pas autorisé pour cet hôtel, hotel_permission_is_not_found est renvoyé.
hotelSeoUrlSlug SEO de l’hôtel. Utilisé à la place de hotelCode uniquement par le moteur de réservation propre à HMS ; les intégrations tierces envoient hotelCode.

En-tête Bearer#

Tous les endpoints, sauf la connexion, attendent le jeton dans l’en-tête Authorization :

Requête
GET /external/currencies HTTP/1.1
Host: test.hms.gen.tr
Authorization: Bearer eyJlbmREYXRlIjp7ImRhdGUiOiIyMDI2LTA5LTE1IDEwOjI0OjMxLjAwMDAwMCIs…

Si l’en-tête est absent, mal formé (sans préfixe Bearer) ou si le jeton est inconnu, l’API renvoie 401 :

401 Unauthorized
{
    "success": false,
    "error": "Authentication required"
}

Durée de validité et renouvellement du jeton#

  • Le jeton est valable 7 jours. Renouvelez-le en vous reconnectant avant son expiration ; la connexion est peu coûteuse et peut être répétée pour le même hôtel.
  • N’analysez pas le jeton. Bien qu’il s’agisse d’une structure encodée en base64, son format n’est pas garanti ; stockez-le et transmettez-le comme une chaîne opaque.
  • En cas de 401, reconnectez-vous une fois et relancez la requête ; un second 401 signifie que la paire de clés ou l’autorisation pour l’hôtel a changé.

Contexte hôtel#

Un jeton est lié à un seul hôtel. Le paramètre hotelID des endpoints doit correspondre à cet hôtel ; interroger un autre hôtel entraîne une erreur d’autorisation ou des résultats vides. Pour les intégrations multi-hôtels, obtenez un jeton distinct par hôtel et mettez-le en cache hôtel par hôtel.

Erreurs de connexion#

messageSignification
partner_is_not_foundLa paire apiKey / apiSecret ne correspond pas. Vérifiez les clés et leur encodage URL.
hotel_is_not_foundAucun hôtel ne correspond à hotelSeoUrl.
hotel_permission_is_not_foundLe partenaire n’est pas autorisé pour cet hôtel, ou l’autorisation est inactive. Contactez le support HMS.

Ces erreurs sont renvoyées en HTTP 200 avec success: false et token: null.

Dernière mise à jour: 21 septembre 2026Vous avez repéré une erreur ? Signalez-la-nous