TVCast Partner API

Appearance

Areas ​

Les routes areas representent les chambres, zones ou espaces rattaches a une facility.

Format d'identifiant ​

Les identifiants areaExternalId suivent le format historique:

text
{facilityExternalId}-{areaExternalId}

Recuperer une area ​

Retourne les informations d'une chambre, zone ou espace rattache a une facility.

http
GET /v1/areas/{areaExternalId}/

Comportement ​

  • data_services et data_general sont normalises en tableaux vides s'ils sont absents.
  • data_services[].end peut etre normalise au format ISO string si la valeur est presente.

Exemple ​

bash
curl \
  -H "Authorization: Bearer <cms-partner-token>" \
  https://partner.api.tvcast.fr/v1/areas/facility-001-101/

Ouvrir une area ​

Ouvre une chambre et reinitialise ses donnees temporaires.

http
POST /v1/areas/{areaExternalId}/

Cette operation:

  • vide data_general et data_services;
  • passe le statut a open;
  • peut ajouter de nouvelles donnees dans la meme requete.

Le corps peut contenir des champs historiques serialises en JSON string:

  • data_general
  • data_services

Exemple ​

json
{
  "data_general": "[{\"key\":\"guest_name\",\"value\":\"Jean Dupont\"}]",
  "data_services": "[{\"label\":\"Petit dejeuner\",\"end\":\"2026-04-30T10:00:00.000Z\"}]"
}

Reponse indicative ​

json
{
  "info": "room opened",
  "area": {}
}

Fermer une area ​

Ferme une chambre et reinitialise ses donnees temporaires.

http
DELETE /v1/areas/{areaExternalId}/

Cette operation:

  • vide data_general et data_services;
  • passe le statut a closed.

Reponse indicative ​

json
{
  "info": "room closed",
  "room": {}
}

Mettre a jour le nom ​

Met a jour le nom de la chambre ou de l'area.

http
PATCH /v1/areas/{areaExternalId}/name

Corps attendu:

json
{
  "value": "Nom de chambre"
}

Reponse indicative:

json
{
  "name": "Nom de chambre"
}

Ajouter des donnees generales ​

data_general permet au partenaire de transmettre des cles/valeurs libres au niveau d'une area.

Ces donnees peuvent ensuite etre utilisees dans nos interfaces comme variables d'affichage, de personnalisation ou de contexte.

http
PATCH /v1/areas/{areaExternalId}/data_general

Le corps conserve le format legacy: value est une chaine contenant un JSON array.

json
{
  "value": "[{\"key\":\"guest_name\",\"value\":\"Jean Dupont\"},{\"key\":\"guest_language\",\"value\":\"fr\"},{\"key\":\"stay_reference\",\"value\":\"ABC123\"}]"
}

Cas d'usage ​

  • nom de l'occupant;
  • langue de l'occupant;
  • reference externe partenaire;
  • informations contextuelles affichables dans l'interface;
  • libelles ou parametres metier propres au partenaire.

Comportement ​

  • key identifie la variable.
  • value contient la valeur exploitable par les interfaces.
  • Les donnees sont fusionnees avec les donnees existantes.
  • Si une entree possede une key deja presente, elle remplace l'ancienne valeur.
  • Les cles inconnues par l'interface peuvent etre conservees sans etre affichees.
  • Les noms de cles sont libres, mais doivent idealement etre stables et documentes entre le partenaire et Comminter.

Reponse indicative ​

json
{
  "info": "data added to room",
  "data": [
    { "key": "guest_name", "value": "Jean Dupont" },
    { "key": "guest_language", "value": "fr" },
    { "key": "stay_reference", "value": "ABC123" }
  ]
}

Communiquer des souscriptions de services ​

Les endpoints data_services sont reserves aux installations compatibles avec la gestion de souscriptions de services par chambre.

http
POST /v1/areas/{areaExternalId}/data_services
DELETE /v1/areas/{areaExternalId}/data_services/{serviceId}

Ils sont documentes en detail dans Souscriptions de services.

Notes communes ​

  • Toutes les routes v1 exigent Authorization: Bearer <cms-partner-token>.
  • Les permissions CMS limitent les areas accessibles.
  • Une reponse 403 peut etre retournee meme avec un token valide si l'area n'est pas autorisee pour le partenaire.
  • Plusieurs corps de requete conservent des formats legacy, notamment des tableaux JSON serialises dans une chaine.
  • Les endpoints data_services ne sont pas destines a toutes les integrations partenaires et disposent d'une page dediee.
  • Les endpoints Remote Control sont documentes separement dans Remote Control.