Desarrolladores API v1

Endpoints de la API. Especificación exacta de cada operación de la API v1 (parámetros, cuerpo, respuestas y ejemplos), generada del documento OpenAPI con el que se valida cada respuesta real. Los procedimientos completos están en Guías.

POST /waves

Planear una ola

Planea una ola con una lista de surtidos (picking_ids) o con los filtros del planeador (filters). La ola queda planeada; liberarla es decisión de un supervisor en la web.

Alcance (cliente de integración)
pickings:write
Permiso (token de usuario)
exits.manage
Idempotency-Key
Opcional
Requisitos
Módulo de olas

Cabeceras

  • Idempotency-Key string

    Llave única por operación (se recomienda un UUID v4). Reenviar la misma solicitud con la misma llave en las siguientes 24 horas devuelve la respuesta original sin repetir la operación.

Cuerpo de la solicitud application/json

  • warehouse string obligatorio
  • strategy string obligatorio
    Valores: discrete, by_customer, batch, cluster, zone, pick_and_pass
  • picking_ids array de enteros
  • filters objeto
    6 campos de filters
    • carrier string | null
    • customer string | null
    • route string | null
    • zone_id integer | null
    • min_priority integer | null
    • due_by string (date) | null
  • cutoff_id integer | null
  • template_id integer | null

Respuestas

201 Ola planeada. Location apunta al nuevo recurso.
  • data objeto obligatorio
    12 campos de data
    • id integer obligatorio
    • code string obligatorio
    • warehouse_code string | null
    • strategy string obligatorio
      Valores: discrete, by_customer, batch, cluster, zone, pick_and_pass
    • status string obligatorio
      Valores: draft, planned, released, in_progress, picked, completed, closed, cancelled
    • carrier_code string | null
    • cutoff_at string (date-time) | null
    • released_at string (date-time) | null
    • metrics objeto

      Pedidos, líneas, unidades y avance de la ola.

    • created_at string (date-time) | null
    • updated_at string (date-time) | null
    • orders array de objetos

      Solo en el detalle.

      2 campos de orders
      • picking_id integer obligatorio
      • status string obligatorio
401 Falta el token o no es válido.

Cuerpo: el sobre de error.

402 La función no está en el plan de la empresa, o la cuenta está suspendida o cancelada.

Cuerpo: el sobre de error.

403 Al cliente le falta el alcance (missing_scope), al usuario el permiso (forbidden), o el token de usuario no tiene acceso a la ruta (client_not_allowed: aplicación móvil o usuario con verificación en dos pasos).

Cuerpo: el sobre de error.

409 La solicitud choca con el estado actual (por ejemplo, un pedido ya está en otra ola).

Cuerpo: el sobre de error.

422 Datos no válidos (validation_failed), una llave de idempotencia reutilizada con otra solicitud (idempotency_key_reused) o una regla de negocio que bloquea la operación (rule_blocked).

Cuerpo: el sobre de error.

429 Se superó el límite por minuto. Reintente después de los segundos de Retry-After.

Cuerpo: el sobre de error.

Probar

Probar con una instancia

La solicitud sale del navegador hacia la instancia indicada; nada pasa por chainlink.mx. El token se conserva solo en esta pestaña.

Obtener un token con un cliente de integración

Credenciales de Configuración › Clientes API (grant client_credentials). El secreto se usa una vez y no se guarda. Los tokens de usuario se obtienen fuera de la consola; ver Autenticación.

Solicitud 
curl -X POST "https://empresa.chainlink.mx/api/v1/waves" \
  -H "Authorization: Bearer $CHAINLINK_TOKEN" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "warehouse": "CEDIS-GDL",
    "strategy": "batch",
    "filters": {
        "customer": "CLI-001",
        "due_by": "2026-10-07"
    }
}'
Respuesta 
{
    "data": {
        "id": 9,
        "code": "OLA-000009",
        "warehouse_code": "CEDIS-GDL",
        "strategy": "batch",
        "status": "planned",
        "carrier_code": null,
        "cutoff_at": null,
        "released_at": null,
        "metrics": {
            "lines": 3,
            "trips": 0,
            "units": 18,
            "orders": 2,
            "standard_minutes": 1.1
        },
        "created_at": "2026-10-06T10:20:11-06:00",
        "updated_at": "2026-10-06T10:20:11-06:00",
        "orders": [
            {
                "picking_id": 6120,
                "status": "planned"
            },
            {
                "picking_id": 6121,
                "status": "planned"
            }
        ]
    }
}