Rastrear envíos
Rastrea envíos de Shalom por API: consulta individual con POST /track, lote de hasta 50 guías, búsqueda por ose_id, ticket oficial en PDF o imagen y rótulo en PDF.
El rastreo consulta el estado de una guía de Shalom con su número de orden y su código de seguridad. La respuesta es el espejo del rastreo público de Shalom. Los documentos del envío (ticket y rótulo) salen de tu cuenta de Shalom Pro y requieren una instancia.
Qué datos necesitas
El número de orden (8 a 12 dígitos) y el código de seguridad (4 caracteres) que recibe el cliente al registrar el envío. Sin el código la guía no se puede consultar, aunque el número exista. Si solo tienes el ose_id (el identificador interno de la orden), conviértelo primero con GET /track/by-ose.
Qué significa que la respuesta sea un espejo
La API devuelve lo que publica Shalom, no un estado propio. Los campos cambian según la etapa del envío y no todos los hitos están siempre presentes: un hito que todavía no ocurrió llega en null.
El estado que muestra Shalom está en statuses.message ("Registrado", "En origen", "En tránsito", "En destino", "Demora de envíos" o "Entregado"). Los webhooks agregan además un código normalizado, que es el que conviene usar para decidir flujos.
Individual, lote o webhook
POST /track resuelve una guía. Para revisar muchas a la vez usa POST /track/batch, que acepta hasta 50 y consume una sola operación.
Si necesitas reaccionar a los cambios (avisar al comprador, cerrar un pedido contra entrega), no consultes en bucle: suscribe las guías y recibe un webhook cuando cambien. Cada cuánto se actualiza una guía se explica en Cómo se actualiza el tracking.
Rastrear un envío
POST /trackDevuelve el resultado de búsqueda (search) y la línea de tiempo (statuses) de la guía, tal como los publica el rastreo de Shalom. Consume 1 operación.
| Parámetro | Requerido | Descripción |
|---|---|---|
orderNumber | Sí | Número de orden. String de 8 a 12 dígitos, solo números (las guías nuevas de Shalom tienen 9). |
orderCode | Sí | Código de seguridad. String de exactamente 4 caracteres. |
curl -X POST "https://api.shalom-api.lat/track" \
-H "x-api-key: TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"orderNumber": "66479331",
"orderCode": "3KTH"
}'{
"search": {
"success": true,
"message": "Guia encontrada.",
"data": {
"ose_id": 106620694,
"numero_orden": "66479331",
"codigo_orden": "3KTH",
"entregado": false,
"contenido": "1 PAQUETE XS",
"origen": { "id": 7, "nombre": "LIMA" },
"destino": { "id": 582, "nombre": "PIURA" },
"...": "más campos del espejo: monto, pago, remitente, destinatario, comprobante"
}
},
"statuses": {
"message": "En tránsito",
"data": {
"registrado": { "fecha": "2026-11-10 09:12:00" },
"origen": { "fecha": "2026-11-10 11:40:00" },
"transito": { "fecha": "2026-11-10 20:05:00" },
"destino": null,
"reparto": null,
"entregado": null
}
}
}Rastrear en lote
POST /track/batchRastrea hasta 50 guías en una sola llamada (se consultan de 5 en 5). Una guía que falla no corta el lote. Consume 1 operación por llamada, sin importar cuántas guías envíes.
| Parámetro | Requerido | Descripción |
|---|---|---|
orders | Sí | Array de 1 a 50 objetos { orderNumber, orderCode }, con las mismas reglas que POST /track. |
curl -X POST "https://api.shalom-api.lat/track/batch" \
-H "x-api-key: TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"orders": [
{ "orderNumber": "66479331", "orderCode": "3KTH" },
{ "orderNumber": "66479332", "orderCode": "9ABC" }
]
}'[
{
"orderNumber": "66479331",
"orderCode": "3KTH",
"search": { "success": true, "...": "igual que POST /track" },
"statuses": { "message": "En tránsito", "...": "igual que POST /track" }
},
{
"orderNumber": "66479332",
"orderCode": "9ABC",
"success": false,
"error": "Shalom buscar API returned status 503"
}
]Resolver ose_id a número de orden y código
GET /track/by-oseConvierte un ose_id (service_order_id) en número de orden y código de seguridad, con el estado y los datos del envío. Usa el rastreo público de Shalom; si envías instanceId y la guía aún no es pública, la busca también en los envíos pendientes de esa cuenta. Consume 1 operación.
| Parámetro | Requerido | Descripción |
|---|---|---|
ose_id | Sí | ose_id de la orden. Solo números, hasta 15 dígitos. |
instanceId | No | Opcional: instancia de tu cuenta para buscar también en los envíos pendientes. |
curl -X GET "https://api.shalom-api.lat/track/by-ose?ose_id=106620694" \
-H "x-api-key: TU_API_KEY"{
"success": true,
"message": "Guia encontrada.",
"source": "tracking",
"data": {
"ose_id": 106620694,
"orderNumber": "66479331",
"orderCode": "3KTH",
"status": "En destino",
"delivered": false,
"monto": "12.00",
"montoAdicional": 0,
"contenido": "1 PAQUETE XS",
"fecha_emision": "2026-11-10 09:12:00",
"fecha_traslado": "2026-11-10 20:05:00",
"tiempo_llegada": "48 horas",
"tipo_pago": "Contra entrega",
"estado_pago": "CA",
"direccion_entrega": "ENTREGAR EN AGENCIA",
"aereo": false,
"reparto": null,
"remitente": { "nombre": "TIENDA EJEMPLO SAC", "documento": "20123456789" },
"destinatario": { "nombre": "CLIENTE DE PRUEBA", "documento": "12345678" },
"comprobante": { "cop_id": 72409411, "tipo": "BV", "serie": "B936", "numero": "0049643", "fecha": "2026-11-10", "hora": "12:46:00", "estado_pago": "CA" },
"origen": { "id": 7, "nombre": "LIMA" },
"destino": { "id": 582, "nombre": "PIURA" }
}
}Descargar el ticket oficial (PDF o imagen)
GET /track/voucherRequiere Shalom Pro
Descarga el ticket oficial del envío tal como lo emite Shalom Pro, en PDF o como imagen lista para WhatsApp. Consume 1 operación.
| Parámetro | Requerido | Descripción |
|---|---|---|
instanceId | Sí | Instancia de la cuenta Shalom Pro dueña del envío. |
ose_id | No | ose_id del envío. Recomendado: funciona también con guías recién creadas. |
orderNumber | No | Número de orden (8 a 12 dígitos). Alternativa a ose_id, junto con orderCode. |
orderCode | No | Código de seguridad (4 caracteres). Va con orderNumber. |
format | No | pdf (por defecto) devuelve el PDF oficial; image, jpg o jpeg devuelven JPEG y png devuelve PNG, rasterizados del mismo PDF. |
curl -X GET "https://api.shalom-api.lat/track/voucher?instanceId=2e656a02-7e37-4573-9d68-e76740d337dc&ose_id=106620694&format=pdf" \
-H "x-api-key: TU_API_KEY"Content-Type: application/pdf
Content-Disposition: inline; filename="voucher-106620694.pdf"
<binario: PDF del ticket oficial de Shalom>Descargar el rótulo (etiqueta PDF)
GET /track/labelRequiere Shalom Pro
Descarga el PDF del rótulo del envío, la etiqueta que se pega en el paquete, generado por Shalom Pro. Consume 1 operación.
| Parámetro | Requerido | Descripción |
|---|---|---|
instanceId | Sí | Instancia de la cuenta Shalom Pro dueña del envío. |
ose_id | No | ose_id del envío. Recomendado: es la única forma de pedir el rótulo de una guía que todavía no aparece en el rastreo público. |
orderNumber | No | Número de orden (8 a 12 dígitos). Alternativa a ose_id, junto con orderCode. |
orderCode | No | Código de seguridad (4 caracteres). Va con orderNumber. |
curl -X GET "https://api.shalom-api.lat/track/label?instanceId=2e656a02-7e37-4573-9d68-e76740d337dc&ose_id=106620694" \
-H "x-api-key: TU_API_KEY"Content-Type: application/pdf
<binario: PDF del rótulo>Errores
| Código | Significado |
|---|---|
400 | orderNumber no tiene de 8 a 12 dígitos, orderCode no tiene 4 caracteres, ose_id no es numérico, format no es válido, o falta ose_id y también orderNumber + orderCode. |
403 | El instanceId no existe o no pertenece a tu API key. |
404 | Shalom no tiene esa orden o no se pudo resolver su ose_id (by-ose, voucher y label). POST /track no responde 404: devuelve search.success en false. |
409 | La instancia perdió la sesión de Shalom Pro y no pudo reconectarse. Vuelve a iniciar sesión (ver Instancias). |
502 | Shalom no devolvió el documento o la consulta. Reintenta en unos minutos; el borde puede mostrarlo como "error code: 502". |
Preguntas frecuentes
El número de orden (8 a 12 dígitos; las guías nuevas tienen 9) y el código de seguridad de 4 caracteres que se entregan al registrar la guía. Los dos son obligatorios.
Una con POST /track y hasta 50 con POST /track/batch. El lote consume 1 operación por llamada.
Es un espejo del rastreo de Shalom. Si el dato guardado tiene más de 10 minutos, se pide el estado en vivo antes de responderte. Las reglas completas están en Cómo se actualiza el tracking.
POST /track responde 200 con search.success en false y statuses en null. Revisa que el número y el código sean los del ticket.
Con GET /track/voucher (ticket oficial en PDF, o imagen con format=image o png) y GET /track/label (rótulo en PDF). Los dos requieren una instancia de Shalom Pro.
Con webhooks: registras tu URL una vez, suscribes las guías y recibes un POST firmado cada vez que una cambia de estado.