7. API locale - HTTP: l'endpoint /blocked

GET /blocked indica all'ECR quali endpoint dell'API locale hanno ancora uno scambio HTTP incompleto, in modo che un risultato avviato prima di un arresto anomalo o di una perdita di connessione possa essere letto prima dell'invio di una nuova richiesta. Questo articolo spiega cosa segnala l'endpoint, cosa non segnala e come utilizzarlo in una procedura di ripristino.

Cosa segnala

Il server HTTP del terminale esegue uno scambio per ogni endpoint asincrono (/payment, /acquisition, /reversal, /update, /balanceinquiry, /giftcard). Uno scambio si apre quando il POST viene accettato (202) e si chiude quando l'ECR legge la risposta finale con GET: la risposta finale (200) oppure, quando l'applicazione di pagamento non ha risposto entro il timeout dell'endpoint, un 408. Fino a quel momento, l'endpoint viene elencato da GET /blocked e un nuovo POST su di esso viene rifiutato con 403. Una risposta finale attende di essere letta; non scade e sopravvive al riavvio del terminale. Un pagamento interrotto da un riavvio prima che producesse un risultato non lascia nulla sull'endpoint (GET → 423): effettuare nuovamente il login e utilizzare /status.

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

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

La richiesta non ha un corpo e la risposta è in JSON semplice, senza un envelope Nexo. Su una LAN, l'indirizzo del terminale è quello assegnato dalla rete (ad esempio 192.168.1.24); tramite tethering USB è 192.168.42.129.

Nota

/blocked descrive il server HTTP del terminale, non l'applicazione di pagamento. È una visualizzazione di sola lettura: chiamarlo non attiva né libera nulla e non modifica lo stato di alcuno scambio.

Quando chiamarlo

All'avvio dell'ECR, prima della prima vendita: la sessione precedente potrebbe essersi conclusa nel mezzo di un pagamento.
Dopo un errore di trasporto o un timeout durante il polling di un'operazione.
Quando un POST risponde 403 Forbidden: su quell'endpoint è ancora aperto uno scambio.

Per ogni endpoint elencato, inviare un GET senza corpo su quel percorso finché non risponde 200. Quel 200 contiene la risposta finale dell'operazione interrotta (ad esempio la PaymentResponse): elaborarla esattamente come se fosse arrivata normalmente. Il successivo GET /blocked non elenca più l'endpoint.

`GET` sull'endpoint elencato risponde	Significato	Azione dell'ECR
`200`	Risposta finale	Elaborarla; lo scambio è chiuso.
`201`	Messaggio intermedio, per ora non c'è altro da leggere	Mostrarlo all'operatore di cassa se è una `DisplayRequest`, continuare il polling.
`204`	Operazione in corso, non c'è ancora nulla da leggere	Continuare il polling.
`206`	Viene restituito un messaggio e ce ne sono altri in attesa	Elaborarlo e chiamare nuovamente `GET` subito.
`408`	L'applicazione di pagamento non ha risposto entro il timeout dell'endpoint	La lettura del `408` chiude lo scambio; l'operazione continua sul terminale. `/status` risponde `InProgress` fino al termine, quindi restituisce il risultato. Un nuovo `POST` inviato nel frattempo viene accettato (`202`), ma riceve immediatamente una risposta `Failure`, `ErrorCondition: Busy`, `TransactionInProgress`.
`423`	Nessuno scambio aperto su questo endpoint	Non c'è nulla da leggere. Controllare `/status` se è ancora necessario un risultato.

Solo 200 chiude lo scambio. Interrompere su 204 o 206 lascia l'endpoint bloccato e il successivo POST viene rifiutato con 403.

Cosa non comunica

Domanda	Dove si trova la risposta
Il terminale è libero di accettare un nuovo pagamento?	`POST /diagnosis`: `POIStatus.GlobalStatus` è `OK` o `Busy`. Funziona senza sessione.
Qual è stato il risultato di uno scambio già chiuso?	`POST /status`: restituisce l'ultimo Payment, CardAcquisition o Reversal completato.
È possibile riportare forzatamente il terminale allo stato inattivo?	Nessun endpoint lo consente. Un pagamento in corso può essere annullato solo con `/abort`; un'applicazione di pagamento bloccata richiede il riavvio del terminale.

Esistono quindi due situazioni diverse di "blocco" e /blocked rileva solo la prima:

Situazione	`GET /blocked`	`POST /diagnosis`	Azione dell'ECR
Uno scambio HTTP è aperto (il risultato non è ancora stato letto)	Elenca l'endpoint	`Busy` mentre l'operazione è in corso, `OK` quando il risultato è pronto	Eseguire `GET` sull'endpoint fino a `200`.
L'applicazione di pagamento è occupata senza uno scambio aperto (è stato letto un `408` mentre l'operazione era in corso oppure l'applicazione è bloccata)	Elenco vuoto	`Busy` (e `/status` risponde `InProgress`)	Attendere e controllare nuovamente; oltre la finestra di pagamento, inviare un solo `/abort`; se è ancora `Busy`, considerare la vendita non risolta e riavviare il terminale.

Timeout dell'endpoint

Ogni endpoint ha un timeout specifico nella configurazione del server HTTP del terminale (<Endpoint Name="/payment" TimeoutMillis="180000"/>): 180 s per /payment, lo stesso su ogni terminale. È il tempo durante il quale il server HTTP attende la risposta finale dell'applicazione di pagamento. Trascorso questo tempo, la risposta finale dello scambio diventa 408; l'endpoint rimane in /blocked e rifiuta i nuovi POST fino alla lettura di quel 408. Mantenere la finestra di pagamento dell'ECR al di sotto di questo valore (120 s consigliati), in modo che un pagamento normale non lo raggiunga.

Gli endpoint sincroni (/login, /logout, /diagnosis, /status, /abort) hanno timeout più brevi e rispondono 408 direttamente sul POST quando l'applicazione di pagamento non risponde in tempo, in genere subito dopo l'accensione, mentre l'applicazione è ancora in fase di avvio. Riprovare dopo alcuni secondi. Mentre tale POST è in sospeso, l'endpoint appare in /blocked e un secondo POST risponde 403; non c'è nulla da leggere su di esso con GET (405).

Errori comuni

Utilizzare /blocked come controllo della disponibilità del terminale. Un elenco vuoto significa solo che non ci sono risultati in attesa di essere letti. Utilizzare /diagnosis.
Chiamare /status mentre un endpoint è elencato. /status restituisce la transazione completata precedente, non quella ancora aperta. Svuotare prima l'endpoint.
Eseguire il polling di /blocked invece dell'endpoint dell'operazione durante un pagamento. Durante un pagamento, eseguire il polling di GET /payment; /blocked serve per il ripristino.

Per la logica completa di ripristino (registro delle transazioni, regole ServiceID, controllo di coerenza su /status), consultare l'articolo "Impedire pagamenti duplicati dall'ECR". Serve aiuto? Contattare l'assistenza Market Pay all'indirizzo assist.market-pay.com.