API room-event
Point d'entrée unique par lequel un événement chambre (check-in / check-out) est signalé à hospiphone. Cette page couvre le contrat que votre intégration doit respecter, y compris le champ guest_code à venir.
Vue d'ensemble
Chaque chambre d'établissement dispose d'un identifiant SIP interne fixe. En complément, un code d'appel propre au séjour en cours peut être généré à chaque check-in — c'est ce code que votre interface doit récupérer et transmettre au patient, pour qu'il le communique à ses proches. Le code change automatiquement au check-in suivant : un ancien code ne joint plus jamais la chambre une fois le prochain séjour commencé.
Votre système appelle POST /room-event au moment du check-in ; la réponse contient le code à afficher.
Accès & environnement
Un seul environnement est ouvert à l'intégration pour le moment.
| Environnement | Base URL | Disponibilité |
|---|---|---|
| dev | https://hospitality.ansetech.com/hospiphone/dev-api | ouvert |
| prod | — | pas encore actif |
La production n'est pas encore ouverte à cette intégration : les mises à jour en cours (dont guest_code) ne sont déployées que sur l'environnement dev pour l'instant. Développez et testez contre dev — l'ouverture de la prod fera l'objet d'une communication séparée une fois la fonctionnalité livrée et déployée.
x-api-key: bc6131d12002efc3d377963231ef5b23d74463f40c5ab476ac9d21f5437da284
Authentification
Toutes les requêtes portent un en-tête de clé API statique, fournie ci-dessus pour l'environnement dev :
x-api-key: <clé de l'environnement — voir Accès & environnement>
Une clé absente ou invalide renvoie 401 (voir Codes d'erreur).
Sur la base URL dev ci-dessus, soit en entier : https://hospitality.ansetech.com/hospiphone/dev-api/asterisk/room-event.
Corps de requête
| Champ | Type | Description |
|---|---|---|
| hotel_id | string | Identifiant de l'établissement requis |
| room_id | string | Identifiant interne de la chambre requis |
| event | "checkin" | "checkout" | Seul "checkin" déclenche une action ; "checkout" répond ok sans effet requis |
{
"hotel_id": "66a26bebe5716871b4344522",
"room_id": "chambre02",
"event": "checkin"
}
Réponse — 200
| Champ | Type | Statut | Description |
|---|---|---|---|
| ok | boolean | live | Toujours true si la requête est acceptée |
| voicemails_deleted | number | live | Nombre de messages vocaux purgés pour cette chambre |
| guest_code | string | null | à venir | Code d'appel régénéré pour ce séjour. null si la fonctionnalité est désactivée pour cet établissement |
Important : traitez guest_code: null comme un état normal, pas une erreur — certains établissements n'activent pas le code dynamique. Dans ce cas, n'affichez aucun code au patient.
{ "ok": true, "voicemails_deleted": 3, "guest_code": "1102" }
{ "ok": true, "voicemails_deleted": 0, "guest_code": null }
Codes d'erreur
| Code | Cause | Action recommandée |
|---|---|---|
| 400 | Un champ requis manque dans le corps de la requête | Vérifier hotel_id, room_id, event |
| 401 | En-tête x-api-key absent ou invalide | Vérifier la clé fournie par hospiphone |
| 500 | Erreur serveur interne | Réessayer avec un backoff ; contacter hospiphone si persistant |
Exemple complet
curl -X POST https://hospitality.ansetech.com/hospiphone/dev-api/asterisk/room-event \ -H "x-api-key: bc6131d12002efc3d377963231ef5b23d74463f40c5ab476ac9d21f5437da284" \ -H "Content-Type: application/json" \ -d '{"hotel_id":"66a26bebe5716871b4344522","room_id":"chambre02","event":"checkin"}'
{ "ok": true, "voicemails_deleted": 0, "guest_code": "1102" }
Notes d'intégration
Un seul code actif à la fois
Un nouveau check-in régénère guest_code et invalide immédiatement l'ancien pour cette chambre. N'affichez jamais un code mis en cache d'un appel précédent.
Pas de webhook de reprise
Si votre système ne récupère pas la réponse (timeout réseau), il n'existe pas aujourd'hui d'endpoint de relecture du dernier code — le prochain check-in en régénérera un nouveau de toute façon. Prévoyez une nouvelle tentative côté appelant en cas d'échec réseau.
Format du code
Chaîne numérique, longueur variable (visez 4 chiffres dans vos maquettes). Traitez-le comme une chaîne opaque, ne tentez pas de le parser ou d'en déduire le numéro de chambre.
checkout
event: "checkout" reste accepté et répond { ok: true } sans guest_code — aucune action requise de votre côté à ce moment.