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" \
  -H "X-Shalom-Email: cliente@empresa.com" \
  -H "X-Shalom-Password: tu-password-de-shalom-pro" \
  "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: mi-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 controlás la URL — evita que alguien apunte el webhook a un servidor ajeno.

// Al registrar, te mandamos un webhook.ping firmado con un challenge.
// Tu endpoint debe DEVOLVER ese challenge en el body (2xx) para habilitarse.
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
  }
  // ... acá procesás 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 primero. 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: mi-key" \
  -H "Content-Type: application/json" \
  -d '{ "numero": "80574902", "codigo": "CJTW" }'

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

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 o llegaste al cupo, la orden se crea igual.

curl -X POST https://api.shalom-api-peru.com/v1/orders \
  -H "X-API-Key: mi-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 con fecha, hora y descripción — lo mismo que el status de GET /v1/tracking.

{
  "id": "evt_812_tracking.updated_destino",
  "event": "tracking.updated",
  "occurred_at": "2026-07-30T15:04:05Z",
  "data": {
    "numero": "80574902",
    "ose_id": 84048736,
    "status": "destino",
    "previous_status": "transito",
    "delivered": false,
    "timeline": [
      { "milestone": "registrado", "fecha": "2026-07-28", "hora": "09:12", "descripcion": "Registrado en agencia origen", "completo": true },
      { "milestone": "transito",   "fecha": "2026-07-29", "hora": "14:30", "descripcion": "En tránsito", "completo": true },
      { "milestone": "destino",    "fecha": "2026-07-30", "hora": "10:05", "descripcion": "En agencia destino", "completo": false }
    ]
  }
}

Headers

X-Shalom-Event: tracking.updated
X-Shalom-Event-Id: evt_812_tracking.updated_destino
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, entregado, reparto.

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).

const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const sig = Object.fromEntries(header.split(',').map(kv => kv.split('=')));
  const expected = crypto.createHmac('sha256', secret)
    .update(sig.t + '.' + rawBody).digest('hex');
  const firmaOk = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
  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) => {
  if (!verify(req.body, req.header('X-Shalom-Signature'), SECRET)) return res.status(400).end();
  const event = JSON.parse(req.body);
  // ... procesa event.data ... (deduplica por event.id)
  res.status(200).end();
});

Reintentos e idempotencia

• Responde 2xx rápido. Si tu servidor responde algo distinto de 2xx (o no responde), reintentamos el mismo cambio en el próximo ciclo de poll. Procesa en background si tu lógica es lenta.
• 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 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": 485,
  "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.

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. La resolución de remitente y 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 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. 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 }

El token a revocar va en el header X-Shalom-Session, no en el path ni en el body. Si el header falta, devuelve 400.

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,
  "email": null,
  "address": null
}

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",
  "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",
  "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.

Crea una guía de envío. Devuelve guia, serie y codigo — los identificadores con los que después puedes trackear o borrar la orden.

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.

Todos los campos del body — requeridos y opcionales — están en Campos del body. Ojo con declaracion_jurada: es requerido ("docs", "ropa", "art" o "electro"); si lo omites, la API 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 siempre 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 para que corrijas el Excel y reintentes.

{
  "error": {
    "code": "upstream_rejected",
    "message": "el archivo tiene filas con errores de validación",
    "request_id": "01KQ..."
  },
  "rows": [
    {
      "row": 3,
      "errors": ["El destinatario no tiene documento válido"]
    },
    {
      "row": 7,
      "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 o per_page se activa la paginación y se agrega meta.

La paginación y los filtros se aplican del lado de la API, no de Shalom: recortan la respuesta, pero no reducen la carga contra el upstream.

Query params (opcionales)

Los filtros (guia, status, from, to) se combinan con AND y se aplican antes de paginar, así que meta.total refleja el conteo ya filtrado. Filtrar sin paginar devuelve el mismo shape de siempre (sin meta).

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": 1234567,
        "document": "12345678",
        "name": "JUAN",
        "last_name": "PEREZ",
        "sur_name": "GARCIA",
        "full_name": "JUAN PEREZ GARCIA",
        "phone": 999888777
      },
      "receiver": { "id": 7654321, "document": "87654321", "...": "..." },
      "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 }
    }
  ]
}

# Paginar (agrega "meta") + filtrar por estado y rango de fechas
curl "https://api.shalom-api-peru.com/v1/orders?page=1&per_page=20&status=1&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, "created_at": "2026-05-08 10:11:12" }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "per_page": 20,
    "last_page": 8
  }
}

Campos de la orden