Introduction

L’API Customotel est un service web hébergé par Xelya, à destination des structures hotellières et de leurs clients, et qui veulent interfacer directement avec leurs sites web ou extranets.

L’API utilise un protocole REST JSON via HTTPS.

Le contenu de toutes les requêtes et réponses est au format JSON, et encodé en UTF-8.

L’API est structurée par fonctionnalités. Certaines sont accessibles uniquement sur option.

Les méthodes de l’API permettent d’accèder à une liste d’objets et/ou au détail d’un objet (GET), de créer de nouveaux objets (POST) ou d’en mettre à jour (PUT)

Un exemple d’utilisation de l’API est disponible sous la forme d’un fichier Postman.

Initialisation

L'utilisation de l'API est autorisée par l'activation d'un accès avec identifiant unique.
L'identification et l'authentification sont assurées au moyen d'un token JWT.
Le token JWT, qui devra être passé dans chaque requête de l'API, contient notamment l'identifiant unique qui vous sera attribué par Xelya. Cet identifiant vous donne accès, via l'API, aux données d'une application au sein de Ximi.
Le token est signé via une clé RSA 2048.
En tant que consommateur de l'API, vous devez préalablement générer une clé RSA de taille 2048 bit.
La génération de cette clé peut se faire via des outils comme OpenSSH.
Vous conservez la partie privée de la clé. La partie publique doit nous être envoyée au format PEM, elle nous servira à vérifier la signature des tokens JWT.

Authentification

Un token JWT doit être généré au début d'une séquence d'utilisation de l'API,
et doit être transmis dans tous les appels aux méthodes de l'API, dans un Header nommé API-Key

La valeur de ce header doit être un token JWT avec le contenu suivant :
Header : { "alg": "RS512", "typ" : "JWT"}
Payload: { “sub": "", "exp" : "" }
Signature :

Le contenu de Header est fixe; l'algorithme de signature est RS512.
Le Payload doit contenir :
- dans "sub" la valeur de l'identifiant unique qui vous a été fourni par Xelya, et qui identifie un tenant/application Ximi.
Le format de l'identifiant ressemble à ceci : a067d785-7947-4092-1f39-f0576ad4b1c9
- dans "exp" une date d'expiration, exprimée sous la forme d'un timestamp, ou nombre de secondes depuis le 1er janvier 1970.
Le contenu de Signature est généré en signant avec la clé privée les contenus encodés en Base 64 des Header et Payload.

Le contenu final passé dans le header API-Key ressemble à l'exemple suivant :

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Requêtes

Chaque requête doit contenir au minimum les headers suivants :
Content-Type : application/json
API-Key :

NOTE : les formats acceptés pour les champs de type DATE dans le corps de méthodes sont les suivants : YYYY-MM-DD, ISO 8601 (YYYY-MM-DDThh:mm:ssZ)

Réponses

Méthodes GET de listes

Les méthodes qui retournent des listes d'objets ont une réponse JSON structurée ainsi :
{
Results : [] // liste des objets résultats de la requête
HasMoreRows : boolean // Vaut true s'il y a des données supplémentaires (voir paramètres gérant la pagination)
Hitcount : integer // Nombre d'éléments total, renseigné si dans la requête les paramètres ComputeHasMoreRows et ComputeHitCount sont à true
}

Chaque objet retourné contient généralement une propriété Id : integer, qui est l'identifiant unique de l'objet dans la base de données.
Cet Id correspond à la clé étrangère qu'on retrouve dans d'autres propriétés de certaines données résultats.

Méthodes POST de création

Les méthodes qui permettent de créer des objets ont une réponse JSON, en cas de succès, qui contient au moins une propriété Id : integer, qui est l'identifiant unique de l'objet qui vient d'être créé.

API

Liste exhaustive des méthodes disponibles :

Gestion des tâches :

---

---

---

Gestion des utilisateurs :

---

---

---

Gestion des fichiers :

---

---