Shalom API guarda una copia del estado de cada guía de Shalom y la actualiza por su cuenta, para que POST /track responda rápido y los webhooks avisen sin que tengas que preguntar en bucle. Para que eso escale sin saturar el sistema de Shalom, la actualización automática sigue unas reglas. Ninguna cambia los endpoints ni el formato de las respuestas.
Solo las guías suscritas se actualizan en segundo plano
La actualización automática es para las guías con una suscripción activa (POST /tracking/subscriptions). Son las que necesitan un aviso por webhook en cuanto cambian.
Una guía que solo consultaste con POST /track, sin suscribirla, no se vigila en segundo plano. Cuando la vuelves a consultar, si el dato guardado tiene más de 10 minutos, pedimos el estado en vivo antes de responderte. Para tu integración el resultado es el mismo: siempre recibes el estado actual.
Si quieres avisos automáticos de una guía, suscríbela justo después de crearla. Al suscribirla entra de inmediato a la actualización en segundo plano.
Ritmo de actualización
Las guías suscritas se consultan con un ritmo que depende de su actividad: cada 30 minutos cuando acaban de cambiar de estado, cada 2 horas mientras siguen en camino sin cambios y cada 3 horas cuando ya están en la agencia destino esperando recojo. Una vez entregadas no se vuelven a consultar.
Pausa nocturna
Entre las 22:00 y las 06:00, hora de Lima, no se hacen consultas en segundo plano. En ese horario Shalom casi no informa movimientos que el comprador necesite saber al momento.
Si una guía cambia de noche, el webhook llega a partir de las 06:00. Los avisos acumulados se reparten hasta las 07:30. POST /track no tiene pausa: de noche también consulta el estado en vivo cuando el dato guardado tiene más de 10 minutos.
Guías inactivas (DORMANT)
Una guía deja de vigilarse en segundo plano cuando lleva 20 días sin ningún movimiento o cuando Shalom la marca como devuelta o anulada. No se borra ni pierde su historial.
Vuelve a vigilarse sola si la consultas con POST /track y el estado en vivo muestra un cambio. También si la suscribes de nuevo con POST /tracking/subscriptions, aunque ya estuviera suscrita: eso le da otros 20 días de seguimiento.
Consultas en vivo más livianas
Cuando una guía ya tiene su identificador interno de Shalom guardado, la actualización en segundo plano solo pide su línea de tiempo. Si la línea de tiempo cambió, se descarga la guía completa para refrescar también el resto de los datos (monto, estado de pago, agencias). Así la respuesta de POST /track y el payload del webhook siempre traen los datos completos y al día.
Qué te conviene hacer
Suscribe las guías de las que necesitas avisos automáticos: sin suscripción solo se actualizan cuando las consultas.
No consultes POST /track en bucle para enterarte de los cambios. Usa webhooks y te llegará un POST firmado solo cuando algo cambie.
Si una guía estuvo detenida mucho tiempo y la vuelves a necesitar, suscríbela de nuevo para reactivar su seguimiento.