Última actualización: 2026-09-21 · 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 dígitos) y su código de seguridad (4 caracteres alfanuméricos). La respuesta es el espejo del sistema de Shalom: se refresca cada 30 minutos mientras la guía se mueve, cada 2 horas cuando lleva un tiempo sin cambios y cada 6 horas en las más antiguas. 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 dígitos, patrón ^[0-9]+$). |
| 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/voucherGenera y descarga el comprobante del envío en formato imagen (por defecto) o PDF.
| Parámetro | Descripción |
|---|---|
| orderNumber* | Número de guía (8 dígitos). |
| orderCode* | Código de seguridad (4 caracteres). |
| format | Formato de descarga: image (default) | pdf. |
curl -X GET "https://api.shalom-api.lat/track/voucher?orderNumber=66479331&orderCode=3KTH&format=pdf" \
-H "x-api-key: TU_API_KEY"Content-Type: image/png
<binario — imagen o PDF del comprobante>/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 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 rastreo se hace con dos datos que el cliente recibe al registrar el envío: el número de orden de 8 dígitos 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 1.000 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.
El estado se refresca solo, con un ritmo que depende de la actividad de la guía: cada 30 minutos mientras se mueve, cada 2 horas cuando lleva un tiempo sin cambios y cada 6 horas en las más antiguas. Las guías ya entregadas dejan de consultarse. Al llamar a POST /track, si el último dato guardado tiene más de 10 minutos se pide el estado en vivo antes de responder.
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 8 dígitos o orderCode no tiene 4 caracteres. |
| 404 | La guía no existe o aún no está registrada en Shalom. |
El número de orden de 8 dígitos 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: se refresca cada 30 min–6 h según la actividad de la guía y, si el dato guardado tiene más de 10 minutos, se consulta en vivo al responder tu llamada. Para reaccionar a los cambios sin consultar, lo eficiente es usar webhooks.
Con GET /track/voucher para el comprobante y GET /track/label para la etiqueta en PDF.
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