Consultar Enlaces de Múltiples Paradas

Descripción

Devuelve, en una sola llamada, los solicitudes de pago activas (derivados de sesiones pending) para varias Paradas (stop_id).

Incluye paginación por Parada, filtros básicos y posibilidad de limitar campos para reducir payload.

¿Por qué POST para "leer"? Acepta listas grandes de stop_id (hasta 200) y tokens de paginación por Parada; un GET se quedaría corto por límites de longitud de URL. Este patrón es común en APIs modernas (Google Cloud, AWS) para queries complejas.

Características:

Optimizado para UI cliente - devuelve solo activos por defecto (status=pending)
Paginación cursor-based por parada
Rate limit: 100 requests/minuto por comercio
Máximo: 200 stop_ids por request

Notas importantes:

Si necesitas histórico, usa status: "historical" o include_history: true en el request
Para más de 200 stops, realiza múltiples requests
Este endpoint es idempotente (lectura) y cacheable

Endpoint

POST /api/v1/ext/payment-stops/payment-sessions/query

Autenticación Requerida

Bearer / Token: BearerAuth

Requiere el uso de el token obtenido en /auth/login

Esquema: bearer (JWT)

Request

Ejemplos de Body (JSON)

Consulta simple (solo activos)

{
  "stop_ids": [
    "stp_111",
    "stp_222",
    "stp_333"
  ]
}

Con paginación y campos mínimos

{
  "stop_ids": [
    "stp_111",
    "stp_222"
  ],
  "per_stop": {
    "page_size": 20,
    "sort": "created_at",
    "order": "desc",
    "only_fields": [
      "session_id",
      "payment_url",
      "expires_at"
    ]
  }
}

Reanudación por Parada (usando next_cursor previo)

{
  "stop_ids": [
    "stp_111",
    "stp_222",
    "stp_333"
  ],
  "per_stop": {
    "cursor_by_stop": {
      "stp_111": "cur_aaa",
      "stp_333": "cur_ccc"
    },
    "page_size": 50
  }
}

Responses

Consulta procesada exitosamente

Response Headers

X-Total-Stops

Número total de paradas consultadas

X-RateLimit-Limit

Límite de requests por ventana

X-RateLimit-Remaining

Requests restantes en la ventana actual

X-RateLimit-Reset

Timestamp Unix cuando se resetea el límite