Paginación

Los endpoints de colección (getHistory, consultas tipo lista) retornan resultados paginados. Esta página especifica el contrato.

Inicio rápido

curl -X POST "https://sandbox-api.ariari.xyz/api/v1/fxorder/getHistory" \
  -H "Ocp-Apim-Subscription-Key: $SU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "pageSize": 50,
    "start_date": "2026-04-01",
    "end_date": "2026-04-30"
  }'

Respuesta:

{
  "items": [ /* ...hasta pageSize ítems, ordenados por created_at desc... */ ],
  "page": 1,
  "page_size": 50,
  "total_items": 137
}

Forma de la solicitud — POST con cuerpo JSON

La API M2M de ARi usa POST con cuerpo JSON para consultas de colección, no GET con parámetros de query string. Esto aplica a cada endpoint estilo getHistory y a búsquedas multi-criterio.

Razones:

• Filtros de fecha, filtros de estado, y consultas con alcance por cliente pueden tener muchos parámetros; las query strings se vuelven incómodas rápido y chocan con límites de longitud de URL en proxies.
• Algunas consultas toman formas de filtro que no serializan limpiamente a formato URL (p. ej. cláusulas IN, arrays de rangos).
• Los cuerpos POST no se registran en texto plano en logs de acceso de proxy como sí lo hacen las query strings; para consultas con customer_id de socio esto es higiene de privacidad incidental.

Si está integrando desde una herramienta que por defecto usa GET (one-liners de cURL, etc.), use -X POST + -d. Si su herramienta construye GETs con plantillas URL, cambie a POST con cuerpo JSON para consultas de colección.

Campos de paginación

Notas:

• Los campos de solicitud son camelCase (pageSize); los campos de respuesta son snake_case (page_size). Esto refleja la convención de cable más amplia del BFF — el cuerpo de solicitud usa la forma del DTO validado; el cuerpo de respuesta normaliza a snake_case.
• total_items refleja el conjunto de resultados filtrado, no la tabla completa. Los filtros lo reducen.
• El orden por defecto es created_at desc (más reciente primero) salvo que el endpoint especifique lo contrario. Algunos endpoints aceptan un campo explícito sort_by — vea la referencia del endpoint.

Filtros de fecha

La mayoría de endpoints estilo getHistory aceptan start_date + end_date opcionales:

La semántica de fechas está basada en UTC. start_date: "2026-04-01" coincide con registros desde 2026-04-01T00:00:00.000Z en adelante.

Omitir tanto start_date como end_date retorna el historial completo que coincide con otros filtros. Algunos endpoints tienen una ventana máxima de retroceso del lado del servidor (p. ej. 90 días) por rendimiento — vea la referencia del endpoint.

Iterar todas las páginas

import requests

page = 1
all_items = []
while True:
    response = requests.post(
        "https://sandbox-api.ariari.xyz/api/v1/fxorder/getHistory",
        headers={
            "Ocp-Apim-Subscription-Key": SU_CLAVE,
            "Content-Type": "application/json",
        },
        json={"page": page, "pageSize": 100, "start_date": "2026-04-01"},
    )
    response.raise_for_status()
    body = response.json()
    all_items.extend(body["items"])
    if page * body["page_size"] >= body["total_items"]:
        break
    page += 1

Patrones recomendados del lado cliente:

1. Limite pageSize a 100. El máximo se aplica del lado del servidor; solicitar pageSize: 1000 retorna 422.
2. Detenga cuando page * page_size >= total_items. No sondee una página vacía — items será [] pero el ida y vuelta se desperdicia.
3. No dependa de total_items para invariantes. Puede cambiar entre llamadas si se colocan nuevas órdenes concurrentemente. Trátelo como una pista, no una constante.
4. Persista items durablemente conforme avanza. Bucles de iteración largos sobre un historial de un millón de filas tendrán hipos de red; guardar incrementalmente le permite reanudar desde la última página exitosa en lugar de reiniciar.

Consideraciones de rendimiento

• Ventanas pequeñas: pageSize: 10 a pageSize: 50 es el punto óptimo para consultas interactivas de baja latencia (paneles de operador, actualizaciones de UI en tiempo real). Los tiempos de respuesta del servidor son típicamente <200ms p95 en este rango.
• Exportación masiva: pageSize: 100 minimiza ida y vueltas. Para exportaciones grandes, use filtros de fecha para fragmentar por mes/trimestre en lugar de paginar a través de años.
• Costo del conteo total: total_items requiere que el servidor ejecute una consulta COUNT además del corte de la página. Para ventanas filtradas muy grandes (>100K filas), esto puede agregar latencia notable. Si no necesita el total, use un pageSize artificialmente pequeño e ignore total_items.

Migración a paginación por keyset (futuro)

Para colecciones con millones de filas, la paginación basada en OFFSET (page * pageSize) se vuelve ineficiente — la base de datos escanea las filas saltadas. Versiones futuras de ARi pueden introducir paginación por keyset (basada en cursor) como alternativa opt-in, particularmente para endpoints getHistory de alto volumen.

Cuando eso se entregue, el contrato será aditivo — la forma existente page / pageSize continúa funcionando; los socios pueden adoptar un campo cursor en la solicitud cuando estén listos. Anunciaremos vía Registro de cambios con al menos 30 días de aviso.

Vea también

• Autenticación — configuración de clave de suscripción + ID de correlación
• Idempotencia — solo relevante para endpoints que cambian estado, pero léala junto si está construyendo lógica robusta de reintentos
• Órdenes FX, Transferencias, Broker — campos de filtro específicos del endpoint que se componen con paginación