7. API local - HTTP: el endpoint /blocked

GET /blocked indica al ECR qué endpoints de la API local todavía tienen un intercambio HTTP sin finalizar, para que un resultado iniciado antes de un bloqueo o una pérdida de conexión pueda leerse antes de enviar una nueva solicitud. En este artículo se explica qué informa el endpoint, qué no informa y cómo usarlo en una rutina de recuperación.

Qué informa

El servidor HTTP del terminal ejecuta un intercambio por cada endpoint asíncrono (/payment, /acquisition, /reversal, /update, /balanceinquiry, /giftcard). Un intercambio se abre cuando se acepta el POST (202) y se cierra cuando el ECR lee su respuesta final con GET: la respuesta final (200) o, cuando la aplicación de pago no respondió dentro del tiempo de espera del endpoint, un 408. Hasta esa lectura, el endpoint aparece en GET /blocked y se rechaza un nuevo POST en él con 403. Una respuesta final espera hasta que se lee; no caduca y sobrevive al reinicio del terminal. Un pago interrumpido por un reinicio antes de producir un resultado no deja nada en el endpoint (GET → 423): vuelva a iniciar sesión y use /status.

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

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

La solicitud no tiene cuerpo y la respuesta es JSON simple, sin una envoltura Nexo. En una LAN, la dirección del terminal es la asignada por la red (por ejemplo, 192.168.1.24); mediante tethering USB es 192.168.42.129.

Cuándo llamarlo

• Al iniciar el ECR, antes de la primera venta: la sesión anterior puede haber terminado en mitad de un pago.
• Después de un error de transporte o un tiempo de espera agotado mientras se sondea una operación.
• Cuando un POST responde 403 Forbidden: todavía hay un intercambio abierto en ese endpoint.

Para cada endpoint incluido en la lista, envíe un GET sin cuerpo a esa ruta hasta que responda 200. Ese 200 contiene la respuesta final de la operación interrumpida (por ejemplo, el PaymentResponse): procésela exactamente como si hubiera llegado normalmente. El siguiente GET /blocked ya no incluirá el endpoint.

Solo 200 cierra el intercambio. Detenerse en 204 o 206 deja el endpoint bloqueado y el siguiente POST se rechaza con 403.

Qué no informa

Por lo tanto, hay dos situaciones diferentes de «bloqueo», y /blocked solo detecta la primera:

Tiempo de espera del endpoint

Cada endpoint tiene su propio tiempo de espera en la configuración del servidor HTTP del terminal (<Endpoint Name="/payment" TimeoutMillis="180000"/>): 180 s para /payment, el mismo en todos los terminales. Es el tiempo que el servidor HTTP espera la respuesta final de la aplicación de pago. Una vez transcurrido, la respuesta final del intercambio se convierte en 408; el endpoint permanece en /blocked y rechaza nuevos POST hasta que se lea ese 408. Mantenga el tiempo de pago del ECR por debajo de este valor (se recomiendan 120 s) para que un pago normal nunca llegue a ese límite.

Los endpoints síncronos (/login, /logout, /diagnosis, /status, /abort) tienen tiempos de espera más cortos y responden 408 en el propio POST cuando la aplicación de pago no responde a tiempo, normalmente justo después de encender el dispositivo, mientras la aplicación todavía se está iniciando. Vuelva a intentarlo unos segundos después. Mientras dicho POST está pendiente, el endpoint aparece en /blocked y un segundo POST responde 403; no hay nada que leer en él con GET (405).

Errores comunes

• Usar /blocked como comprobación de disponibilidad del terminal. Una lista vacía solo significa que no hay ningún resultado esperando para ser leído. Use /diagnosis.
• Llamar a /status mientras un endpoint aparece en la lista. /status devuelve la transacción completada anteriormente, no la que sigue abierta. Vacíe primero el endpoint.
• Sondear /blocked en lugar del endpoint de la operación durante un pago. Durante un pago, sondee GET /payment; /blocked es para la recuperación.

Para consultar la lógica completa de recuperación (diario de transacciones, reglas de ServiceID, comprobación de coherencia en /status), consulte el artículo «Evitar pagos duplicados desde el ECR». ¿Necesita ayuda? Póngase en contacto con el servicio de asistencia de Market Pay en assist.market-pay.com.