7. API locale - HTTP : le point de terminaison /blocked

GET /blocked indique à l’ECR quels points de terminaison de l’API locale contiennent encore un échange HTTP non terminé, afin qu’un résultat commencé avant un plantage ou une perte de connexion puisse être lu avant l’envoi de toute nouvelle requête. Cet article explique ce que le point de terminaison signale, ce qu’il ne signale pas et comment l’utiliser dans une routine de récupération.

Ce qu’il signale

Le serveur HTTP du terminal exécute un échange par point de terminaison asynchrone (/payment, /acquisition, /reversal, /update, /balanceinquiry, /giftcard). Un échange s’ouvre lorsque le POST est accepté (202) et se ferme lorsque l’ECR lit sa réponse finale avec GET : la réponse finale (200) ou, lorsque l’application de paiement n’a pas répondu dans le délai d’attente du point de terminaison, une réponse 408. Jusqu’à cette lecture, le point de terminaison est répertorié par GET /blocked et un nouveau POST sur celui-ci est refusé avec le code 403. Une réponse finale reste en attente jusqu’à sa lecture ; elle n’expire pas et subsiste après le redémarrage du terminal. Un paiement interrompu par un redémarrage avant la production d’un résultat ne laisse rien sur le point de terminaison (GET → 423) : reconnectez-vous et utilisez /status.

GET http://<terminal-ip>:8080/blocked

200 {"blocked":[]}
200 {"blocked":["/payment"]}
200 {"blocked":["/payment","/update"]}

La requête n’a pas de corps et la réponse est au format JSON brut, sans enveloppe Nexo. Sur un réseau local, l’adresse du terminal est celle attribuée par le réseau (par exemple 192.168.1.24) ; en partage de connexion USB, il s’agit de 192.168.42.129.

Remarque

/blocked décrit le serveur HTTP du terminal, et non l’application de paiement. Il s’agit d’une vue en lecture seule : son appel ne déclenche rien, ne libère rien et ne modifie pas l’état d’un échange.

Quand l’appeler

Au démarrage de l’ECR, avant la première vente : la session précédente peut s’être terminée au milieu d’un paiement.
Après une erreur de transport ou un délai d’attente lors de l’interrogation d’une opération.
Lorsqu’un POST répond 403 Forbidden : un échange est toujours ouvert sur ce point de terminaison.

Pour chaque point de terminaison répertorié, envoyez un GET simple sur ce chemin jusqu’à ce qu’il réponde 200. Ce 200 contient la réponse finale de l’opération interrompue (par exemple la PaymentResponse) : traitez-la exactement comme si elle était arrivée normalement. Le prochain GET /blocked ne répertorie plus le point de terminaison.

Réponse du `GET` sur le point de terminaison répertorié	Signification	Action de l’ECR
`200`	Réponse finale	Traitez-la, l’échange est fermé.
`201`	Message intermédiaire, rien d’autre à lire pour le moment	Affichez-le au caissier s’il s’agit d’une `DisplayRequest`, puis continuez l’interrogation.
`204`	Opération en cours, rien à lire pour l’instant	Continuez l’interrogation.
`206`	Un message est renvoyé et d’autres sont en attente	Traitez-le et appelez à nouveau `GET` immédiatement.
`408`	L’application de paiement n’a pas répondu dans le délai d’attente du point de terminaison	La lecture du `408` ferme l’échange ; l’opération elle-même se poursuit sur le terminal. `/status` répond `InProgress` jusqu’à sa fin, puis renvoie son résultat. Un nouveau `POST` envoyé entre-temps est accepté (`202`), mais reçoit immédiatement une réponse `Failure`, `ErrorCondition: Busy`, `TransactionInProgress`.
`423`	Aucun échange ouvert sur ce point de terminaison	Rien à lire. Vérifiez `/status` si vous avez encore besoin d’un résultat.

Seul le code 200 ferme l’échange. S’arrêter sur 204 ou 206 laisse le point de terminaison bloqué et le prochain POST est refusé avec le code 403.

Ce que cela ne vous indique pas

Question	Où trouver la réponse
Le terminal est-il disponible pour accepter un nouveau paiement ?	`POST /diagnosis` : `POIStatus.GlobalStatus` vaut `OK` ou `Busy`. Cela fonctionne sans session.
Quel était le résultat d’un échange déjà fermé ?	`POST /status` : renvoie le dernier paiement, la dernière acquisition de carte ou le dernier retour terminé.
Puis-je forcer le terminal à revenir à l’état inactif ?	Aucun point de terminaison ne permet de le faire. Un paiement en cours peut uniquement être annulé avec `/abort` ; une application de paiement bloquée nécessite un redémarrage du terminal.

Il existe donc deux situations « bloquées » différentes, et /blocked ne détecte que la première :

Situation	`GET /blocked`	`POST /diagnosis`	Action de l’ECR
Un échange HTTP est ouvert (résultat pas encore lu)	Répertorie le point de terminaison	`Busy` pendant l’exécution de l’opération, `OK` une fois le résultat prêt	Effectuez un `GET` du point de terminaison jusqu’à obtenir `200`.
L’application de paiement est occupée sans échange ouvert (un `408` a été lu alors que l’opération était en cours, ou l’application est bloquée)	Liste vide	`Busy` (et `/status` répond `InProgress`)	Attendez et vérifiez à nouveau ; au-delà de votre fenêtre de paiement, envoyez une fois `/abort` ; si l’état reste `Busy`, considérez la vente comme non résolue et redémarrez le terminal.

Délai d’attente du point de terminaison

Chaque point de terminaison possède son propre délai d’attente dans la configuration du serveur HTTP du terminal (<Endpoint Name="/payment" TimeoutMillis="180000"/>) : 180 s pour /payment, sur tous les terminaux. Il s’agit du délai pendant lequel le serveur HTTP attend la réponse finale de l’application de paiement. Une fois ce délai dépassé, la réponse finale de l’échange devient 408 ; le point de terminaison reste dans /blocked et refuse les nouveaux POST jusqu’à ce que ce 408 soit lu. Maintenez la fenêtre de paiement de l’ECR en dessous de cette valeur (120 s recommandé), afin qu’un paiement normal ne l’atteigne jamais.

Les points de terminaison synchrones (/login, /logout, /diagnosis, /status, /abort) ont des délais d’attente plus courts et répondent 408 sur le POST lui-même lorsque l’application de paiement ne répond pas à temps, généralement juste après la mise sous tension, pendant le démarrage de l’application. Réessayez quelques secondes plus tard. Pendant qu’un tel POST est en attente, le point de terminaison apparaît dans /blocked et un second POST répond 403 ; il n’y a rien à lire sur celui-ci avec GET (405).

Erreurs courantes

Utiliser /blocked comme vérification de la disponibilité du terminal. Une liste vide signifie uniquement qu’aucun résultat n’attend d’être lu. Utilisez /diagnosis.
Appeler /status lorsqu’un point de terminaison est répertorié. /status renvoie la transaction terminée précédente, et non celle qui est encore ouverte. Traitez d’abord le point de terminaison.
Interroger /blocked au lieu du point de terminaison de l’opération pendant un paiement. Pendant un paiement, interrogez GET /payment ; /blocked est destiné à la récupération.

Pour connaître la logique complète de récupération (journal des transactions, règles relatives à ServiceID, contrôle de cohérence sur /status), consultez l’article « Empêcher les paiements en double depuis l’ECR ». Besoin d’aide ? Contactez l’assistance Market Pay à l’adresse assist.market-pay.com.