DéveloppeursVersion tablette · pilote

Référence des routes HTTP

Routes Kelna explicites, identités requises et schémas de requête issus du code.

Lire le contrat

Ouvrez une route pour consulter ses paramètres de chemin et son schéma JSON lorsqu’ils existent. Les schémas sont extraits des validateurs Fastify au build ; une route manquante dans le catalogue fait échouer la génération.

Le contrat OpenAPI 3.1 couvre ces routes Kelna, hors proxy Better Auth. Les réponses de salle et les règles de reprise sont expliquées dans « Lire la salle et envoyer une action ». Un code 200 ne prouve pas que l’appel suivant sera encore autorisé : les identités sont revérifiées.

Les routes vision sont signalées comme expérimentales. Elles conservent seulement des réglages ; elles n’activent pas une détection en service.

Télécharger le contrat OpenAPI

GET/api/health

Vérifier que le processus API répond.

Accès: Route sans session ; les autres contrôles restent applicables

GET/api/ready

Vérifier la connexion à la base initialisée. Répond 503 si elle est indisponible.

Accès: Route sans session ; les autres contrôles restent applicables

GET/api/account

Lire le compte connecté et le besoin de double authentification. La réponse contient des données personnelles du compte.

Accès: Session humaine ; MFA selon la route

GET/api/account/verified

Vérifier que la session humaine a passé la double authentification.

Accès: Session humaine ; MFA selon la route

POST/api/account/activate

Activer ou récupérer un compte avec un jeton d’invitation valable une heure. Mot de passe de 12 à 128 caractères.

Accès: Route sans session ; les autres contrôles restent applicables

Corps JSON de la requête

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "token",
    "password"
  ],
  "properties": {
    "token": {
      "type": "string",
      "minLength": 43,
      "maxLength": 43
    },
    "password": {
      "type": "string",
      "minLength": 12,
      "maxLength": 128
    }
  }
}

GET/api/access/organizations

Lister les organisations accessibles après MFA.

Accès: Session humaine ; MFA selon la route

GET/api/organizations/{organizationId}/venues

Lister les établissements autorisés et les capacités de gestion d’appareils et de rapports.

Accès: Session humaine ; MFA selon la route

Paramètres de chemin

{
  "type": "object",
  "required": [
    "organizationId"
  ],
  "properties": {
    "organizationId": {
      "type": "string",
      "format": "uuid"
    }
  }
}

GET/api/organizations/{organizationId}/roles

Lister les rôles et leurs permissions dans l’organisation.

Accès: Session humaine ; MFA selon la route

Paramètres de chemin

{
  "type": "object",
  "required": [
    "organizationId"
  ],
  "properties": {
    "organizationId": {
      "type": "string",
      "format": "uuid"
    }
  }
}

POST/api/organizations/{organizationId}/role-assignments

Attribuer un rôle à un membre. venueId vaut null pour une portée organisation. Le contrôle SQL vérifie les droits et empêche l’escalade ; une session récente est requise.

Accès: Session humaine ; MFA selon la route

Paramètres de chemin

{
  "type": "object",
  "required": [
    "organizationId"
  ],
  "properties": {
    "organizationId": {
      "type": "string",
      "format": "uuid"
    }
  }
}

Corps JSON de la requête

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "memberId",
    "roleId",
    "venueId"
  ],
  "properties": {
    "memberId": {
      "type": "string",
      "format": "uuid"
    },
    "roleId": {
      "type": "string",
      "format": "uuid"
    },
    "venueId": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    }
  }
}

DELETE/api/organizations/{organizationId}/role-assignments/{assignmentId}

Révoquer une attribution avec contrôle des droits, session récente et maintien d’un Propriétaire.

Accès: Session humaine ; MFA selon la route

Paramètres de chemin

{
  "type": "object",
  "required": [
    "organizationId",
    "assignmentId"
  ],
  "properties": {
    "organizationId": {
      "type": "string",
      "format": "uuid"
    },
    "assignmentId": {
      "type": "string",
      "format": "uuid"
    }
  }
}

GET/api/organizations/{organizationId}/venues/{venueId}/devices

Lister les appareils, leur dernière activité, leur expiration et leur révocation.

Accès: Session humaine ; MFA selon la route
Permission: devices.manage

Paramètres de chemin

{
  "type": "object",
  "required": [
    "organizationId",
    "venueId"
  ],
  "properties": {
    "organizationId": {
      "type": "string",
      "format": "uuid"
    },
    "venueId": {
      "type": "string",
      "format": "uuid"
    }
  }
}

POST/api/organizations/{organizationId}/venues/{venueId}/pairing

Créer un code à usage unique valable cinq minutes, pour une tablette ou un passe.

Accès: Session humaine ; MFA selon la route
Permission: devices.manage

Paramètres de chemin

{
  "type": "object",
  "required": [
    "organizationId",
    "venueId"
  ],
  "properties": {
    "organizationId": {
      "type": "string",
      "format": "uuid"
    },
    "venueId": {
      "type": "string",
      "format": "uuid"
    }
  }
}

Corps JSON de la requête

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "kind"
  ],
  "properties": {
    "kind": {
      "enum": [
        "tablet",
        "pass"
      ]
    }
  }
}

POST/api/organizations/{organizationId}/venues/{venueId}/devices/{deviceId}/revoke

Révoquer un appareil de l’établissement.

Accès: Session humaine ; MFA selon la route
Permission: devices.manage

Paramètres de chemin

{
  "type": "object",
  "required": [
    "organizationId",
    "venueId",
    "deviceId"
  ],
  "properties": {
    "organizationId": {
      "type": "string",
      "format": "uuid"
    },
    "venueId": {
      "type": "string",
      "format": "uuid"
    },
    "deviceId": {
      "type": "string",
      "format": "uuid"
    }
  }
}

POST/api/device/pair

Échanger un code de huit caractères contre le cookie HttpOnly kelna.device. Origine vérifiée et tentatives limitées.

Accès: Route sans session ; les autres contrôles restent applicables

Corps JSON de la requête

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "code",
    "kind"
  ],
  "properties": {
    "code": {
      "type": "string",
      "pattern": "^[A-HJ-NP-Z2-9]{8}$"
    },
    "kind": {
      "enum": [
        "tablet",
        "pass"
      ]
    }
  }
}

GET/api/device

Lire l’établissement et la vue autorisés pour l’appareil actuel.

Accès: Appareil jumelé

GET/api/organizations/{organizationId}/venues/{venueId}/room

Lire l’instantané de salle avec une session humaine vérifiée et le contexte explicite de l’établissement.

Accès: Session humaine ; MFA selon la route
Permission: venue.view

Paramètres de chemin

{
  "type": "object",
  "required": [
    "organizationId",
    "venueId"
  ],
  "properties": {
    "organizationId": {
      "type": "string",
      "format": "uuid"
    },
    "venueId": {
      "type": "string",
      "format": "uuid"
    }
  }
}

GET/api/room

Lire l’instantané du plan, du service, des tables et des groupes pour l’appareil jumelé.

Accès: Appareil jumelé
Permission: venue.view

POST/api/room/services

Ouvrir un service avec un UUID id fourni par l’appelant. Le plan et les seuils sont figés à l’ouverture.

Accès: Tablette jumelée, avec permission
Permission: services.manage

Corps JSON de la requête

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    }
  }
}

POST/api/room/services/{serviceId}/close

Fermer un service avec un UUID de commande id. Les derniers états sont conservés.

Accès: Tablette jumelée, avec permission
Permission: services.manage

Paramètres de chemin

{
  "type": "object",
  "required": [
    "serviceId"
  ],
  "properties": {
    "serviceId": {
      "type": "string",
      "format": "uuid"
    }
  }
}

Corps JSON de la requête

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    }
  }
}

POST/api/room/services/{serviceId}/tables/{tableId}/commands

Appliquer une action de table ou undo avec id et expectedVersion. Une table réunie exige aussi groupId et les versions de tous ses membres.

Accès: Tablette jumelée, avec permission
Permission: tables.update

Paramètres de chemin

{
  "type": "object",
  "required": [
    "serviceId",
    "tableId"
  ],
  "properties": {
    "serviceId": {
      "type": "string",
      "format": "uuid"
    },
    "tableId": {
      "type": "string",
      "format": "uuid"
    }
  }
}

Corps JSON de la requête

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "type",
    "expectedVersion"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "type": {
      "enum": [
        "seat",
        "greet",
        "order",
        "serve",
        "request_bill",
        "deliver_bill",
        "pay",
        "depart",
        "clear",
        "undo"
      ]
    },
    "expectedVersion": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2147483646
    },
    "groupId": {
      "type": "string",
      "format": "uuid"
    },
    "members": {
      "type": "array",
      "minItems": 2,
      "maxItems": 30,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "tableId",
          "version"
        ],
        "properties": {
          "tableId": {
            "type": "string",
            "format": "uuid"
          },
          "version": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483646
          }
        }
      }
    }
  }
}

POST/api/room/services/{serviceId}/groups

Réunir, séparer ou annuler une opération de groupe. Fournir les versions courantes du groupe et de chaque table.

Accès: Tablette jumelée, avec permission
Permission: tables.join

Paramètres de chemin

{
  "type": "object",
  "required": [
    "serviceId"
  ],
  "properties": {
    "serviceId": {
      "type": "string",
      "format": "uuid"
    }
  }
}

Corps JSON de la requête

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "type",
    "groupId",
    "expectedVersion",
    "primaryTableId",
    "members"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "type": {
      "enum": [
        "join",
        "split",
        "undo_join",
        "undo_split"
      ]
    },
    "groupId": {
      "type": "string",
      "format": "uuid"
    },
    "expectedVersion": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2147483646
    },
    "primaryTableId": {
      "type": "string",
      "format": "uuid"
    },
    "members": {
      "type": "array",
      "minItems": 2,
      "maxItems": 30,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "tableId",
          "version"
        ],
        "properties": {
          "tableId": {
            "type": "string",
            "format": "uuid"
          },
          "version": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483646
          }
        }
      }
    }
  }
}

GET/api/organizations/{organizationId}/venues/{venueId}/vision

Lire les réglages préparatoires du banc caméra. Aucune observation caméra ne pilote le service.

Accès: Session humaine ; MFA selon la route
Permission: venue.view

Préparation expérimentale

Paramètres de chemin

{
  "type": "object",
  "required": [
    "organizationId",
    "venueId"
  ],
  "properties": {
    "organizationId": {
      "type": "string",
      "format": "uuid"
    },
    "venueId": {
      "type": "string",
      "format": "uuid"
    }
  }
}

POST/api/organizations/{organizationId}/venues/{venueId}/vision

Enregistrer les réglages expérimentaux avec planId, revision et config. Aucun flux vidéo ni image n’est accepté.

Accès: Session humaine ; MFA selon la route
Permission: floorplan.edit

Préparation expérimentale

Paramètres de chemin

{
  "type": "object",
  "required": [
    "organizationId",
    "venueId"
  ],
  "properties": {
    "organizationId": {
      "type": "string",
      "format": "uuid"
    },
    "venueId": {
      "type": "string",
      "format": "uuid"
    }
  }
}

Corps JSON de la requête

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "planId",
    "revision",
    "config"
  ],
  "properties": {
    "planId": {
      "type": "string",
      "format": "uuid"
    },
    "revision": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2147483646
    },
    "config": {
      "type": "object"
    }
  }
}

Besoin d’un coup de main ?

Indiquez l’étape qui bloque et le message affiché. Gardez vos mots de passe et codes de connexion privés.

Contacter l’équipe Kelna