ApiBorne
Sommaire du guide

Services offerts par le serveur

Le contrat couvre les appels de la borne vers vous. Le serveur ApiBorne offre en retour des services que votre système appelle : c'est ce qui garde le Cockpit et la numérotation des tickets synchrones avec votre agenda quand la configuration des bornes est portée par ApiBorne.

Principe

Ces services vivent sur le serveur ApiBorne (pas chez vous), sous {apiborneServerUrl}/api/kioskTicket/…. Ils sont le miroir des routes de communication : la borne crée des tickets chez ApiBorne au check-in, votre agenda fait de même quand une arrivée est pointée à la main — une seule séquence de numérotation pour tout le monde.

Séquence : une arrivée pointée dans l'agenda obtient son ticket d'ApiBorne, puis chaque changement de statut est poussé et reflété au Cockpit.Votre systèmeagendaServeur ApiBorneCockpitécrans d'accueilArrivée pointée à la mainissueForAppointment (requestUid unique){ "number": 12, "formattedNumber": "SC-12" }ticket visiblemême séquence que les check-ins borneChangement d'état du RDVappointmentStatusChanged (fire-and-forget)événement temps réelagenda reflété en ~1–2 sÉchec d'un appel ? On logge, on continue.Repli en numérotation locale — le flux métier ne bloque jamais
Le sens inverse du contrat : votre système appelle les services du serveur ApiBorne — toujours en best-effort.

Comment appeler ces services

  1. URL de base : le serveur ApiBorne, communiqué à l'installation ;
  2. Auth : header Authorization = la clé d'autorisation compte brute (pas de préfixe Bearer) — la même clé que X-Kiosk-Auth-Key, affichée dans l'admin ApiBorne, page Connectivité ;
  3. Licence cible dans le corps : licenceUuid — l'UUID de la licence, affiché dans l'admin ApiBorne (page Connectivité) et reporté chez vous à l'installation, comme la clé. Suffisant et non ambigu ;
  4. RDV concerné : contractAppointmentId, l'identifiant tel qu'exposé sur le contrat.
socle de payload
{
  "licenceUuid": "ecdb8b76-…",          // LA licence cible — copiez-le depuis l'admin ApiBorne, page Connectivité
  "contractAppointmentId": "1001~8f3a…" // id contrat du RDV concerné
}
Ne confondez pas les deux : la clé authentifie (header Authorization — c'est un secret), le licenceUuid désigne la licence cible (c'est un identifiant, pas un secret) — nécessaire car plusieurs licences peuvent partager la même clé.
N'envoyez que le licenceUuid : le serveur accepte d'autres champs d'identification pour ses intégrations historiques, mais tout identifiant fourni est vérifié — un champ superflu ou obsolète fait rejeter l'appel.

Les 5 services

POST /api/kioskTicket/issueForAppointment

Une arrivée est pointée dans VOTRE agenda : demandez le numéro de ticket à ApiBorne (séquence partagée avec les check-ins borne).

POST /api/kioskTicket/appointmentStatusChanged

À chaque changement d'état d'un RDV : le Cockpit reflète votre agenda en 1 à 2 secondes.

POST /api/kioskTicket/cancelForAppointment

L'accueil doit être refait : annulez les tickets du jour du RDV, ils disparaissent du Cockpit.

POST /api/kioskTicket/getCheckinNotifySettings

Lisez les réglages « Accueil RIS » gérés dans l'admin ApiBorne (conditions de notification).

POST /api/kioskTicket/printTicket

Demandez la réimpression d'un ticket sur une borne du lieu (guichet, poste d'accueil).

Best-effort, toujours

Ne bloquez jamais votre flux métier sur un échec de push : timeout court (8 s dans la démo), échecs loggés et avalés, repli en numérotation locale pour issueForAppointment. Le client de référence : src/server/apiborne/client.ts.

Swagger à télécharger

Les services du serveur ont leur propre spécification OpenAPI (schémas de requête et de réponse, sécurité, exemples) :

Télécharger openapi-server.yamlTélécharger openapi-server.json