Última actualización: 2026-11-11 · Base URL: https://api.shalom-api.lat
El rastreo consulta el estado de una guía de Shalom usando su número de orden (8 a 12 dígitos) y su código de seguridad (4 caracteres alfanuméricos). La respuesta es el espejo del sistema de Shalom. Si la guía está suscrita, se refresca sola cada 30 minutos cuando acaba de cambiar, cada 2 horas mientras está en camino (así el aviso de llegada no tarda más de eso) y cada 3 horas cuando ya está en la agencia destino esperando recojo. Si consultas una guía cuyo último dato guardado tiene más de 10 minutos, pedimos el estado en vivo antes de responderte.
/trackDevuelve el resultado de búsqueda y los estados de la guía (espejo del sistema de Shalom).
| Parámetro | Descripción |
|---|---|
| orderNumber* | Número de guía / orden (string de 8 a 12 dígitos, patrón ^[0-9]+$). Las guías nuevas de Shalom tienen 9 dígitos. |
| orderCode* | Código de seguridad (string de 4 caracteres). |
{
"orderNumber": "66479331",
"orderCode": "3KTH"
}{
"search": { "..." : "resultado de búsqueda de Shalom (espejo)" },
"statuses": [ { "..." : "estados de la guía (espejo)" } ]
}Nota: La respuesta es el espejo de la API pública de Shalom (campos adicionales según el estado). Si el dato guardado tiene más de 10 minutos, se consulta en vivo al responder (unos segundos; si el origen no responde, se devuelve el último espejo).
/track/batchRastrea múltiples guías con control de flujo y concurrencia. Límite máximo de 50 órdenes por petición.
| Parámetro | Descripción |
|---|---|
| orders* | Array de objetos { orderNumber, orderCode }, máximo 50 items. |
{
"orders": [
{ "orderNumber": "66479331", "orderCode": "3KTH" },
{ "orderNumber": "66479332", "orderCode": "9ABC" }
]
}[
{ "search": { "..." : "..." }, "statuses": [ "..." ] },
{ "search": { "..." : "..." }, "statuses": [ "..." ] }
]Nota: La respuesta es un ARRAY directo: cada posición corresponde a la orden enviada en el mismo orden.
/track/by-oseResuelve un ose_id (service_order_id) al número de orden y código de seguridad usando el rastreo público de Shalom. No requiere instancia; si envías instanceId y la guía aún no es pública, la busca en los envíos pendientes de esa cuenta.
| Parámetro | Descripción |
|---|---|
| ose_id* | ose_id / service_order_id de la orden. |
| instanceId | Opcional: ID de la instancia para buscar también en envíos pendientes. |
curl -X GET "https://api.shalom-api.lat/track/by-ose?ose_id={ose_id}&instanceId={instanceId}" \
-H "x-api-key: TU_API_KEY"{
"success": true,
"message": "Guia encontrada.",
"source": "tracking",
"data": {
"ose_id": 123456789,
"orderNumber": "12345678",
"orderCode": "ABCD",
"status": "En destino",
"delivered": false,
"monto": "12.00",
"montoAdicional": 0,
"contenido": "1 PAQUETE XS",
"fecha_emision": "2026-10-01 10:00:00",
"fecha_traslado": "2026-10-01 10:00:00",
"tiempo_llegada": "48 horas",
"tipo_pago": "Contra entrega",
"estado_pago": "CA",
"direccion_entrega": "ENTREGAR EN AGENCIA",
"aereo": false,
"remitente": { "nombre": "JUAN PEREZ GOMEZ", "documento": "12345678" },
"destinatario": { "nombre": "MARIA LOPEZ DIAZ", "documento": "87654321" },
"comprobante": { "cop_id": 72409411, "tipo": "BV", "serie": "B936", "numero": "0049643", "fecha": "2026-10-02", "hora": "12:46:00", "estado_pago": "CA" },
"origen": { "id": 7, "nombre": "LIMA" },
"destino": { "id": 582, "nombre": "PIURA" }
}
}Nota: Incluye remitente, destinatario (nombre y documento), comprobante, pago, entrega y fechas. Sin instanceId solo resuelve órdenes visibles en el rastreo público. Con instanceId y una guía pendiente responde source "pending" y status "Pendiente" (el destinatario puede venir null si Shalom aún no lo vincula; se incluye recipient_id). 404 si no existe.
/track/voucherShalom ProDescarga el ticket oficial del envío tal como lo emite Shalom, en PDF o como imagen (JPEG/PNG) lista para WhatsApp. Es una operación Pro: requiere una cuenta Shalom Pro conectada (instanceId), porque el documento se pide con la sesión del panel.
| Parámetro | Descripción |
|---|---|
| instanceId* | ID de la instancia (cuenta Shalom Pro conectada). |
| ose_id | ose_id / service_order_id del envío (recomendado: funciona también con guías recién creadas). |
| orderNumber | Número de guía (8 a 12 dígitos). Alternativa a ose_id. |
| orderCode | Código de seguridad (4 caracteres). Alternativa a ose_id. |
| format | pdf (default) devuelve el PDF oficial; image, jpg, jpeg o png devuelven una imagen del mismo ticket, rasterizada del PDF oficial. |
curl -X GET "https://api.shalom-api.lat/track/voucher?instanceId={instanceId}&ose_id={ose_id}" \
-H "x-api-key: TU_API_KEY"Content-Type: application/pdf
<binario — PDF del ticket oficial de Shalom>
// con format=image
Content-Type: image/jpeg
<binario — imagen del ticket oficial>Nota: Identifica el envío con ose_id o con orderNumber + orderCode: si la guía todavía no aparece en el rastreo público, el ose_id se resuelve desde tus envíos pendientes. El ticket se pide a Shalom (POST /ticket-pdf/token + GET /ticket-pdf/<ose_id>) y se devuelve tal cual; con format=image se rasteriza ese mismo PDF (nunca se genera un ticket local). instanceId es obligatorio. Errores: 404 si Shalom no tiene esa orden, 409 si la sesión de la instancia venció y 502 solo si el origen falla.
/track/labelShalom ProDescarga el PDF de la etiqueta (rótulo) de un envío. Es una operación Pro: requiere una cuenta Shalom Pro conectada (instanceId) porque el rótulo se genera con la sesión del usuario.
| Parámetro | Descripción |
|---|---|
| instanceId* | ID de la instancia (cuenta Shalom Pro conectada). |
| ose_id | ose_id / service_order_id del envío (recomendado, funciona también con guías pendientes). |
| orderNumber | Número de guía (8 a 12 dígitos). Alternativa a ose_id. |
| orderCode | Código de seguridad (4 caracteres). Alternativa a ose_id. |
curl -X GET "https://api.shalom-api.lat/track/label?instanceId={instanceId}&ose_id={ose_id}" \
-H "x-api-key: TU_API_KEY"Content-Type: application/pdf
<binario — PDF de la etiqueta>Nota: Identifica el envío con ose_id o con orderNumber + orderCode. Internamente se solicita un token temporal (POST /rotulo/token) y se descarga la URL firmada con la sesión de la instancia. El PDF lo genera Shalom y se devuelve tal cual: 1 página horizontal de 595 × 366 pt (≈ 210 × 129 mm, ~550 KB) con orden, código, destinatario, destino, tipo de entrega y un recuadro para pegar tu logo. No es formato de etiqueta térmica 10 × 15: imprímelo en A4 o escálalo en tu impresora. Shalom también genera el rótulo de guías anuladas, así que verifica el estado antes de despachar.
El rastreo se hace con dos datos que el cliente recibe al registrar el envío: el número de orden (8 a 12 dígitos; las guías nuevas de Shalom tienen 9) y el código de seguridad de 4 caracteres alfanuméricos. Los dos son obligatorios. Sin el código, la API no puede resolver la guía aunque el número exista.
POST /track resuelve una guía. Si tienes que revisar decenas —por ejemplo, todos los pedidos de la semana— usa POST /track/batch, que acepta hasta 50 guías por llamada.
El lote no solo ahorra requests: es la diferencia entre acercarte o no al límite de 60 peticiones por minuto cuando tu volumen crece.
La respuesta refleja el estado del sistema de Shalom, no un estado propio nuestro. Por eso los campos pueden variar según la etapa del envío y no conviene asumir que todos los hitos estarán siempre presentes.
Las guías con suscripción activa se refrescan solas, con un ritmo que depende de su actividad: cada 30 minutos mientras se mueven, cada 2 horas cuando llevan un tiempo sin cambios y cada 3 horas cuando esperan recojo en destino. Entre las 22:00 y las 06:00 (hora de Lima) no se refrescan en segundo plano. Las guías entregadas dejan de consultarse, y también las que llevan 20 días sin moverse o están devueltas o anuladas.
Una guía sin suscripción no se refresca sola. Al llamar a POST /track, a cualquier hora y esté o no suscrita la guía, si el último dato guardado tiene más de 10 minutos se pide el estado en vivo antes de responder. El detalle está en el tema Optimizaciones del tracking.
Consultar el estado cada pocos segundos funciona, pero es caro y lento. Si tu sistema necesita reaccionar a los cambios —avisar al comprador, cerrar un pedido contra entrega— registra un webhook y suscribe las guías: recibirás un POST firmado solo cuando el envío cambie de estado, con el timeline completo dentro.
Conviene persistir cada consulta con su fecha. El estado en vivo te dice dónde está el paquete hoy; el histórico te permite responder «¿cuándo se movió por última vez?» y detectar envíos detenidos antes de que el cliente reclame.
| 400 | orderNumber no tiene entre 8 y 12 dígitos o orderCode no tiene 4 caracteres. |
| 404 | La guía no existe o aún no está registrada en Shalom. |
| 409 | La instancia perdió la sesión de Shalom Pro (aplica a /track/voucher y /track/label). Vuelve a iniciar sesión en la instancia. |
| 502 | Shalom (el origen) no devolvió el documento. Reintenta en unos minutos; el borde puede mostrarlo como "error code: 502". |
El número de orden (8 a 12 dígitos, hoy las guías nuevas tienen 9) y el código de seguridad de 4 caracteres que se entregan al registrar la guía. Ambos son obligatorios.
En POST /track una guía; en POST /track/batch hasta 50 por petición.
Es un espejo del sistema de Shalom, no un dato instantáneo: las guías suscritas se refrescan solas cada 30 min–3 h según su actividad y, si el dato guardado tiene más de 10 minutos, se consulta en vivo al responder tu llamada. La respuesta replica lo que informa Shalom, incluido su texto de estado (statuses.message). Para reaccionar a los cambios sin consultar, usa webhooks: te avisan de cada hito, desde el registro y la recepción en origen hasta la entrega.
Shalom publica Registrado, En origen, En tránsito, En destino, Demora de envíos y Entregado. La API los replica tal cual en el evento (status) y agrega el estado normalizado (statusCode: REGISTERED, EN_ORIGIN, IN_TRANSIT, AT_DESTINATION, OUT_FOR_DELIVERY, DELIVERED). Demora de envíos es un aviso: llega con delayed en true y no reemplaza el hito.
Con GET /track/voucher para el ticket oficial en PDF o imagen (requiere instanceId; usa format=image para WhatsApp) y GET /track/label para la etiqueta (rótulo) en PDF horizontal de ≈ 210 × 129 mm, que se imprime en A4.
Con webhooks: registras tu URL una vez, suscribes las guías y recibes un POST firmado cada vez que un envío cambia de estado. Así dejas de hacer polling.
Escríbenos por WhatsApp y la recibes de inmediato para probar todos estos ejemplos.
Solicitar API key