Postes

L’agent s’installe sur le poste du cabinet, à côté des lecteurs. Il n’ouvre que des connexions sortantes : rien n’écoute au cabinet, aucun port n’est à ouvrir. Il dit à Ophelix quels lecteurs sont branchés et quelles cartes sont insérées. Le tableau de bord et vos webhooks le savent ainsi en continu.

Ophelix apprend qu’une carte est là et de quel genre, cps, vitale ou unknown. Jamais à qui elle est : ni NIR ni identité ne remontent par ce canal.

Un poste est un Workstation, ws_…, et son code d’appairage un WorkstationPairingCode, wpc_…. Droits de clé : workstations:read et workstations:write.

Je veux…

Je veux…	Appel
Créer un code d’appairage	`POST /v1/workstation-pairing-codes`
Suivre un code	`GET /v1/workstation-pairing-codes/{id}`
Retirer un code	`POST /v1/workstation-pairing-codes/{id}/cancel`
Reprendre un poste à une autre organisation	`POST /v1/workstation-pairing-codes/{id}/confirm-transfer`
Lister les postes	`GET /v1/workstations`
Lire un poste	`GET /v1/workstations/{id}`
Renommer un poste	`PATCH /v1/workstations/{id}`
Révoquer un poste	`POST /v1/workstations/{id}/revoke`

Appairer un poste

Créez un code, dans le tableau de bord ou par l’API :


curl -X POST https://api.ophelix.fr/v1/workstation-pairing-codes \
  -H "Authorization: Bearer sk_test_…"


{
  "id": "wpc_…",
  "object": "workstation_pairing_code",
  "code": "RB7K-4Q2M",
  "status": "pending",
  "stage": "waiting",
  "expires_at": 1793970654,
  "workstation": null,
  "created": 1793970054,
  "livemode": false
}

Le code vaut dix minutes et une seule fois, dans le mode de la clé. Il se saisit avec ou sans tiret, en casse libre. code ne se rend qu’ici. Ensuite, status vaut pending, paired, expired ou cancelled, et workstation devient l’objet avec expand[]=workstation.

Suivre un code

Tant que status vaut pending, stage dit où en est le poste. Il est vide pour tout autre statut.

`stage`	Sens	Quoi faire
`waiting`	Le code n’a pas été saisi	Attendre
`connecting`	Le code a été saisi sur le poste, la personne confirme	Attendre
`stalled`	L’agent se tait depuis 90 secondes après la saisie	Vérifier le réseau du poste. L’état repart si l’agent revient
`agent_outdated`	L’agent est trop ancien	Le mettre à jour : `agent.minimum_version` dit le minimum
`already_paired`	Le poste appartient déjà à une organisation, nommée par `current_organization`	Confirmer le rattachement, ou annuler le code

stalled se déduit du silence de l’agent : il peut aussi dire que la personne n’a pas encore confirmé. agent porte ce que l’agent a dit de lui en présentant le code. Il est vide avant la saisie.

Confirmer un rattachement ne retire rien : le poste quitte son organisation quand l’agent termine l’appairage, et elle reçoit alors workstation.revoked.

Suivre les postes

Un poste est online tant qu’il a parlé il y a moins de 45 secondes. status vaut online, offline ou revoked. readers est son dernier état :


[
  {
    "name": "Lecteur bi-fente",
    "slots": [
      { "index": 0, "reader_name": "Lecteur bi-fente 00", "card": { "kind": "cps" } },
      { "index": 1, "reader_name": "Lecteur bi-fente 01", "card": null }
    ]
  }
]

last_card_at est le dernier état remonté avec une carte présente. state_reported_at est le dernier état reçu : vide juste après l’appairage, il dit que readers n’a encore rien appris. agent_status vaut up_to_date, update_available ou outdated.

Révoquer

La révocation vaut à la requête suivante, sans délai de grâce. L’agent reçoit alors workstation_revoked et revient à l’appairage. Révoquer deux fois ne change rien. Un poste révoqué le reste : pour le réutiliser, appairez-le avec un nouveau code.

Relais de webhooks

Sur un poste de test, l’écran Webhooks de l’agent transmet les événements à votre serveur local, sur localhost, 127.0.0.1 ou [::1] seulement. C’est une connexion sortante de plus, vers votre propre machine : l’agent n’ouvre toujours aucun port, et il ne suit aucune redirection.

L’en-tête Ophelix-Signature est celui d’une vraie livraison, avec le secret whsec_… du poste, que l’écran permet de copier. Voir Webhooks. Rejouer renvoie le même événement, même identifiant et même corps, avec un horodatage neuf. Le relais commence à son ouverture, sans rejouer l’historique.

Événements

Type	Quand	Charge, en plus de `id` et `object`
`workstation.paired`	Un code devient un poste	`name`
`workstation.revoked`	Le poste est révoqué ou se désappaire	`name`
`reader.connected`	Un lecteur apparaît	`reader`
`reader.disconnected`	Un lecteur disparaît	`reader`
`card.inserted`	Une carte entre dans une fente	`reader`, `slot`, `kind`
`card.removed`	Une carte sort d’une fente	`reader`, `slot`, `kind`

id est celui du poste et object vaut workstation. Un état inchangé n’émet rien. Une carte retirée sort avant que son lecteur ne parte, et une carte d’un lecteur branché entre après lui. Une carte remplacée entre deux états est un card.removed puis un card.inserted.

Pièges

Un poste qui se tait n’émet rien. Surveillez online, pas les événements, pour savoir s’il est joignable.
Test et production sont séparés. Un poste appairé par un code de test n’existe que pour les clés de test.
La création d’un code ignore Idempotency-Key. Deux appels donnent deux codes, dont un expirera seul.
Un code qui a servi ou expiré ne s’annule plus : 409 conflict.