Documentación.

Solo los hitos del envío: registrado, origen, tránsito, demora, destino, entregado, reparto. Es el mismo objeto status que ya trae GET /v1/tracking — úsalo cuando solo necesitas refrescar el estado y ya tienes el ose_id.

{
  "registrado": { "fecha": "2026-04-15 09:12:30" },
  "origen":     { "fecha": "2026-04-15 09:12:30" },
  "transito":   { "fecha": "2026-04-15 14:08:21", "completo": true,
                  "cargueros": ["964724", "964583", "966345"], "carguero": "966345" },
  "demora":     null,
  "destino":    { "fecha": "2026-04-16 01:01:03", "completo": true },
  "entregado":  { "fecha": "2026-04-16 11:40:45" },
  "reparto":    null
}

Comprobante de la orden.

Enlace a la Guía de Remisión del Transportista. Un envío puede pasar por varios cargueros (transportistas) y cada uno emite su propio GRT — por eso el cap_id es obligatorio.

curl -H "X-API-Key: tu-api-key" \
  "https://api.shalom-api-peru.com/v1/tracking/584210/grt?cap_id=898441"

{
  "enlace": "https://..."
}

Webhooks de tracking

En vez de pollear GET /v1/tracking cada pocos minutos, suscribes los envíos que te importan y nosotros te empujamos un POST a tu servidor cuando cambian de estado. Menos trabajo para ti, y no gastas cuota consultando envíos que no se movieron.

Registra (o actualiza) la URL a la que te empujamos los eventos. La URL debe ser https y pública — rechazamos localhost e IPs internas por seguridad. En el alta te devolvemos el signing_secret una sola vez: guárdalo, lo necesitas para verificar la firma.

curl -X PUT https://api.shalom-api-peru.com/v1/webhooks \
  -H "X-API-Key: tu-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://mi-servidor.com/webhooks/shalom" }'

{
  "url": "https://mi-servidor.com/webhooks/shalom",
  "enabled": true,
  "verified": true,
  "created": true,
  "signing_secret": "9f8b1c...guarda-este-secreto-de-64-hex...a2"
}

Verificación de propiedad (importante)

Al registrar, te mandamos un evento webhook.ping firmado con un data.challenge. Tu endpoint debe responder 2xx devolviendo ese challenge en el body. Hasta que lo haga, el webhook queda deshabilitado ("verified": false) y no entregamos nada. Esto confirma que controlas la URL — evita que alguien apunte el webhook a un servidor ajeno.

Responde el ping sin exigir la firma. El ping viene firmado, pero en el alta te llega antes de que tengas el signing_secret (te lo devolvemos en la respuesta de ese mismo PUT). Si tu handler verifica la firma antes de mirar el tipo de evento, rechaza el ping y el webhook queda deshabilitado. Devolver el challenge no expone nada; la firma verifícala en el resto de eventos (ver Verificar la firma).

// Al registrar, te mandamos un webhook.ping firmado con un challenge.
// Tu endpoint debe DEVOLVER ese challenge en el body (2xx) para habilitarse.
// Respóndelo SIN exigir la firma: en el alta el ping llega antes de que tengas
// el signing_secret (te lo devolvemos en la respuesta de ese mismo PUT).
app.post('/webhooks/shalom', express.raw({ type: 'application/json' }), (req, res) => {
  const event = JSON.parse(req.body);
  if (event.event === 'webhook.ping') {
    return res.status(200).send(event.data.challenge); // <- eco del challenge
  }
  // ... aquí procesas los eventos de tracking (tracking.updated, etc.) ...
  res.status(200).end();
});

Ver la config y el uso — GET /v1/webhooks

Devuelve la config actual y tu uso de cuota de suscripciones (used / max).

{
  "configured": true,
  "url": "https://mi-servidor.com/webhooks/shalom",
  "enabled": true,
  "last_delivery_at": "2026-07-30T15:04:05Z",
  "usage": { "used": 12, "max": 50 }
}

Otras operaciones

Suscribe un envío a vigilar por su numero y codigo de guía (ambos requeridos — son los que ves al crear la orden o en el comprobante). Requiere tener un webhook configurado y verificado (que haya pasado el ping); si no, responde 400. Tip: para tus propias órdenes, lo más cómodo es "track": true al crearlas.

curl -X POST https://api.shalom-api-peru.com/v1/tracking/subscriptions \
  -H "X-API-Key: tu-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "numero": "80574902", "codigo": "CJTW" }'

{
  "subscription": {
    "id": 812,
    "numero": "80574902",
    "codigo": "CJTW",
    "status": "pending_resolve",
    "next_poll_at": "2026-07-30T12:00:00Z",
    "created_at": "2026-07-30T12:00:00Z"
  },
  "outcome": "created"
}

Poco después de suscribir te llega un primer evento con el estado actual del envío, aunque no haya cambiado nada: no hace falta esperar al próximo hito. Si el envío ya estaba entregado, ese primer evento es tracking.delivered y la suscripción se cierra ahí mismo.

Atajo: suscribir al crear la orden

Agrega "track": true al body de POST /v1/orders y la guía recién creada queda suscrita automáticamente. Es best-effort: si no tienes webhook verificado o llegaste al cupo, la orden se crea igual. La respuesta de la orden no indica si la suscripción se creó: confírmalo en GET /v1/tracking/subscriptions.

curl -X POST https://api.shalom-api-peru.com/v1/orders \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password" \
  -H "Content-Type: application/json" \
  -d '{ "...campos de la orden...": "...", "track": true }'

Listar y desuscribir

El payload que recibes

Un POST application/json por cada cambio de estado. El timeline trae los hitos presentes, en orden, con los datos del status de GET /v1/tracking: cada entrada tiene siempre milestone y completo; fecha, hora y descripcion vienen solo si Shalom los manda (en la práctica, casi siempre solo fecha). La entrada entregado puede traer cliente (documento, nombre): quién recibió. occurred_at puede traer fracciones de segundo.

ose_id puede no venir en el primer evento de una suscripción hecha con numero + codigo; identifica el envío por numero.

{
  "id": "evt_812_tracking.updated_1110100",
  "event": "tracking.updated",
  "occurred_at": "2026-07-30T15:04:05.482913Z",
  "data": {
    "numero": "80574902",
    "ose_id": 84048736,
    "status": "destino",
    "previous_status": "transito",
    "delivered": false,
    "timeline": [
      { "milestone": "registrado", "fecha": "2026-07-28 09:12:30", "completo": false },
      { "milestone": "origen",     "fecha": "2026-07-28 09:12:30", "completo": false },
      { "milestone": "transito",   "fecha": "2026-07-29 14:08:21", "completo": true },
      { "milestone": "destino",    "fecha": "2026-07-30 10:05:03", "completo": true }
    ]
  }
}

Headers

Content-Type: application/json
User-Agent: shalom-api-webhooks/1
X-Shalom-Event: tracking.updated
X-Shalom-Event-Id: evt_812_tracking.updated_1110100
X-Shalom-Signature: t=1782140645,v1=8f3a9c...hmac-sha256-en-hex...

Tipos de evento

Los hitos de status / timeline[].milestone son: registrado, origen, transito, demora, destino, reparto, entregado (en ese orden; status es el más avanzado presente).

Verificar la firma (opcional, recomendado)

Cada webhook viene firmado para que puedas comprobar que lo enviamos nosotros y no un impostor que conoce tu URL. Puedes empezar sin verificar para probar rápido, pero recomendamos hacerlo si tu sistema reacciona al evento con una acción automática — por ejemplo, dar la venta por cerrada, actualizar tu stock, o (en un marketplace) liberarle el pago al vendedor cuando el envío figura entregado. Si a tu servidor le llega un entregado falso y lo actúa a ciegas, te pueden engañar. El header X-Shalom-Signature tiene la forma t=<timestamp>,v1=<hmac>, donde v1 = HMAC-SHA256(t + "." + cuerpo_crudo, signing_secret) en hex. La clave es el signing_secret tal cual (el string de 64 caracteres hex), sin decodificarlo.

const crypto = require('crypto');

// SECRET es el signing_secret TAL CUAL: el string de 64 caracteres hex.
// No lo decodifiques de hex — la clave del HMAC son esos caracteres como texto.
function verify(rawBody, header, secret) {
  if (!header) return false;
  const sig = {};
  for (const kv of header.split(',')) {
    const i = kv.indexOf('=');
    if (i > 0) sig[kv.slice(0, i).trim()] = kv.slice(i + 1).trim();
  }
  if (!sig.t || !sig.v1) return false;
  const expected = Buffer.from(crypto.createHmac('sha256', secret)
    .update(sig.t + '.').update(rawBody).digest('hex'));
  const recibida = Buffer.from(sig.v1);
  // timingSafeEqual lanza (→ 500) si los largos difieren: compáralos antes.
  if (expected.length !== recibida.length) return false;
  const firmaOk = crypto.timingSafeEqual(expected, recibida);
  const fresca  = Math.abs(Date.now() / 1000 - Number(sig.t)) < 300; // anti-replay
  return firmaOk && fresca;
}

// Express: usa el cuerpo CRUDO (express.raw), NO el JSON ya parseado.
app.post('/webhooks/shalom', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try { event = JSON.parse(req.body); } catch { return res.status(400).end(); }

  // 1) El ping se responde ANTES de verificar la firma: en el alta llega antes
  //    de que tengas el signing_secret. Si lo rechazas, el webhook queda deshabilitado.
  if (event.event === 'webhook.ping') {
    return res.status(200).send(event.data.challenge);
  }

  // 2) Todo lo demás: verifica la firma antes de actuar.
  if (!verify(req.body, req.header('X-Shalom-Signature'), SECRET)) return res.status(400).end();
  // ... procesa event.data ... (deduplica por event.id)
  res.status(200).end();
});

Reintentos e idempotencia

• Responde 2xx rápido: tienes 10 segundos. Si tu servidor responde algo distinto de 2xx (o no responde a tiempo), reintentamos el mismo cambio en el siguiente poll de esa suscripción (con backoff), con el mismo id, hasta que respondas 2xx o venza el TTL de 21 días. Si mientras tanto el envío avanzó, te llega directamente el estado nuevo (con otro id). Procesa en background si tu lógica es lenta.
• tracking.expired se envía una sola vez. No se reintenta: si tu servidor no responde 2xx, la suscripción se cierra igual.
• Deduplica por X-Shalom-Event-Id. Un reintento reusa el mismo id; guarda los ids procesados y descarta los repetidos (entrega at-least-once). El id es opaco: úsalo solo para deduplicar, no lo parsees.
• El endpoint debe ser https y público. Rechazamos localhost, IPs privadas y de metadata (169.254.169.254) al registrar y en cada entrega.
• No seguimos redirects. Apunta directo al endpoint final.

Lista paginada de agencias. La respuesta incluye total con el conteo del catálogo completo, para que sepas cuántas páginas esperar sin recorrerlas todas.

{
  "page": 1,
  "per_page": 100,
  "total": 546,
  "items": [
    {
      "id": 622,
      "abrebiatura": "BGACHCA",
      "nombre": "AMAZONAS / BAGUA / BAGUA / BAGUA CAPITAL",
      "departamento": "AMAZONAS",
      "provincia": "BAGUA",
      "direccion": "JR. AMAZONAS C-9 MZ. 126 LT. 25, BAGUA - BAGUA - AMAZONAS",
      "telefono": "(01) 500 7878",
      "latitud": -5.6347003028441,
      "longitud": -78.528378922503,
      "aereo": true,
      "estado": "ATENDIENDO EN ESTE MOMENTO",
      "categoria": "PEQUEÑA",
      "zona": "BAGUA",
      "lugar_over": "BAGUA CAPITAL",
      "dep_id": 1,
      "prov_id": 2,
      "dist_id": 5,
      "ubi_id": 10205,
      "reparto_habilitado": true,
      "habilitado": true,
      "principal": false,
      "internacional": false,
      "horario": { "hora_atencion": "LUNES A VIERNES - 8:00 AM A 8:00 PM" },
      "origenes_aereos": [2, 3, 7],
      "destinos_aereos": [623, 624, 632]
    }
  ]
}

Busca por texto o por filtros de ubicación. No pagina: devuelve hasta per_page resultados (page se ignora).

Agencia más cercana

Con near el catálogo se devuelve ordenado de la agencia más cercana a la más lejana, y cada una trae distancia_km. Útil para elegir el punto de recojo automáticamente a partir de la dirección del cliente, sin traerte el catálogo entero en cada llamada.

curl "https://api.shalom-api-peru.com/v1/agencies/search?near=-12.1211,-77.0300&radius_km=5&per_page=3" \
  -H "X-API-Key: tu-api-key"

{
  "items": [
    {
      "id": 190,
      "nombre": "LIMA / LIMA / MIRAFLORES / AV. JOSE PARDO",
      "departamento": "LIMA",
      "provincia": "LIMA",
      "direccion": "AV. JOSE PARDO N°533",
      "latitud": -12.119319117645,
      "longitud": -77.034353944233,
      "aereo": false,
      "distancia_km": 0.51
    },
    {
      "id": 435,
      "nombre": "LIMA / LIMA / MIRAFLORES / AV. COMANDANTE ESPINAR",
      "distancia_km": 0.91
    }
  ]
}

Detalle completo de una agencia por ID numérico.

Todos los departamentos del Perú.

{
  "items": [
    { "id": 1, "name": "AMAZONAS" }
  ]
}

Provincias de un departamento.

Distritos de una provincia.

Es el único nivel que trae ubi_id: el ubigeo INEI de 6 dígitos del distrito (150201 = Barranca). Departamentos y provincias devuelven sólo id y name — su id es el de Shalom, no un ubigeo.

{
  "items": [
    { "id": 1, "name": "BARRANCA", "ubi_id": 150201 },
    { "id": 2, "name": "PARAMONGA", "ubi_id": 150202 }
  ]
}

Crear pedido en Shalom Pro

Crea una guía de envío real en la cuenta de Shalom Pro del cliente y devuelve los identificadores para tracking, descarga de PDF y operaciones posteriores. El remitente es la cuenta autenticada; la resolución del destinatario, la validación del servicio de cobranza y la cotización se hacen automáticamente en una sola llamada.

Estos endpoints necesitan X-API-Key + credenciales de Shalom Pro: ver Autenticación.

Latencia y reintentos

La primera llamada de cada cuenta hace un login real contra Shalom y tarda ~90 s, hasta 2 min. Las siguientes son rápidas: la sesión queda caliente y se reutiliza. Aplica a crear pedido, tracking, sesiones, bulk y productos.

Si una llamada se corta por timeout

En las lecturas (tracking, productos, tarifa, listar órdenes, crear sesión) reintenta sin miedo: la sesión termina de calentarse en segundo plano y el reintento sale rápido.

Usar la opción A concentra el arranque lento en una sola llamada: pides el token con POST /v1/shalom/sessions (una lectura, reintentable sin riesgo) y las órdenes posteriores ya salen rápidas.

Valida las credenciales contra pro.shalom.pe y emite un token efímero (formato ssk_<64-hex>) con TTL de 2 horas.

El password viaja en el body (no en headers, que suelen acabar en logs) y no se persiste: se usa para emitir el token y se descarta.

curl -X POST https://api.shalom-api-peru.com/v1/shalom/sessions \
  -H "X-API-Key: tu-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "cliente@empresa.com",
    "password": "tu-password-de-shalom-pro"
  }'

{
  "session_token": "ssk_a1b2c3d4e5f6...",
  "expires_at": "2026-05-08T18:23:01Z"
}

Body

Cuándo expira el token

Dura 2 horas desde su emisión. Un token vencido devuelve 401 shalom_auth_failed: pide uno nuevo. El token solo sirve con la X-API-Key que lo emitió; usado con otra key, también devuelve 401 shalom_auth_failed. El token sobrevive a reinicios y despliegues del servicio dentro de esas 2 horas, así que no necesitas re-emitirlo tras un deploy.

Revoca un token antes de que expire y cierra la sesión viva que la API mantiene abierta contra Shalom para esa cuenta. Idempotente: si el token ya estaba revocado o nunca existió, igual responde 200. Útil para forzar logout cuando el cliente cambia de cuenta o detecta actividad sospechosa.

curl -X DELETE https://api.shalom-api-peru.com/v1/shalom/sessions \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Session: ssk_a1b2c3d4e5f6..."

{ "revoked": true, "session_closed": true }

El token a revocar va en el header X-Shalom-Session, no en el path ni en el body. También puedes identificar la cuenta con X-Shalom-Email + X-Shalom-Password para cerrar su sesión viva, pero solo si no mandas X-Shalom-Session: si viene el token, se usa siempre ese. Si no mandas ni lo uno ni lo otro, devuelve 400. session_closed indica si se cerró la sesión viva contra Shalom (es false si el token ya no era válido).

Lista los productos disponibles en la cuenta de Shalom Pro del cliente: Sobre, Caja Paquete XXS/XS/S/M/L y Otra Medida. Devuelve el id que usas en el body de POST /v1/orders y las dimensiones default de cada uno.

curl https://api.shalom-api-peru.com/v1/products \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro"

{
  "products": [
    {
      "id": 3,
      "title": "Sobre",
      "img": "https://pro.shalom.pe/img/products/sobre.png",
      "content": "Hasta 0.5 kg",
      "sub_content": "Documentos y similares",
      "measurements": {
        "weight": 0.5,
        "width": 0.3,
        "height": 0.02,
        "length": 0.4
      }
    },
    {
      "id": 1098,
      "title": "Otra Medida",
      "img": "https://pro.shalom.pe/img/products/custom.png",
      "content": "Define las dimensiones",
      "sub_content": "Para bultos fuera de catálogo",
      "measurements": { "weight": 0, "width": 0, "height": 0, "length": 0 }
    }
  ]
}

Resuelve un documento (DNI/RUC/CE) a una persona registrada en pro.shalom.pe. Útil para autocomplete en formularios — el usuario tipea su DNI y tú pre-cargas nombre, apellidos y teléfono antes del submit.

curl "https://api.shalom-api-peru.com/v1/persons/search?document=70123456&type=DNI" \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro"

{
  "id": 1234567,
  "document_type": "DNI",
  "document": "70123456",
  "name": "JUANA",
  "last_name": "RAMOS",
  "sur_name": "LOPEZ",
  "full_name": "JUANA RAMOS LOPEZ",
  "phone": 999111222
}

Query params

Errores específicos

{
  "error": {
    "code": "not_found",
    "message": "persona no registrada en Shalom Pro",
    "request_id": "01KS..."
  }
}

Calcula el precio de un envío entre dos terminales sin comprometer la orden. Devuelve el precio para cada tipo de producto del catálogo (sobre, cajas XXS/XS/S/M/L y otra medida) para que puedas mostrar la cotización antes del checkout.

curl -X POST https://api.shalom-api-peru.com/v1/tariff/calculate \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_terminal_id": 66,
    "destiny_terminal_id": 7,
    "dimensions": {
      "weight_kg": 1.0,
      "height_m": 0.1,
      "length_m": 0.2,
      "width_m": 0.15
    }
  }'

{
  "currency": "PEN",
  "aereo": false,
  "breakdown": {
    "sobre": 8.00,
    "caja_paquete_xxs": 8.00,
    "caja_paquete_xs": 10.00,
    "caja_paquete_s": 12.00,
    "caja_paquete_m": 15.00,
    "caja_paquete_l": 20.00,
    "otra_medida": 25.00
  }
}

Body

Con product_id — precio puntual

Si ya sabes qué producto va a comprar el usuario, manda product_id y te ahorras el mapeo manual del breakdown:

curl -X POST https://api.shalom-api-peru.com/v1/tariff/calculate \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_terminal_id": 66,
    "destiny_terminal_id": 7,
    "product_id": 3
  }'

{
  "currency": "PEN",
  "aereo": false,
  "breakdown": {
    "sobre": 8.00,
    "caja_paquete_xxs": 8.00,
    "caja_paquete_xs": 10.00,
    "caja_paquete_s": 12.00,
    "caja_paquete_m": 15.00,
    "caja_paquete_l": 20.00,
    "otra_medida": 25.00
  },
  "product": {
    "id": 3,
    "title": "Sobre",
    "price": 8.00
  }
}

Errores: los generales. El 400 se da si faltan origin_terminal_id o destiny_terminal_id, Si Shalom no cotiza la ruta o el producto, responde 422 upstream_rejected con su motivo (prefijo "Shalom Pro: "); lo mismo pasa al crear un pedido.

Crea una guía de envío. Devuelve guia, serie, codigo y ose_id. Para trackear usa guia + codigo (o el ose_id); para borrar necesitas el id que aparece en GET /v1/orders, que no viene en esta respuesta.

curl -X POST https://api.shalom-api-peru.com/v1/orders \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_terminal_id": 404,
    "destiny_terminal_id": 7,
    "product_id": 3,
    "quantity": 1,
    "payer": "sender",
    "declaracion_jurada": "docs",
    "receiver": {
      "document_type": "DNI",
      "document": "87654321",
      "name": "MARIA",
      "last_name": "GOMEZ",
      "sur_name": "TORRES",
      "phone": 998765432
    },
    "pickup_code": "2415"
  }'

{
  "guia": "80574902",
  "serie": "v872",
  "codigo": "CJTW",
  "ose_id": 584210
}

Guarda el ose_id: lo necesitas para descargar el rótulo y el comprobante. Qué es cada identificador de la respuesta, en Identificadores.

Con GET /v1/orders/{ose_id} recuperas el registro local completo de una orden (el body que mandaste y la respuesta), tal como se guardó al crearla. Solo existe para órdenes creadas con POST /v1/orders por tu misma API key; cualquier otra devuelve 404.

Todos los campos del body — requeridos y opcionales — están en Campos del body. Ojo con declaracion_jurada: la API lo exige ("docs", "ropa", "art" o "electro"); si lo omites, responde 400.

Errores propios de crear pedido

El resto, en Errores.

{
  "error": {
    "code": "shalom_auth_failed",
    "message": "X-Shalom-Email/Password rechazados por Shalom Pro",
    "request_id": "01KQ..."
  }
}

Carga masiva de envíos desde la plantilla Excel de Shalom Pro (Formato-Pro-Masivo.xlsx). El wrapper importa el archivo, lo valida (todo-o-nada), asigna la misma clave de retiro a todo el lote y lo emite — en una sola llamada. Para crear un solo envío usa POST /v1/orders.

Campos (form-data)

curl -X POST https://api.shalom-api-peru.com/v1/orders/bulk \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro" \
  -F "file=@Formato-Pro-Masivo.xlsx" \
  -F "pickup_code=2415"

{
  "count": 12,
  "message": "Envíos registrados",
  "created": []
}

created normalmente viene vacío: Shalom confirma la emisión pero no devuelve las guías. Para obtenerlas, consulta GET /v1/orders justo después — las del lote son las más recientes.

Validación todo-o-nada

Si cualquier fila tiene errores, no se crea ningún envío: la respuesta es 422 con el detalle por fila en rows (row, el id del borrador que se descartó y los errors de Shalom) para que corrijas el Excel y reintentes. Si Shalom rechaza el archivo entero, el message trae su motivo y rows puede venir vacío.

{
  "error": {
    "code": "upstream_rejected",
    "message": "Shalom Pro: el archivo tiene filas con errores; corrige y vuelve a subirlo",
    "request_id": "01KQ..."
  },
  "rows": [
    {
      "row": 3,
      "id": 5512001,
      "errors": ["El destinatario no tiene documento válido"]
    },
    {
      "row": 7,
      "id": 5512005,
      "errors": ["Terminal de destino no encontrado", "Peso requerido"]
    }
  ]
}

Errores propios de bulk

El resto, en Errores.

Lista las órdenes de la cuenta: preguías y envíos despachados. Sin query params devuelve todas en una sola respuesta, sin campo meta. Al mandar page, per_page o state se activa la paginación y se agrega meta.

Hay dos caminos. Rápido (paginado por Shalom): si mandas state, o from junto con page/per_page, y no mandas status, la API pide a Shalom solo lo que necesita. Lento (lista completa): en cualquier otro caso (incluido usar status) la API trae todas las órdenes de la cuenta y filtra y pagina en memoria: recorta la respuesta, pero no la carga contra Shalom.

Query params (opcionales)

Los filtros se combinan con AND y se aplican antes de paginar, así que meta.total refleja el conteo ya filtrado. Filtrar sin paginar (y sin state) devuelve el mismo shape de siempre (sin meta). Con from + paginación y sin state, la API combina los tres estados; si alguno no responde en Shalom, sirve el resto y marca meta.partial: true (puede faltar órdenes de ese estado).

curl https://api.shalom-api-peru.com/v1/orders \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro"

{
  "orders": [
    {
      "id": 87654321,
      "internal_id": 4567890,
      "guia": "12345678",
      "serie": "s001",
      "codigo": "ABCD",
      "pickup_code": "2415",
      "created_at": "2026-05-08 10:11:12",
      "updated_at": "2026-05-08 10:11:13",
      "shipping_date": "2026-05-08",
      "status": 1,
      "payer": "receiver",
      "aereo": false,
      "delivered": false,
      "paid": false,
      "origin": {
        "ter_id": 404,
        "name": "SALAS ICA",
        "address": "SUB LOTE 01 ZONA PANAMERICANA SUR KM. 293.350...",
        "abbreviation": "sls",
        "phone": "(01) 500 7878",
        "ubigeo": "ICA - ICA - SALAS"
      },
      "destination": {
        "ter_id": 7,
        "name": "AV PARRA 379 CO",
        "address": "AV. PARRA 379",
        "abbreviation": "AQP",
        "phone": "0",
        "ubigeo": "AREQUIPA - AREQUIPA - AREQUIPA"
      },
      "sender": {
        "id": 0,
        "document": "12345678",
        "name": "",
        "last_name": "",
        "sur_name": "",
        "full_name": "JUAN PEREZ GARCIA",
        "phone": 0
      },
      "receiver": {
        "id": 0,
        "document": "87654321",
        "name": "MARIA",
        "last_name": "GOMEZ",
        "sur_name": "TORRES",
        "full_name": "MARIA GOMEZ TORRES",
        "phone": 998765432
      },
      "items": [
        {
          "id": 11223344,
          "quantity": 1,
          "weight": 0,
          "width": 0,
          "length": 0,
          "height": 0,
          "status": 1,
          "product_name": "Sobre",
          "product_detail": "Documentos simples en sobre manila / Tamaño A4",
          "product_price": 20
        }
      ],
      "warranty": { "active": false, "amount": 0, "total_cost": 0, "percent": 0.01 }
    }
  ]
}

# Paginado por Shalom (rápido): estado + rango de fechas, con "meta"
curl "https://api.shalom-api-peru.com/v1/orders?state=delivered&page=1&per_page=20&from=2026-05-01&to=2026-05-31" \
  -H "X-API-Key: tu-api-key" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro"

{
  "orders": [
    { "id": 87654321, "guia": "12345678", "status": 1, "delivered": true, "created_at": "2026-05-08 10:11:12" }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "per_page": 20,
    "last_page": 8
  }
}

Campos de la orden