7. Lokale API - HTTP: het eindpunt /blocked

GET /blocked geeft aan de ECR door welke eindpunten van de lokale API nog een onafgeronde HTTP-uitwisseling bevatten, zodat een resultaat die vóór een crash of een verbroken verbinding werd gestart, kan worden gelezen voordat een nieuwe aanvraag wordt verzonden. Dit artikel legt uit wat het eindpunt rapporteert, wat het niet rapporteert en hoe u het in een herstelprocedure gebruikt.

Wat het rapporteert

De HTTP-server van de terminal voert één uitwisseling uit per asynchroon eindpunt (/payment, /acquisition, /reversal, /update, /balanceinquiry, /giftcard). Een uitwisseling begint wanneer de POST wordt aanvaard (202) en eindigt wanneer de ECR het definitieve antwoord leest met GET: de definitieve respons (200) of, wanneer de Payment Application niet binnen de time-out van het eindpunt heeft geantwoord, een 408. Tot die lezing wordt het eindpunt vermeld door GET /blocked en wordt een nieuwe POST erop geweigerd met 403. Een definitief antwoord blijft wachten tot het wordt gelezen; het vervalt niet en blijft behouden na een herstart van de terminal. Een betaling die door een herstart wordt onderbroken voordat er een resultaat was, laat niets achter op het eindpunt (GET → 423): meld u opnieuw aan en gebruik /status.

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

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

De aanvraag heeft geen body en het antwoord is gewone JSON, zonder Nexo-enveloppe. Via een LAN is het terminaladres het adres dat door het netwerk is toegewezen (bijvoorbeeld 192.168.1.24); via USB-tethering is het 192.168.42.129.

Opmerking

/blocked beschrijft de HTTP-server van de terminal, niet de Payment Application. Het is een alleen-lezenweergave: wanneer u het aanroept, wordt er niets gestart, komt er niets vrij en verandert de status van geen enkele uitwisseling.

Wanneer u het moet aanroepen

Bij het opstarten van de ECR, vóór de eerste verkoop: de vorige sessie kan midden in een betaling zijn beëindigd.
Na een transportfout of een time-out tijdens het pollen van een bewerking.
Wanneer een POST antwoordt met 403 Forbidden: er staat nog een uitwisseling open op dat eindpunt.

Stuur voor elk vermeld eindpunt een kale GET naar dat pad totdat het antwoordt met 200. Die 200 bevat de definitieve respons van de onderbroken bewerking (bijvoorbeeld de PaymentResponse): verwerk die precies alsof ze normaal was ontvangen. De volgende GET /blocked vermeldt het eindpunt niet langer.

`GET` op het vermelde eindpunt antwoordt	Betekenis	Actie van de ECR
`200`	Definitieve respons	Verwerk ze; de uitwisseling is beëindigd.
`201`	Tussenbericht; er is voorlopig niets meer te lezen	Toon het aan de kassier als het een `DisplayRequest` is en blijf pollen.
`204`	Bewerking wordt uitgevoerd; er is nog niets te lezen	Blijf pollen.
`206`	Er wordt een bericht teruggestuurd en er wachten er nog meer	Verwerk het en roep onmiddellijk opnieuw `GET` aan.
`408`	De Payment Application heeft niet geantwoord binnen de time-out van het eindpunt	Door de `408` te lezen, wordt de uitwisseling beëindigd; de bewerking zelf loopt verder op de terminal. `/status` antwoordt met `InProgress` totdat de bewerking eindigt en geeft daarna het resultaat terug. Een nieuwe `POST` die ondertussen wordt verzonden, wordt aanvaard (`202`) maar onmiddellijk beantwoord met `Failure`, `ErrorCondition: Busy`, `TransactionInProgress`.
`423`	Geen open uitwisseling op dit eindpunt	Niets te lezen. Controleer `/status` als u nog een resultaat nodig hebt.

Alleen 200 beëindigt de uitwisseling. Als u stopt bij 204 of 206, blijft het eindpunt geblokkeerd en wordt de volgende POST geweigerd met 403.

Wat het u niet vertelt

Vraag	Waar u het antwoord vindt
Is de terminal vrij om een nieuwe betaling uit te voeren?	`POST /diagnosis`: `POIStatus.GlobalStatus` is `OK` of `Busy`. Dit werkt zonder sessie.
Wat was het resultaat van een uitwisseling die al is beëindigd?	`POST /status`: geeft de laatst voltooide Payment, CardAcquisition of Reversal terug.
Kan ik de terminal geforceerd terug naar inactief brengen?	Geen enkel eindpunt doet dat. Een lopende betaling kan alleen worden geannuleerd met `/abort`; een vastgelopen Payment Application vereist een herstart van de terminal.

Er zijn dus twee verschillende situaties waarin iets “blocked” is, en /blocked ziet alleen de eerste:

Situatie	`GET /blocked`	`POST /diagnosis`	Actie van de ECR
Er staat een HTTP-uitwisseling open (resultaat nog niet gelezen)	Vermeldt het eindpunt	`Busy` terwijl de bewerking loopt, `OK` zodra het resultaat klaar is	Voer `GET` uit op het eindpunt totdat u `200` krijgt.
De Payment Application is bezig zonder open uitwisseling (er werd een `408` gelezen terwijl de bewerking liep, of de applicatie is vastgelopen)	Lege lijst	`Busy` (en `/status` antwoordt met `InProgress`)	Wacht en controleer opnieuw; stuur buiten uw betalingsvenster één `/abort`; als de status `Busy` blijft, beschouw de verkoop als onopgelost en herstart de terminal.

Time-out van het eindpunt

Elk eindpunt heeft zijn eigen time-out in de configuratie van de HTTP-server van de terminal (<Endpoint Name="/payment" TimeoutMillis="180000"/>): 180 sec. voor /payment, hetzelfde op elke terminal. Dit is de tijd die de HTTP-server wacht op de definitieve respons van de Payment Application. Daarna wordt het definitieve antwoord van de uitwisseling 408; het eindpunt blijft in /blocked en weigert nieuwe POST-aanvragen totdat die 408 is gelezen. Houd het betalingsvenster van de ECR onder deze waarde (120 sec. aanbevolen), zodat een normale betaling deze niet bereikt.

Synchrone eindpunten (/login, /logout, /diagnosis, /status, /abort) hebben kortere time-outs en antwoorden met 408 op de POST zelf wanneer de Payment Application niet tijdig reageert, meestal onmiddellijk na het inschakelen terwijl de applicatie nog wordt gestart. Probeer enkele seconden later opnieuw. Terwijl een dergelijke POST in behandeling is, verschijnt het eindpunt in /blocked en antwoordt een tweede POST met 403; er is niets op te halen met GET (405).

Veelgemaakte fouten

/blocked gebruiken als controle van de beschikbaarheid van de terminal. Een lege lijst betekent alleen dat er geen resultaat klaarstaat om te worden gelezen. Gebruik /diagnosis.
/status aanroepen terwijl een eindpunt vermeld staat. /status geeft de vorige voltooide transactie terug, niet de transactie die nog openstaat. Haal eerst alle berichten van het eindpunt op.
/blocked pollen in plaats van het bewerkingseindpunt tijdens een betaling. Poll tijdens een betaling GET /payment; /blocked is bedoeld voor herstel.

Raadpleeg voor de volledige herstellogica (transactiejournal, regels voor ServiceID, consistentiecontrole op /status) het artikel “Dubbele betalingen vanuit de ECR voorkomen”. Hulp nodig? Neem contact op met de ondersteuning van Market Pay via assist.market-pay.com.