Cómo conectar los datos de seguimiento de envíos a un Oms: mapeo de pedidos y reglas de sincronización
Para conectar los datos de seguimiento de envíos con un sistema de gestión de pedidos (OMS), asigna cada paquete rastreado a un registro de envío interno y, después, vincula ese envío con sus líneas de pedido y de cumplimiento. Recibe las actualizaciones de seguimiento mediante la interfaz compatible del proveedor, conserva los eventos originales y aplica reglas explícitas para los duplicados, las actualizaciones tardías, el estado del envío y la finalización del pedido. No uses únicamente un número de seguimiento como identificador del pedido ni permitas que un solo evento de entrega cierre automáticamente un pedido con varios paquetes.

Esta guía está dirigida a ingenieros de integración y equipos de operaciones de comercio electrónico que implementan esta conexión. El diseño recomendado separa las observaciones del transportista de las decisiones comerciales: los datos de seguimiento describen el recorrido de un paquete, mientras que el OMS decide qué significa ese recorrido para el cumplimiento, la comunicación con el cliente y el cierre del pedido.
Define qué sistema es responsable de cada registro
Antes de crear una conexión mediante API, acuerda la responsabilidad con el administrador del OMS, el equipo de cumplimiento y el equipo de atención al cliente. De lo contrario, una integración técnicamente correcta aún podría sobrescribir datos comerciales válidos.
- OMS: Es responsable de los pedidos, las líneas de pedido, las cantidades requeridas, las cancelaciones y las reglas para completar los pedidos.
- Sistema de cumplimiento: Es responsable de los registros de envíos o paquetes que crea, incluidas las asignaciones de embalaje y las asignaciones de etiquetas. Puede ser el propio OMS o un sistema de almacén independiente.
- Proveedor de seguimiento: Proporciona observaciones de seguimiento y cualquier clasificación de estado definida por el proveedor.
- Capa de integración: Es responsable de las referencias cruzadas de identificadores, el procesamiento de eventos, la normalización, la gestión de reintentos y los registros de auditoría de sincronización.
Trata estos puntos como límites recomendados, no como suposiciones sobre tu software. Documenta las excepciones. Por ejemplo, si el almacén puede sustituir una etiqueta de envío, la integración necesita una actualización explícita de ese sistema en lugar de suponer que un número observado recientemente reemplaza a uno anterior.
Crea la asignación de pedido a paquete antes de sincronizar los estados
Una relación práctica es pedido → cumplimiento → paquete → asignación de seguimiento. Tu OMS puede utilizar nombres diferentes o combinar algunos de estos registros. Conserva las relaciones aunque la estructura de la base de datos sea distinta.
Un pedido puede tener varios cumplimientos y un cumplimiento puede contener varios paquetes. Un paquete también puede adquirir una nueva asignación de seguimiento o un identificador de última milla vinculado. Esos identificadores no deben crear cantidades adicionales solicitadas.
| Registro | Campos recomendados | Finalidad |
|---|---|---|
| Pedido | ID del comercio o de la tienda, ID inmutable del pedido en el OMS | Separa a los comerciantes y evita depender de los números de pedido visibles. |
| Cumplimiento | ID de cumplimiento, ID del pedido, ID y cantidades de las líneas asignadas | Identifica qué artículos comprados se están procesando. |
| Paquete | ID interno del paquete, ID de cumplimiento, asignaciones del paquete cuando estén disponibles | Proporciona una identidad estable independiente de las etiquetas de seguimiento. |
| Asignación de seguimiento | ID de asignación, ID del paquete, cuenta del proveedor, identificador del transportista, número de seguimiento, periodo de actividad | Vincula las observaciones de seguimiento entrantes con el paquete correcto y el ciclo de vida de la asignación. |
Relaciona las actualizaciones mediante una referencia cruzada almacenada
Cuando se cree un envío, conserva sus ID internos antes de registrarlo para el seguimiento. Almacena cualquier ID de registro de seguimiento emitido por el proveedor que devuelva el proceso de registro documentado. Si el proveedor admite una referencia del comerciante, utiliza una referencia interna opaca y conserva la correspondencia localmente.
Para las actualizaciones entrantes, resuelve primero el ID de registro del proveedor almacenado dentro de la cuenta correcta del proveedor y del comercio. Si ese identificador no está disponible, utiliza la combinación documentada de número de seguimiento, identidad del transportista, contexto de la cuenta e historial de asignaciones. Trátalo como una estrategia de búsqueda, no como una garantía de que la combinación sea globalmente única.
No hagas coincidencias por nombre del cliente, dirección de correo electrónico ni número de pedido visible sin ámbito. Conserva los números de seguimiento como cadenas para que no se pierdan los ceros iniciales. Evita eliminar caracteres o cambiar mayúsculas y minúsculas, salvo que el contrato del transportista o proveedor correspondiente permita esa normalización.
Si una búsqueda no devuelve coincidencias o devuelve varias coincidencias posibles, pon la actualización en cuarentena para investigarla. Un evento sin resolver es más seguro que una actualización segura pero incorrecta del pedido de otro cliente.
Gestiona los pedidos divididos sin inventar asignaciones de paquetes
Considera un pedido ilustrativo que contiene tres unidades. El paquete A transporta dos unidades y el paquete B transporta una. La entrega del paquete A significa que existen pruebas de entrega para dos unidades; no significa que se haya entregado todo el pedido.
Si el sistema de cumplimiento solo registra que ambos paquetes pertenecen al mismo cumplimiento, no inventes asignaciones a nivel de unidad. Aún puedes calcular si se han entregado todos los paquetes requeridos, pero los informes de entrega a nivel de artículo deben permanecer no disponibles o indicarse explícitamente como inciertos hasta que existan datos de asignación.
Conecta la API de seguimiento mediante una capa de ingesta duradera
Utiliza una canalización que mantenga separada la comunicación con el proveedor de las escrituras en el OMS:
Creación del envío → registro del seguimiento → actualización entrante o recuperación programada → almacenamiento duradero del evento → asignación y normalización → actualización del OMS → conciliación
Para una implementación de 17TRACK, la página del producto Tracking API y la documentación oficial de la API son los puntos de partida pertinentes. Confirma la interfaz de registro aplicable, los identificadores de transportistas, las opciones de entrega de actualizaciones, los requisitos de autenticación, las definiciones de estado y los límites de la cuenta antes de implementar el adaptador. El modelo de datos de esta guía es una recomendación de integración, no una afirmación de que 17TRACK utilice estos nombres de campo o proporcione un conector nativo para tu OMS.
Si el proveedor seleccionado admite webhooks, autentica las solicitudes entrantes mediante su mecanismo documentado y almacena de forma duradera los mensajes aceptados antes de confirmarlos. Mantén el trabajo lento del OMS fuera de la ruta de solicitud. Sigue el contrato real de confirmación y reintentos del proveedor en lugar de asumir un cuerpo de respuesta o un tiempo de espera concretos.
Si es necesario realizar consultas periódicas, almacena el progreso de recuperación cuando la API lo admita, controla la concurrencia y respeta los límites de frecuencia documentados. Ni la recepción de un webhook ni una solicitud de consulta correcta demuestran que el OMS se haya actualizado; registra esos resultados por separado.
Define reglas de sincronización que resistan los reintentos y los eventos tardíos
1. Haz que el procesamiento sea idempotente
Procesar dos veces la misma observación no debe duplicar un envío, avanzar las cantidades dos veces ni volver a enviar la misma notificación al cliente. HTTP no convierte una operación POST arbitraria en idempotente; la integración debe implementar protección contra duplicados. RFC 9110 explica la idempotencia de los métodos HTTP.
Utiliza un ID de evento estable del proveedor cuando esté documentado y disponible. De lo contrario, define una huella a partir del ID de asignación y de los campos relevantes del evento, como la marca de tiempo del evento, el estado de origen y la ubicación. Documenta la posibilidad de colisiones o de cambios en las descripciones de los eventos. Conserva la observación sin procesar incluso cuando no produzca otra acción en el OMS.
Protege cada efecto secundario por separado. Por ejemplo, una escritura de estado en el OMS y una notificación por correo electrónico necesitan sus propios controles de deduplicación. Utiliza un buzón de salida transaccional o un registro de trabajo duradero equivalente para que un fallo del proceso no deje un evento aceptado sin una actualización programada.
2. Almacena por separado la hora del evento y la hora de recepción
La hora en que ocurre un evento y la hora en que lo recibe tu integración responden a preguntas diferentes. Almacena ambas, junto con la representación original de la marca de tiempo y cualquier desfase horario proporcionado. No asignes silenciosamente la zona horaria del almacén a un evento cuya zona horaria se desconoce.
Una lectura tardía de un envío en tránsito normalmente debe enriquecer el historial sin reemplazar un estado entregado más reciente. Sin embargo, las marcas de tiempo por sí solas no son suficientes: un proveedor puede emitir una corrección y los eventos pueden tener información temporal incompleta. Utiliza los campos de secuencia o revisión documentados cuando estén disponibles, junto con una política de corrección explícita.
3. Normaliza los estados sin borrar los detalles de origen
Crea un vocabulario interno reducido que el OMS pueda entender, como en espera de aceptación del transportista, en tránsito, en reparto, entregado, incidencia y en devolución. Asigna los estados documentados del proveedor a estas categorías. Son categorías internas sugeridas, no definiciones universales de los transportistas.
Almacena el código de estado original, la descripción, la ubicación del evento, la referencia del registro del proveedor y la versión de la regla de asignación. Un valor no asignado debe generar una condición revisable en lugar de establecerse por defecto como entregado o fallido. La creación de una etiqueta no debe considerarse una prueba de aceptación física por parte del transportista, salvo que el evento de origen respalde explícitamente esa interpretación.
4. Utiliza reglas de transición, no una clasificación numérica simple
Los estados de los envíos no siempre forman una línea recta. Una incidencia puede ir seguida de un tránsito normal y un intento de entrega no equivale a una entrega. El movimiento de devolución puede comenzar después de un evento de entrega anterior.
- Permite que una incidencia se resuelva cuando las pruebas posteriores respalden la reanudación del movimiento.
- Impide que una lectura histórica ordinaria sustituya silenciosamente un estado entregado.
- Permite una corrección documentada mediante una ruta de revisión controlada.
- Realiza el seguimiento del movimiento de devolución por separado de la finalización de la salida cuando el OMS lo admita.
- Envía las pruebas ambiguas o contradictorias a una cola operativa.
Versiona estas reglas. Cuando cambie una asignación, decide si se aplica únicamente a los eventos nuevos o si los registros históricos requieren un recálculo controlado.
Calcula el estado del pedido a partir de las obligaciones de cumplimiento requeridas
El estado del paquete y el estado del pedido deben ser campos separados. Un paquete marcado como entregado proporciona pruebas para ese paquete; la finalización del pedido depende de las cantidades requeridas restantes y de tu política comercial.
Un valor predeterminado útil es marcar un pedido como completamente entregado solo cuando todas las cantidades que requieren entrega tengan pruebas válidas de entrega a nivel de paquete y no queden asignaciones requeridas sin resolver. Excluye las cantidades canceladas conforme a las reglas de cancelación del OMS. Gestiona los artículos digitales, los pedidos para recoger y otras obligaciones no relacionadas con el envío mediante sus propias condiciones de finalización.
Los envíos de sustitución requieren relaciones explícitas. Si se sustituye un paquete perdido, decide si el envío de sustitución reemplaza la obligación de entrega original. De lo contrario, el paquete original podría impedir indefinidamente la finalización o ambos paquetes podrían contabilizarse para el cumplimiento. Registra la decisión en lugar de derivarla únicamente del estado de seguimiento.
Mantén separadas la finalización de la entrega, el cierre financiero, la elegibilidad para reembolsos y la resolución de disputas. Un evento de entrega del transportista no debe autorizar automáticamente un reembolso ni resolver una reclamación del cliente.
Recupérate de los fallos sin perder el registro de auditoría
Reintenta los fallos transitorios mediante un retroceso limitado y cualquier orientación de reintento documentada. Separa los fallos temporales de conexión de los identificadores no válidos, las credenciales caducadas, los errores de permisos y las incompatibilidades de esquema. Estos últimos requieren medidas correctivas, no reintentos indefinidos.
Mantén una cola de trabajos fallidos que contenga el comercio afectado, el paquete, la referencia del evento, la operación intentada, la clasificación del error y la siguiente acción. Registra suficiente contexto para investigar sin copiar en los registros datos innecesarios del cliente ni credenciales.
Ejecuta conciliaciones además de la ruta normal de actualización. Revisa los envíos activos con información de seguimiento obsoleta, los eventos aceptados cuyas escrituras en el OMS fallaron, las observaciones sin coincidencia y las diferencias entre el estado calculado por la integración y el OMS. Elige la frecuencia de revisión según los compromisos de entrega, los límites de la API y el riesgo operativo, en lugar de aplicar un calendario universal arbitrario.
Asigna responsabilidades: ingeniería gestiona la ingesta y los fallos de escritura; las operaciones de cumplimiento resuelven las relaciones de paquetes que faltan; el servicio de atención al cliente revisa las excepciones que requieren comunicación con el cliente. Una cola sin un responsable asignado es solo una ubicación de almacenamiento.
Prueba la asignación y las reglas comerciales antes del lanzamiento
Utiliza datos de prueba controlados y un lanzamiento limitado en producción. Prueba los siguientes casos tanto con el historial de eventos como con el registro resultante del OMS:
- Un pedido de un solo paquete avanza normalmente hasta la entrega.
- Un pedido dividido tiene un paquete entregado y otro aún en movimiento.
- El mismo evento se recibe repetidamente sin efectos secundarios duplicados.
- Una lectura de tránsito antigua llega después de la entrega.
- Un transportista o estado desconocido entra en la cola de revisión.
- Se sustituye una etiqueta sin crear otra obligación de cumplimiento.
- Un envío de sustitución reemplaza un paquete original conforme a una regla aprobada.
- El OMS no está disponible después de que se haya aceptado un evento.
- Un proceso se reinicia entre una escritura en el OMS y su confirmación.
- El mismo número de pedido visible existe en dos tiendas sin coincidencia entre comercios.
Realiza el lanzamiento cuando cada evento aceptado tenga un resultado de procesamiento rastreable, las coincidencias ambiguas no puedan actualizar pedidos automáticamente y los operadores puedan reproducir los trabajos fallidos de forma segura. Estos son criterios de aceptación más útiles que demostrar simplemente que una solicitud a la API funciona.
Preguntas frecuentes
¿Puedo conectar directamente los números de seguimiento con los pedidos?
En un flujo estrictamente de un solo paquete, una relación directa puede ser suficiente inicialmente. Aun así, utiliza una identidad de envío interna entre el pedido y la asignación de seguimiento. Esto proporciona una vía de migración para envíos divididos, reetiquetados y sustituciones sin cambiar el significado del registro del pedido.
¿La integración debe utilizar webhooks o consultas periódicas?
Utiliza el mecanismo de entrega compatible con el proveedor y con tu infraestructura. Los webhooks pueden reducir las recuperaciones repetidas, mientras que las consultas periódicas pueden admitir flujos basados en recuperación y conciliaciones cuando estén disponibles. Ninguno de los dos enfoques elimina la necesidad de almacenamiento duradero, gestión de duplicados y recuperación.
¿Qué debe ocurrir cuando un evento de seguimiento no tiene un pedido coincidente?
Almacénalo en una cola de eventos sin coincidencia e investiga el registro de alta, el contexto del comercio, la identidad del transportista y el momento de creación del envío. No crees un pedido ni asocies automáticamente el evento a un cliente plausible. Reprodúcelo después de corregir la asignación.
¿Las notificaciones de entrega deben proceder del OMS o del sistema de seguimiento?
Elige un único responsable para cada tipo de notificación y activador. Si dos sistemas pueden enviar el mismo mensaje, desactiva una ruta o comparte un registro de notificaciones duradero. Decide también si el mensaje se refiere a un paquete o al pedido completo, especialmente en casos de cumplimiento dividido.
¿Un estado de incidencia significa que el pedido ha fallado?
No. Una incidencia es una observación que requiere interpretación, no necesariamente un resultado permanente. Conserva el motivo, supervisa los eventos posteriores y utiliza tu política de escalamiento para decidir cuándo deben intervenir las operaciones.
Fuentes
- API de seguimiento de 17TRACK — referencia oficial del producto y punto de partida para la integración de la API.
- Documentación de la API de 17TRACK — referencia de implementación para el contrato específico del proveedor; verifica las interfaces aplicables y los requisitos de la cuenta antes de la implementación.
- RFC 9110, sección 9.2.2: métodos idempotentes — semántica HTTP que respalda la distinción entre la idempotencia de los métodos y la protección contra duplicados a nivel de aplicación.


