Cómo integrar una API de seguimiento de envíos en tu tienda de comercio electrónico
Para integrar una API de seguimiento de envíos en tu tienda de comercio electrónico, conecta tu sistema de pedidos con el proveedor de seguimiento, envía los datos del envío y del transportista mediante una solicitud segura del lado del servidor, guarda los eventos de seguimiento normalizados y muestra el estado resultante en las interfaces de clientes y de soporte. Una implementación fiable es más que añadir un campo para el número de seguimiento: debe gestionar la selección del transportista, las actualizaciones de estado, las incidencias de entrega, los reintentos, la privacidad y la forma en que los clientes utilizan realmente la información posterior a la compra.
Esta guía explica un enfoque práctico de integración para propietarios de tiendas, desarrolladores y equipos de operaciones. Utiliza la documentación oficial de Tracking API de 17TRACK como referencia, pero los mismos principios de planificación se aplican al evaluar otro proveedor de múltiples transportistas.
Decide qué debe lograr la integración
Comienza por el resultado empresarial en lugar del endpoint de la API. La mayoría de las tiendas quieren reducir los contactos de «¿Dónde está mi pedido?», ofrecer a los compradores una vista clara de la entrega y ayudar a operaciones a identificar los envíos retrasados antes de que el cliente se queje. Estos objetivos requieren datos y flujos de trabajo diferentes.
- Visibilidad para el cliente: mostrar el estado actual del envío, la información estimada de entrega cuando esté disponible, los datos del transportista y el último evento relevante.
- Visibilidad operativa: permitir que el personal encuentre envíos retrasados, detenidos, devueltos o con incidencias entre distintos transportistas.
- Comunicación automatizada: activar correos electrónicos, SMS u otras notificaciones aprobadas cuando un envío alcance un estado definido.
- Coherencia de los datos: convertir las distintas etiquetas de eventos de los transportistas en un conjunto más reducido de estados que tu tienda pueda utilizar de forma fiable.
Define estos resultados antes de elegir un método de implementación. Una API de seguimiento puede proporcionar datos del envío, pero no decide automáticamente qué eventos merecen una notificación al cliente ni cómo debe gestionar tu tienda un problema de dirección.
Elige la arquitectura de integración adecuada
Una arquitectura típica tiene cuatro capas: la plataforma de comercio, un servicio de integración, el proveedor de seguimiento y la experiencia orientada al cliente. El servicio de integración puede ser una aplicación backend, un sistema de gestión de pedidos o un flujo de trabajo sin servidor. Mantener esta lógica en el servidor suele ser más seguro que colocar las credenciales de la API en el código del navegador.
El flujo básico es el siguiente:
- Se prepara un pedido pagado y recibe un número de seguimiento y un transportista.
- Tu backend envía los detalles del envío al proveedor de seguimiento.
- El proveedor devuelve un identificador de seguimiento o datos de seguimiento según el diseño de su API.
- Tu sistema guarda la referencia del proveedor y asigna los eventos del envío a estados internos.
- Un proceso de actualización programado o una notificación de eventos compatible actualiza el envío.
- Tu tienda, la página del pedido, las herramientas de soporte y el servicio de notificaciones leen de tus propios datos normalizados.
No hagas que cada vista de página llame al transportista o a la API de seguimiento. Ese diseño puede generar experiencias lentas para los clientes, solicitudes duplicadas, problemas de límite de solicitudes y resultados incoherentes. Guarda en tu base de datos el último estado de seguimiento aceptado y actualízalo mediante tareas en segundo plano controladas o el mecanismo de actualización compatible del proveedor.
Confirma la documentación del proveedor antes de programar
Antes de la implementación, revisa la documentación oficial de la API del proveedor para conocer la autenticación, los formatos de solicitud, los campos de respuesta, los transportistas compatibles, el comportamiento ante errores, los mecanismos de actualización y los requisitos de la cuenta. 17TRACK ofrece una página del producto Tracking API específica y documentación para desarrolladores. Considera esas páginas como la autoridad sobre el comportamiento actual de la API, en lugar de basarte en ejemplos copiados de foros o tutoriales antiguos de integración.
Elabora una breve lista de requisitos a partir de la documentación:
- ¿Cómo se emiten, almacenan, rotan y revocan las credenciales de la API?
- ¿La solicitud requiere un código de transportista o el servicio puede identificarlo a partir del número de seguimiento?
- ¿Qué campos de respuesta identifican el envío, el estado, la ubicación, las marcas de tiempo y el mensaje de incidencia?
- ¿Cómo se entregan las actualizaciones asíncronas, si la cuenta las admite?
- ¿Cuáles son los límites de solicitudes documentados, las reglas de facturación, las expectativas de tiempo de espera y los códigos de error?
- ¿Cómo deben gestionarse los números de seguimiento duplicados, los números no válidos, los transportistas desconocidos y los envíos entregados?
No deduzcas una función a partir del nombre de un producto. Por ejemplo, «tiempo real» puede describir una declaración de posicionamiento del producto en lugar de garantizar que cada evento del transportista aparezca inmediatamente. Tu implementación debe explicar que los escaneos del transportista pueden retrasarse y que una API no puede crear un escaneo que el transportista no haya notificado.
Prepara los datos del pedido y del envío
El momento más útil para crear el seguimiento normalmente es cuando se prepara el envío, no cuando se crea el pedido. Un pedido puede estar pagado pero aún no embalado, y un número de seguimiento puede generarse antes de que el transportista acepte el paquete. Decide qué evento de tu flujo de preparación debe crear el registro de seguimiento.
Como mínimo, tu registro interno del envío debe distinguir los siguientes valores:
- ID interno del pedido e ID de preparación
- Número de seguimiento
- Nombre o código del transportista
- País o región de destino, cuando sea necesario desde el punto de vista operativo
- ID de seguimiento del proveedor o referencia de suscripción, si se devuelve
- Estado normalizado actual
- Marca de tiempo del último evento y de la última sincronización
- Respuesta sin procesar del proveedor o una referencia de auditoría controlada
Mantén separados los datos del pedido y los datos del envío. Un pedido puede contener varios paquetes, envíos divididos o distintos transportistas. La suposición de una relación de un pedido con un único número de seguimiento suele fallar cuando un almacén envía los artículos por separado.
Utiliza un proceso idempotente. Si el sistema de preparación reintenta la misma solicitud, la integración debe actualizar el envío existente en lugar de crear suscripciones duplicadas o mensajes duplicados para el cliente. Una clave de idempotencia práctica puede combinar tu ID interno de preparación, el identificador del transportista y el número de seguimiento, según los requisitos del propio proveedor.
Normaliza los estados de los transportistas para los clientes
Los transportistas utilizan etiquetas y secuencias de eventos diferentes. Tu tienda debe mantener un modelo de estados interno reducido, como Información recibida, En tránsito, En reparto, Entregado, Incidencia y Devuelto. Conserva el evento original del transportista para el personal de soporte, pero utiliza el estado normalizado para la lógica de la tienda.
Las reglas de normalización deben ser explícitas. Un evento de «etiqueta creada» no debe presentarse como prueba de que el paquete está avanzando. «Entregado» debe tratarse como un evento notificado por el transportista, no como una garantía de que el cliente haya localizado físicamente el paquete. Una incidencia no debe convertirse silenciosamente en «en tránsito» simplemente porque el envío pueda continuar más adelante.
Define también la precedencia de estados y la gestión de regresiones. Un flujo de datos retrasado del transportista puede llegar fuera de orden. Compara las marcas de tiempo de los eventos cuando estén disponibles, registra el evento sin procesar y evita reemplazar un estado de entrega más reciente por un estado de tránsito anterior. Si las marcas de tiempo faltan o son ambiguas, marca el registro para una actualización conservadora en lugar de inventar una secuencia.
Construye el flujo de solicitudes del lado del servidor
Tu backend debe validar los datos de preparación entrantes antes de llamar al proveedor de seguimiento. Comprueba que el número de seguimiento esté presente, elimina los espacios en blanco accidentales, valida el formato esperado cuando corresponda y confirma que el valor del transportista sea válido. No rechaces números de seguimiento inusuales pero válidos únicamente porque no coincidan con un patrón local demasiado restrictivo.
Un flujo de solicitud independiente del proveedor puede representarse así:
recibir evento de preparación
validar los campos del pedido y del envío
comprobar si existe una clave de idempotencia
enviar la solicitud de seguimiento documentada desde el servidor
guardar la respuesta del proveedor y el registro interno del envío
programar una actualización o procesar el evento compatible
publicar únicamente los campos aprobados en la tiendaUtiliza tiempos de espera cortos, reintentos limitados y retroceso exponencial para los fallos temporales. No reintentes todos los errores. Un fallo de autenticación, una solicitud no válida o un transportista no compatible normalmente requieren una corrección, no llamadas repetidas. Registra un ID de correlación, el resultado de la solicitud y la categoría del error del proveedor, pero evita escribir claves de API, direcciones completas de clientes o información personal innecesaria en los registros de la aplicación.
Mantén separada la respuesta del proveedor del modelo orientado al cliente. Esto facilita cambiar de proveedor, corregir una regla de asignación y limitar la información expuesta a través de una página pública del pedido.
Diseña la experiencia de seguimiento para el cliente
Una página de seguimiento debe responder rápidamente a tres preguntas: cuál es el estado actual, qué ocurrió más recientemente y qué debe hacer el cliente a continuación. Muestra la referencia del pedido, el número de envío de forma respetuosa con la privacidad, el nombre del transportista, la hora del último evento y una explicación clara de las incidencias.
No muestres una línea de tiempo vacía como si fuera un fallo técnico. Antes del primer escaneo del transportista, explica que se ha recibido la información de envío y que es posible que el movimiento aún no sea visible. En el caso de una incidencia, proporciona una explicación en lenguaje sencillo solo cuando los datos de origen la respalden. Si el transportista notifica un problema de dirección, enlaza con el proceso de soporte o la acción de atención al cliente que tu empresa pueda ofrecer realmente.
En las tiendas creadas con Shopify u otra plataforma de comercio, comprueba cómo expone la plataforma los eventos de preparación, las cuentas de clientes, las páginas de estado de los pedidos y las plantillas de notificaciones. La documentación oficial para desarrolladores de Shopify incluye recursos para webhooks y datos de preparación. Las API de la plataforma y la documentación versionada pueden cambiar, por lo que debes confirmar la versión que utiliza tu aplicación antes de trabajar en producción.
Utiliza las notificaciones con cuidado
Los eventos de envío son activadores útiles, pero enviar un mensaje por cada escaneo del transportista puede provocar fatiga de notificaciones. Define reglas empresariales, como notificar la creación del envío, avances relevantes en tránsito, la salida a reparto, la entrega y determinadas incidencias. Suprime los duplicados y añade un intervalo mínimo para los mensajes repetidos sobre retrasos.
Separa las alertas operativas de las notificaciones para clientes. Un equipo de soporte puede necesitar saber que un envío no ha cambiado durante varios días, mientras que un cliente puede necesitar un mensaje solo cuando el transportista notifique una incidencia concreta. El umbral de tiempo debe reflejar el nivel de servicio, el destino, el transportista y el método de envío, en lugar de un número universal sin base operativa.
Prueba con situaciones reales de entrega
Una respuesta correcta para un número de seguimiento no basta para lanzar el sistema en producción. Crea una matriz de pruebas que incluya varios transportistas, países, tipos de envío y estados de eventos. Prueba al menos:
- Un envío recién creado sin escaneo del transportista
- Un envío normal en tránsito
- Un envío en reparto
- Un envío entregado
- Una incidencia o evento relacionado con la dirección
- Un envío devuelto
- Un número de seguimiento no válido
- Un evento de preparación duplicado
- Una respuesta retrasada del proveedor o un tiempo de espera agotado
- Un evento fuera de orden
Mide algo más que la disponibilidad de la API. Comprueba si se actualiza el pedido correcto, si el cliente ve un lenguaje comprensible, si se suprimen las notificaciones duplicadas y si el personal de soporte puede identificar el evento original del transportista. Realiza primero un lanzamiento limitado, conserva una alternativa operativa y supervisa las categorías de errores después de la publicación.
Seguridad, privacidad y mantenimiento
Almacena las credenciales en un gestor de secretos o una variable de entorno protegida, no en el código del tema, el código móvil, el control de versiones ni las solicitudes del navegador. Restringe el acceso a los datos de envíos por función, utiliza HTTPS y revisa durante cuánto tiempo se conservan las respuestas sin procesar y los campos relacionados con los clientes.
Revisa periódicamente la documentación del proveedor y la versión de la API de tu plataforma de comercio. La compatibilidad con transportistas, los nombres de eventos, los requisitos de autenticación y el comportamiento de los webhooks de la plataforma pueden cambiar. Mantén configurables las reglas de asignación de estados, documenta las suposiciones en las que se basan y permite volver a procesar o conciliar un envío sin enviar otro mensaje al cliente.
La API de 17TRACK es una opción relevante que conviene evaluar cuando tu tienda necesita una integración de seguimiento específica para varios transportistas. La elección adecuada sigue dependiendo de los transportistas que utilices, los países a los que prestes servicio, el comportamiento de actualización documentado para tu cuenta, el volumen de solicitudes previsto y los controles operativos que necesite tu equipo. Confirma estos puntos en la documentación oficial y en una prueba de concepto controlada antes de comprometerte con un diseño de producción.
Preguntas frecuentes
¿Debe crearse el seguimiento cuando se realiza un pedido?
Normalmente no. Crea o activa el registro del envío cuando tu flujo de preparación tenga un transportista y un número de seguimiento. Crearlo durante el pago puede generar registros de pedidos cancelados, no preparados o divididos posteriormente.
¿Puede una API de seguimiento garantizar información de entrega en tiempo real?
No. Ninguna API puede garantizar que cada escaneo del transportista sea visible inmediatamente. El proveedor depende de los datos del transportista, y los sistemas de los transportistas pueden notificar eventos con retrasos o interrupciones. Presenta las marcas de tiempo y el lenguaje de los estados con precisión, y evita prometer un tiempo exacto de actualización a menos que la documentación y el acuerdo de servicio correspondientes respalden esa promesa.
¿Debe el navegador llamar directamente a la API de seguimiento?
En la mayoría de las implementaciones, no. Utiliza una integración del lado del servidor para mantener protegidas las credenciales, normalizar las respuestas, controlar los reintentos y filtrar los datos orientados al cliente. Normalmente, la tienda debe leer una vista aprobada del envío desde tu aplicación.
¿Cómo debe gestionar una tienda varios paquetes en un mismo pedido?
Modela cada preparación o paquete como un envío independiente y conserva el ID del pedido principal. La página del pedido puede mostrar un resumen general y líneas de tiempo separadas para cada paquete. Así se evita ocultar un paquete retrasado detrás del estado de entregado de otro paquete.
¿Cuál es la primera métrica de producción que se debe supervisar?
Supervisa el flujo completo, desde la creación de la preparación hasta una actualización correcta visible para el cliente. El éxito de la API por sí solo no es suficiente. Realiza un seguimiento de los registros duplicados, los envíos obsoletos, los eventos sin asignar, los fallos de notificación y el porcentaje de envíos que requieren una corrección manual.
