API Partenaires¶

L'API Front Desk permet aux partenaires hôteliers (intégrateurs PMS, prestataires de ménage, outils de reporting, connecteurs tiers) d'accéder aux données de votre établissement de façon sécurisée et contrôlée.

Documentation interactive (Swagger)¶

Testez l'API directement dans votre navigateur

L'interface Swagger est le point d'entrée recommandé pour explorer et tester l'API. Elle affiche tous les endpoints disponibles, les paramètres acceptés, les réponses attendues, et permet d'envoyer des requêtes en direct depuis votre navigateur.

Interface Swagger UI :

https://front-desk.app/api/v2/docs/

Schéma OpenAPI (JSON) — à importer dans Postman, Insomnia, etc. :

https://front-desk.app/api/v2/schema/

Pour s'authentifier dans Swagger :

Ouvrez https://front-desk.app/api/v2/docs/
Cliquez sur Authorize (en haut à droite).
Saisissez votre clé dans le champ X-API-Key.
Cliquez sur Authorize, puis Close.
Tous les endpoints que vous appelez depuis l'interface utiliseront automatiquement cette clé.

Vue haut niveau¶

Flux d'intégration¶

Système partenaire
       │
       │  X-API-Key (header)
       ▼
Front Desk API v2  ──▶  Authentification & vérification du scope
       │
       ├──▶  /api/v2/tickets/        (logbook:read / logbook:write)
       ├──▶  /api/v2/items/          (lost_found:read / lost_found:write)
       ├──▶  /api/v2/notebooks/      (notebooks:read / notebooks:write)
       ├──▶  /api/v2/users/          (users:read)
       ├──▶  /api/v2/notifications/  (notifications:read)
       └──▶  /api/v2/activities/     (activities:read)

Carte des ressources¶

Ressource	Endpoint	Lecture	Écriture	Cas d'usage typique
Tickets (logbook)	`/api/v2/tickets/`	`logbook:read`	`logbook:write`	PMS envoyant des incidents chambre
Objets trouvés	`/api/v2/items/`	`lost_found:read`	`lost_found:write`	Outil de suivi objets trouvés
Consignes	`/api/v2/notebooks/`	`notebooks:read`	`notebooks:write`	Synchronisation avec outil de briefing
Utilisateurs	`/api/v2/users/`	`users:read`	—	Annuaire équipe (lecture seule)
Notifications	`/api/v2/notifications/`	`notifications:read`	—	Tableau de bord alertes
Journal d'activité	`/api/v2/activities/`	`activities:read`	—	Reporting / audit

Modèle de sécurité¶

Clé par établissement : chaque clé est scopée à un seul établissement. Impossible d'accéder aux données d'un autre établissement.
Scope minimal : une clé n'a accès qu'aux ressources explicitement autorisées lors de sa création.
Révocable à tout moment : une clé compromise peut être invalidée en un clic depuis l'interface.

Vue bas niveau¶

Pagination¶

Tous les endpoints de liste retournent une réponse paginée :

{
  "count": 150,
  "next": "https://front-desk.app/api/v2/tickets/?page=2",
  "previous": null,
  "results": [ ... ]
}

Paramètre de pagination : ?page=<n> (taille de page : 25 par défaut).

Filtrage¶

Chaque endpoint expose ses propres paramètres de filtrage (voir la section Endpoints disponibles ci-dessous ou le Swagger pour la liste exhaustive).

Format des dates : ISO 8601 (2026-04-24T09:15:00Z).

Headers de réponse utiles¶

Header	Description
`Content-Type: application/json`	Format de réponse
`Retry-After: <secondes>`	Présent en cas de `429 Too Many Requests`

Codes d'erreur¶

Code HTTP	Signification
`200 OK`	Requête réussie
`201 Created`	Ressource créée
`400 Bad Request`	Données de la requête invalides
`401 Unauthorized`	Header `X-API-Key` absent ou malformé
`403 Forbidden`	Clé valide mais scope insuffisant
`404 Not Found`	Ressource introuvable dans votre établissement
`429 Too Many Requests`	Limite de débit dépassée

Exemple d'erreur 403 :

{
  "detail": "You do not have permission to perform this action."
}

Limites de débit¶

120 requêtes par minute par clé API.

Le compteur est isolé par clé : deux clés du même établissement ont chacune leur propre quota de 120 req/min, indépendamment l'une de l'autre.

Au-delà du quota, l'API retourne 429 Too Many Requests. Le header Retry-After indique le nombre de secondes à attendre avant de réessayer.

Authentification¶

Obtenir une clé API¶

Les clés API se gèrent directement depuis l'interface Front Desk.

Connectez-vous à Front Desk en tant qu'administrateur ou propriétaire.
Dans le menu latéral, cliquez sur Clés API.
Cliquez sur Générer une clé.
Saisissez un nom descriptif (ex : Intégration PMS Fidelio) et sélectionnez les permissions.
Copiez immédiatement la clé affichée. Elle n'est visible qu'une seule fois.

Sécurité

La valeur brute d'une clé n'est jamais stockée dans nos serveurs. Conservez-la dans un gestionnaire de secrets sécurisé (Vault, AWS Secrets Manager, variable d'environnement chiffrée). Toute clé compromise doit être révoquée immédiatement.

Utiliser la clé¶

Transmettez la clé dans chaque requête via le header X-API-Key :

GET /api/v2/tickets/ HTTP/1.1
Host: front-desk.app
X-API-Key: votre_cle_api
Accept: application/json

Exemple avec curl :

curl https://front-desk.app/api/v2/tickets/ \
  -H "X-API-Key: votre_cle_api" \
  -H "Accept: application/json"

Exemple avec Python :

import httpx

client = httpx.Client(
    base_url="https://front-desk.app/api/v2/",
    headers={"X-API-Key": "votre_cle_api"},
)

response = client.get("tickets/")
tickets = response.json()

Permissions (scopes)¶

Chaque clé est configurée avec un ou plusieurs scopes qui définissent les ressources accessibles. Une clé sans le scope requis reçoit une erreur 403 Forbidden.

Scope	Description
`logbook:read`	Lecture des tickets du registre de maintenance
`logbook:write`	Création et mise à jour de tickets
`lost_found:read`	Lecture des objets trouvés
`lost_found:write`	Création et mise à jour des objets trouvés
`notebooks:read`	Lecture des consignes
`notebooks:write`	Création et mise à jour des consignes
`users:read`	Lecture de la liste des utilisateurs (lecture seule)
`notifications:read`	Lecture des notifications
`activities:read`	Lecture du journal d'activité

Principe du moindre privilège : accordez uniquement les scopes nécessaires. Un connecteur PMS qui envoie des tickets de panne n'a besoin que de logbook:write.

Base URL¶

Toutes les requêtes API V2 utilisent la base URL suivante :

https://front-desk.app/api/v2/

Endpoints disponibles¶

Registre de maintenance — Tickets¶

ListeCréationDétail

GET /api/v2/tickets/

Retourne la liste des tickets de l'établissement.

Scope requis : logbook:read

Paramètres de filtrage

Paramètre	Type	Description
`is_done`	boolean	Filtrer les tickets terminés
`state`	string	État du ticket (`open`, `in_progress`, `done`)
`created__gte`	datetime	Créé après cette date (ISO 8601)
`created__lte`	datetime	Créé avant cette date (ISO 8601)
`search`	string	Recherche dans la description et l'emplacement

Exemple de réponse

{
  "count": 42,
  "next": "https://front-desk.app/api/v2/tickets/?page=2",
  "previous": null,
  "results": [
    {
      "id": 123,
      "description": "Fuite robinet chambre 204",
      "location": "Chambre 204",
      "state": "open",
      "is_done": false,
      "priority": "high",
      "created": "2026-04-24T09:15:00Z",
      "modified": "2026-04-24T10:30:00Z"
    }
  ]
}

POST /api/v2/tickets/
Content-Type: application/json

Scope requis : logbook:write

Corps de la requête

{
  "description": "Fuite robinet chambre 204",
  "location": "Chambre 204",
  "priority": "high"
}

GET /api/v2/tickets/{id}/

Scope requis : logbook:read

Objets trouvés¶

ListeCréation

GET /api/v2/items/

Scope requis : lost_found:read

POST /api/v2/items/
Content-Type: application/json

Scope requis : lost_found:write

Cahier de consignes¶

ListeCréation

GET /api/v2/notebooks/

Scope requis : notebooks:read

POST /api/v2/notebooks/
Content-Type: application/json

Scope requis : notebooks:write

Utilisateurs¶

Liste

GET /api/v2/users/

Scope requis : users:read

Retourne les membres de l'établissement (sans données sensibles). La création et la modification d'utilisateurs ne sont pas disponibles via l'API partenaire.

Notifications¶

Liste

GET /api/v2/notifications/

Scope requis : notifications:read

Journal d'activité¶

Liste

GET /api/v2/activities/

Scope requis : activities:read

Gestion des clés¶

Modifier les permissions¶

Pour modifier les scopes d'une clé existante sans la révoquer :

Rendez-vous sur Clés API dans le menu latéral.
Cliquez sur l'icône de configuration (roue dentée) en face de la clé.
Cochez ou décochez les scopes souhaités.
Cliquez sur Enregistrer.

Régénérer une clé¶

Si une clé est compromise mais que vous souhaitez conserver le même nom et les mêmes scopes :

Cliquez sur l'icône de régénération (flèches circulaires) en face de la clé.
Confirmez. La clé actuelle est immédiatement révoquée.
Copiez la nouvelle clé affichée. Elle n'est visible qu'une seule fois.

Révoquer une clé¶

Pour révoquer une clé compromise ou obsolète :

Connectez-vous en tant qu'administrateur.
Rendez-vous sur Clés API dans le menu latéral.
Cliquez sur l'icône de révocation (croix) en face de la clé concernée.
Confirmez la révocation.

La clé est immédiatement invalidée. Toute requête ultérieure avec cette clé reçoit 401 Unauthorized.

Isolation des données¶

Chaque clé API est strictement scopée à l'établissement qui l'a générée. Il est impossible d'accéder aux données d'un autre établissement, même en possession d'une clé valide. Cette isolation est appliquée au niveau de la base de données.

Support¶

Pour toute question sur l'API partenaires, contactez-nous via la page support en précisant votre établissement et le cas d'usage.