Cómo utilizar las API de seguimiento de envíos para enviar notificaciones proactivas de entrega
Para enviar notificaciones proactivas de entrega con una API de seguimiento de envíos, conecta cada paquete con su pedido, incorpora las actualizaciones de seguimiento, traduce esas actualizaciones en eventos relevantes para el cliente y activa mensajes a través de tu servicio de correo electrónico, SMS o notificaciones de la aplicación. Coloca una cola duradera y comprobaciones de duplicados entre los datos de seguimiento entrantes y los mensajes salientes para que las actualizaciones repetidas o retrasadas no generen alertas confusas.
Esta guía está dirigida a desarrolladores y equipos de operaciones de comercio electrónico que crean este flujo de trabajo. El objetivo no es reenviar cada escaneo del transportista, sino informar a los clientes cuando algo importante cambia, qué significa ese cambio y si deben actuar.
Diseña el flujo de notificaciones antes de conectar la API
Una API de seguimiento de envíos proporciona información de seguimiento; tu aplicación decide cómo utilizarla. Trata la visibilidad del envío y la comunicación con el cliente como responsabilidades independientes, aunque el servicio elegido ofrezca ambas.
Una arquitectura práctica consta de seis etapas:
- Asociación del pedido: conecta un número de seguimiento y el identificador del transportista, cuando sea necesario, con un registro interno del envío.
- Registro del seguimiento: envía o registra el envío según los requisitos de integración del proveedor.
- Incorporación de actualizaciones: recibe devoluciones de llamada mediante webhooks, recupera actualizaciones a través de solicitudes de API o combina ambos enfoques.
- Procesamiento de eventos: valida, normaliza, elimina duplicados y evalúa los eventos entrantes.
- Decisión de notificación: decide si se debe notificar, a quién contactar y qué canal y plantilla utilizar.
- Entrega del mensaje: envía la notificación y registra la respuesta del servicio de mensajería.
Mantén la información de contacto del cliente en tu propio sistema de pedidos o mensajería, a menos que la integración realmente requiera compartirla. Por lo general, un servicio de seguimiento no necesita la dirección de correo electrónico del cliente simplemente para que tu aplicación asocie un evento de seguimiento con un pedido.
1. Confirma el contrato de integración
Antes de escribir el receptor, consulta la documentación del proveedor sobre autenticación, registro de envíos, identificación del transportista, métodos de actualización compatibles, formatos de respuesta, límites de solicitudes y gestión de errores. Para las integraciones mediante webhooks, comprueba también cómo se autentican las devoluciones de llamada, qué respuesta confirma la recepción y cómo se gestionan las entregas fallidas.
Para una implementación de 17TRACK, comienza por la página de la API de seguimiento de 17TRACK y su documentación oficial de la API. Utiliza el contrato documentado para tu integración en lugar de tratar los nombres de campos ilustrativos de esta guía como campos de solicitud o respuesta de 17TRACK. Confirma la configuración de las devoluciones de llamada, los requisitos de seguridad y los límites específicos de la cuenta antes de la implementación.
Elige el método de actualización según el contrato de integración:
- Webhooks: utiliza devoluciones de llamada cuando sean compatibles y adecuadas para tu infraestructura. Permiten que tu aplicación procese las actualizaciones cuando el proveedor las envía, sin solicitar repetidamente el mismo envío.
- Consulta periódica: recupera la información de seguimiento según un calendario cuando las devoluciones de llamada no estén disponibles o no sean adecuadas. Mantén el calendario dentro de los límites de solicitudes documentados.
- Enfoque combinado: utiliza devoluciones de llamada para el procesamiento normal y recuperaciones selectivas mediante la API para conciliar los envíos cuyas actualizaciones parezcan obsoletas, si el proveedor admite ese flujo de trabajo.
No prometas a los clientes notificaciones instantáneas simplemente porque utilices webhooks. Tu aplicación no puede informar de un evento del transportista antes de que los datos de seguimiento ascendentes estén disponibles.
2. Crea un registro de envío que resista los pedidos reales
Utiliza un ID interno del envío como referencia principal, no solo el número de seguimiento. Un pedido puede contener varios paquetes y no debe suponerse que los números de seguimiento sean globalmente únicos para siempre.
Un registro interno útil incluye:
- ID interno del pedido y del envío.
- Número de seguimiento e identificador del transportista, cuando se conozcan.
- La referencia del envío del proveedor, si se proporciona.
- Estado normalizado actual y último evento relevante.
- Hora del evento del transportista, incluida su zona horaria o desplazamiento cuando esté disponible.
- La hora en que tu sistema recibió la actualización.
- Una referencia a las preferencias de comunicación del cliente.
- Historial de notificaciones y cualquier flujo de trabajo de incidencias activo.
Almacena la hora del evento por separado de la hora de recepción. Un escaneo que ocurrió antes puede llegar después de un escaneo más reciente. Si tu aplicación ordena únicamente por orden de llegada, puede cambiar por error un envío entregado de nuevo a “en tránsito”.
Para pedidos divididos, vincula las notificaciones al paquete afectado. “Ha llegado un paquete de tu pedido” es más preciso que “Tu pedido ha llegado” cuando otro paquete aún está en movimiento.
3. Asocia los eventos de seguimiento con las decisiones del cliente
Las descripciones de los transportistas son datos operativos, no mensajes preparados para los clientes. Crea una capa de normalización que conserve el evento original y le asigne una categoría interna que tus reglas de notificación puedan comprender.
Las siguientes categorías son conceptos de aplicación sugeridos, no un vocabulario universal de estados de API:
| Categoría interna | Decisión de notificación | Límite de comunicación |
|---|---|---|
| Información del envío recibida | Envía una actualización de preparación solo si resulta útil. | No insinúes que el transportista tiene físicamente el paquete basándote únicamente en la creación de la etiqueta. |
| En tránsito | Considera notificar el primer movimiento relevante. | Suprime los escaneos rutinarios en instalaciones, salvo que cambien el siguiente paso del cliente. |
| En reparto | Notifica cuando un evento compatible indique este estado. | No conviertas el estado en una hora de llegada garantizada. |
| Intento de entrega o recogida necesaria | Envía una notificación que permita actuar. | Incluye plazos o instrucciones de recogida solo cuando estén verificados. |
| Incidencia de entrega | Evalúa la causa y si el cliente debe actuar. | No describas cada incidencia como un paquete perdido. |
| Entregado | Envía una confirmación a nivel de paquete. | No inventes un destinatario, lugar de entrega ni comprobante de entrega. |
Conserva la incertidumbre. Un evento no reconocido debe pasar a una ruta de revisión o alternativa en lugar de forzarse dentro de la categoría conocida más cercana. Mantén la descripción sin procesar disponible para el personal de soporte para facilitar la resolución de problemas.
4. Recibe actualizaciones sin perder ni duplicar trabajo
Tu endpoint de webhook debe validar la solicitud, guardar de forma duradera la actualización aceptada y devolver la confirmación requerida por el proveedor. Genera los mensajes de forma asíncrona en lugar de esperar a un servicio de correo electrónico o SMS durante la solicitud de devolución de llamada.
Implementa el método documentado por el proveedor para verificar las devoluciones de llamada. No inventes una cabecera de firma ni supongas que todos los proveedores utilizan el mismo esquema de autenticación. Aplica también HTTPS, límites de tamaño de solicitud, validación de cargas útiles y controles de acceso adecuados.
Un flujo de procesamiento simplificado sería el siguiente. Son operaciones a nivel de aplicación, no un ejemplo funcional de SDK:
recibir devolución de llamada
verificar la solicitud mediante el mecanismo documentado del proveedor
validar la carga útil
conservar la carga útil aceptada y poner el procesamiento en cola de forma atómica
devolver la confirmación documentada
procesar la actualización en cola
encontrar el envío interno
normalizar los eventos relevantes
ignorar los eventos ya procesados
evaluar la cronología y la transición de estado
crear un trabajo de notificación si la política lo permite
confirmar el estado y el trabajo conjuntamente
enviar el trabajo de notificación
comprobar las preferencias del destinatario y las reglas de supresión
enviar el mensaje al servicio de mensajería
registrar el resultado y reintentar solo cuando corresponda
Los pasos atómicos son importantes. Si tu aplicación guarda un cambio de estado pero falla antes de crear el trabajo de notificación, es posible que el cliente nunca reciba la alerta. Un buzón de salida transaccional es una opción de diseño: guarda el cambio de estado y el trabajo pendiente en la misma transacción de base de datos y permite que un trabajador envíe el trabajo.
Gestiona explícitamente las referencias de envíos desconocidas. Ponlas en cuarentena para investigarlas o conciliarlas en lugar de adivinar qué cliente debería recibir una notificación.
5. Añade protección contra duplicados y comprobaciones cronológicas
Diseña el receptor para tolerar devoluciones de llamada repetidas y reintentos de los trabajadores. Da preferencia a un identificador de evento estable del proveedor cuando esté documentado. De lo contrario, crea una huella determinista del evento a partir de campos adecuados, como el ID interno del envío, el código del evento, la hora del evento y la ubicación. Prueba esa huella con cargas útiles reales antes de confiar en ella.
La eliminación de duplicados de eventos y la supresión de notificaciones resuelven problemas diferentes. La eliminación de duplicados evita que el mismo evento se procese dos veces. La supresión evita que varios escaneos distintos generen esencialmente el mismo mensaje para el cliente.
Define la identidad de una notificación en torno al evento de negocio. Una confirmación de entrega podría utilizar el ID del envío y el hito de entrega. Un intento de entrega puede necesitar una identidad específica del intento, porque un intento posterior puede ser realmente un evento nuevo.
Para las actualizaciones fuera de orden, compara las marcas de tiempo de los eventos y evalúa las transiciones de estado permitidas. No supongas que una devolución de llamada contiene únicamente un escaneo nuevo; comprueba si su estructura documentada representa un evento individual, una instantánea o un historial. Envía las actualizaciones contradictorias a conciliación en lugar de descartar silenciosamente todas las correcciones.
6. Escribe mensajes que expliquen qué sucede después
Cada notificación debe indicar el paquete relevante, el cambio confirmado y el siguiente paso del cliente. Incluye un enlace de seguimiento seguro y una referencia de pedido reconocible. Evita exponer direcciones completas o información personal innecesaria en mensajes SMS y vistas previas de la pantalla de bloqueo.
Por ejemplo:
- En reparto: “Tu paquete del pedido {order_reference} está en reparto. Sigue su progreso aquí: {tracking_link}”.
- Entrega intentada: “El transportista ha informado de un intento de entrega de tu paquete. Consulta la página de seguimiento para conocer los siguientes pasos disponibles: {tracking_link}”.
- Entregado: “El transportista ha marcado como entregado tu paquete del pedido {order_reference}. Consulta los detalles de entrega disponibles: {tracking_link}”.
Representa los marcadores de posición únicamente a partir de datos validados. Si hay una estimación de entrega disponible y es adecuada para mostrarla, indícala como estimación. Si falta, omítela en lugar de inventar una fecha.
En el caso de las incidencias, distingue entre un problema del envío y una tarea del cliente. Una interrupción puede requerir únicamente una explicación; un problema de dirección verificado puede requerir una acción. No dirijas a los clientes a una página de pago o de carga de documentos basándote únicamente en contenido de texto libre de seguimiento que no sea de confianza.
Elige los canales utilizando las preferencias del cliente, los permisos del canal, la urgencia y las normas aplicables. Revisa los requisitos de consentimiento, exclusión voluntaria y horario de silencio para las jurisdicciones y los canales de mensajería que utilices. Mantén las notificaciones del servicio de entrega separadas de las campañas promocionales en lugar de suponer que los mismos permisos cubren ambas.
7. Define qué ocurre cuando el seguimiento se queda sin actualizaciones
La comunicación proactiva debe cubrir tanto la falta de progreso como los eventos nuevos, pero el silencio por sí solo no demuestra que un envío esté retrasado o perdido.
Crea una regla de seguimiento obsoleto utilizando el nivel de servicio, la ruta, el último evento relevante y cualquier estimación de entrega compatible. Establece los umbrales a partir de tus datos operativos y tu proceso de soporte, en lugar de aplicar un único periodo de espera universal a todos los envíos.
Cuando se active esa regla, comprueba si se ha omitido algún procesamiento, concilia con la fuente de seguimiento cuando sea compatible y decide si debes abrir una tarea interna de soporte. Si notificas al cliente, utiliza un texto que refleje lo que sabes: “No hemos recibido una nueva actualización de seguimiento” es diferente de “Tu paquete se ha perdido”.
Asigna un responsable a las incidencias sin resolver. Un sistema de notificaciones que anuncia repetidamente un problema sin crear una vía para resolverlo puede aumentar la frustración del cliente.
8. Prueba todo el flujo antes de activar los envíos automáticos
Ejecuta primero el flujo en modo de prueba silenciosa: incorpora eventos reales o de prueba aprobados, genera notificaciones propuestas y revisa los resultados sin contactar con los clientes.
- Reproduce una devolución de llamada idéntica y confirma que no crea otro mensaje.
- Procesa un evento de tránsito antiguo después de un evento de entrega y revisa el estado resultante.
- Prueba marcas de tiempo ausentes, estados desconocidos y cargas útiles malformadas.
- Simula un fallo de la base de datos antes de la confirmación y un fallo del trabajador después de la persistencia.
- Prueba los tiempos de espera de mensajería, incluida una respuesta incierta en la que el servicio ya podría haber aceptado el mensaje.
- Confirma que los envíos divididos producen textos específicos para cada paquete.
- Comprueba los destinatarios que han cancelado su suscripción, los datos de contacto no válidos y la gestión de los horarios de silencio.
- Verifica que los enlaces de seguimiento no expongan la información del pedido de otro cliente.
Supervisa las devoluciones de llamada aceptadas, los fallos de procesamiento, la antigüedad de la cola, los trabajos de notificación, la supresión de duplicados y los resultados de mensajería. Mide por separado la latencia de procesamiento desde la hora de recepción de tu sistema y la antigüedad del evento del transportista. Esta distinción ayuda a identificar si una notificación lenta se debió a la disponibilidad de datos ascendentes o a tu propio flujo.
Comienza con un pequeño conjunto de hitos bien comprendidos. Amplía las reglas solo después de que los equipos de soporte y operaciones acuerden que los mensajes son precisos, permiten actuar y merecen recibirse.
Preguntas frecuentes
¿Una API de seguimiento de envíos envía automáticamente correos electrónicos o mensajes SMS?
No necesariamente. El acceso a los datos de seguimiento y la mensajería para clientes son capacidades independientes. Consulta el alcance documentado del servicio. En una integración personalizada, tu aplicación puede procesar las actualizaciones de seguimiento y enviar notificaciones mediante un servicio de mensajería independiente.
¿Debo notificar a los clientes sobre cada escaneo de seguimiento?
Por lo general, no. Da prioridad a los hitos relevantes y a los eventos que requieran actuar. Varios escaneos en instalaciones pueden representar un tránsito normal sin cambiar lo que el cliente necesita saber. Conserva el historial detallado en la página de seguimiento.
¿Puedo garantizar notificaciones de entrega en tiempo real?
Puedes establecer y supervisar un objetivo de procesamiento después de que tu sistema reciba una actualización. No puedes garantizar cuándo un transportista registrará o publicará un escaneo. Describe el servicio en términos que reflejen esa dependencia.
¿Cómo puedo evitar los mensajes de entrega duplicados?
Utiliza una eliminación persistente de duplicados de eventos, una identidad de notificación independiente para cada hito de negocio y la creación transaccional de trabajos. Cuando tu servicio de mensajería admita la idempotencia, utilízala como protección adicional. Una comprobación de duplicados únicamente en memoria no sobrevivirá a los reinicios ni a varios trabajadores.
¿Qué debe ocurrir si el transportista corrige un estado de entregado?
Conserva ambos eventos y concilia el estado del envío. Si la corrección afecta de forma significativa al cliente, envía una corrección clara o dirígela al soporte según tu política. No hagas que el estado de entregado sea permanentemente irreversible solo para simplificar el código.
Fuentes
Los siguientes recursos oficiales son las referencias de implementación para la integración de 17TRACK descrita anteriormente. El esquema interno, las reglas de notificación y el flujo de procesamiento de esta guía son recomendaciones arquitectónicas, no contratos de API citados.
- API de seguimiento de 17TRACK — punto de partida oficial para evaluar la integración de la API.
- Documentación de la API de 17TRACK — referencia para los formatos de solicitud específicos del proveedor, la autenticación, las operaciones de seguimiento y los requisitos de integración.


