Démarrage rapide

La borne appelle directement votre serveur pendant le parcours patient, sur un base path imposé par le contrat :

{votre-serveur}/api/apiborneIntegrationService/v1/

JSON en camelCase anglais, dates ISO 8601 (birthDate en YYYY-MM-DD, startDate avec offset de fuseau), identifiants opaques (chaînes ≤ 128 caractères, stables pendant tout un parcours).

L'intégration complète tient en trois familles, chacune avec son swagger :

1. Routes de communication — les 12 opérations que la borne appelle chez vous pendant le parcours patient (identification, documents, check-in…). Auth : les deux headers X-Kiosk-Auth-Key + X-Kiosk-Device-Id. Swagger : openapi.yaml.
2. Routes de configuration — les 6 GET que le serveur ApiBorne appelle chez vous pour lire vos référentiels (lieux, examens, praticiens, salles, types de documents) et valider l'intégration (sonde sur les 5 premiers). Auth : la clé seule. Swagger : openapi-config.yaml.
3. Services offerts par le serveur — les routes que votre système appelle sur le serveur ApiBorne (ticket d'une arrivée agenda, statuts de RDV, annulation, réglages d'accueil, réimpression). Auth : header Authorization = la clé brute. Swagger : openapi-server.yaml.

Toutes les requêtes de la borne portent deux headers :

X-Kiosk-Auth-Key: <clé partagée>
X-Kiosk-Device-Id: <identifiant du device>

Validez le device d'abord (401 UNKNOWN_DEVICE), puis la clé (401 INVALID_AUTH_KEY). Un 401 ne doit jamais devenir une redirection vers une page de login. La borne étant une application navigateur, le CORS est obligatoire — détails dans le guide Authentification.

Les 12 routes du contrat sont toutes obligatoires — mais une borne exécute un parcours de check-in complet avec ces cinq-là. Implémentez-les en premier.

Les autres opérations (modification patient, documents, prescripteur, statut, connexion du personnel) sont obligatoires aussi, mais leur implémentation minimale tient en quelques lignes si vous n'avez pas la fonctionnalité : liste de documents vide (la borne saute le flow), 204 sans effet, 404 systématique pour les codes de convocation, 401 pour la connexion du personnel. Pas de routes optionnelles, pas de déclaration de support : la configuration ApiBorne reste sans exception.

Variables communes à tous les exemples du guide :

BASE='https://ris.example.com/api/apiborneIntegrationService/v1'
AUTH=(-H 'X-Kiosk-Auth-Key: s3cr3t-key' -H 'X-Kiosk-Device-Id: KIOSK-042' -H 'Content-Type: application/json')

L'identification combine tous les critères fournis (le NIR prime quand il est présent, en tolérant les espaces). Aucun résultat n'est pas une erreur : répondez 200 avec patients: [].

curl -sS "$BASE/patients/identify" "${AUTH[@]}" -d '{
  "context": { "locationId": "loc-42", "config": { "identification": { "twoFieldsIdentification": true } } },
  "criteria": { "socialSecurityId": "280057510612345", "lastName": "DURAND", "firstName": "MARIE", "birthDate": "1980-05-12" }
}'

L'opération critique du parcours. Deux règles à retenir dès le départ : le check-in doit être idempotent (un rejeu réseau renvoie 200 avec le ticket existant), et le proposedTicket envoyé par la borne doit être accepté sans erreur — l'adopter comme numéro d'appel est la meilleure pratique.

curl -sS "$BASE/appointments/apt-1001/check-in" "${AUTH[@]}" -d '{
  "identifiedWithHealthCard": true,
  "attendantCheckIn": false,
  "anomalyCodes": [],
  "sequence": { "number": 1, "count": 1 },
  "proposedTicket": { "number": 12, "formattedNumber": "SC-12" }
}'
# → 200 { "ticketNumber": 12, "ticketNumberFormatted": "SC-12" }

Sémantique complète (multi-RDV, anomalies, erreurs) sur la page référence check-in.

Le repo open-source ApiborneDemoImpl implémente tout le contrat dans un mini système de gestion médical Next.js + SQLite : idéal pour comparer vos réponses aux siennes, route par route.

git clone https://github.com/ApiBorne/ApiborneDemoImpl.git
cd ApiborneDemoImpl
npm install
npm run dev   # implémentation de référence sur http://localhost:3020

• Le parcours borne en 7 étapes — l'ordre réel des appels pendant un accueil.
• Erreurs et politique de retry — indispensables avant d'écrire le moindre handler.
• Routes de configuration — sondées par ApiBorne pour valider votre intégration : implémentez-les tôt.
• Check-list de conformité — à dérouler avant la mise en production.