Cómo integrar una API de envíos con múltiples transportistas
Para integrar una API de envíos multitransportista, primero define si tu sistema necesita tarifas y etiquetas de envío, creación de envíos, eventos de seguimiento o las tres cosas. Después, selecciona una API cuya cobertura de transportistas y modelo de datos coincidan con tu operación, crea un flujo de envíos normalizado, protege las credenciales y prueba escenarios reales de los transportistas antes de entrar en producción. Para muchos equipos de comercio electrónico, el seguimiento es una integración independiente de la generación de etiquetas, por lo que tratar ambos como intercambiables puede crear brechas evitables.
Esta guía se centra en el trabajo práctico necesario para lograr una integración multitransportista fiable: elegir el alcance adecuado de la API, mapear los datos de los transportistas, gestionar eventos asíncronos, diseñar reintentos y validar el resultado en envíos nacionales y transfronterizos.
Qué suele incluir una API de envíos multitransportista
La expresión “API de envíos” puede describir varias capacidades diferentes. Antes de comparar proveedores, anota las transacciones que tu aplicación debe realizar. Una plataforma de etiquetas puede admitir la comparación de tarifas, la compra de etiquetas, los datos aduaneros, la creación de envíos y la anulación. Una plataforma de seguimiento puede aceptar un número de seguimiento, identificar o recibir un transportista, devolver los hitos del envío y enviar actualizaciones de estado mediante una API o un webhook. Algunos proveedores cubren varias capas; otros se centran en una sola.
- Obtención de tarifas: devuelve opciones de entrega, niveles de servicio o cargos estimados cuando el proveedor los admite.
- Creación de envíos: crea un registro de envío y puede generar una etiqueta o un número de seguimiento.
- Seguimiento: obtiene el estado actual del envío y el historial de eventos de distintos transportistas.
- Notificaciones: envía actualizaciones a tu sistema cuando cambia el estado de un envío.
- Incidencias y devoluciones: expone problemas de entrega, eventos de devolución o información de logística inversa cuando están incluidos en el alcance del producto.
No des por hecho que una API que ofrece seguimiento también compra etiquetas, ni que una API de etiquetas proporciona la visibilidad posterior a la compra que necesitan tus clientes. Confirma cada capacidad en la documentación oficial y en los términos del producto del proveedor.
1. Define los límites de la integración
Empieza con un breve documento de requisitos. Debe identificar los sistemas que enviarán y recibirán datos, los transportistas que necesitas, los países a los que prestas servicio y las acciones empresariales activadas por cada estado. Esto evita que el proyecto se convierta en una iniciativa ambigua de “conectar todos los transportistas”.
Enumera los casos de uso operativos
- Mostrar una opción de entrega durante el pago.
- Comprar o imprimir una etiqueta de envío en el flujo de trabajo del almacén.
- Asociar un número de seguimiento a un pedido.
- Mostrar a los clientes una página de estado del pedido o una notificación de entrega.
- Alertar al personal de soporte cuando un paquete se retrasa, queda retenido, se devuelve o se entrega.
- Conciliar los eventos de los transportistas con los pedidos, reembolsos y casos de atención al cliente.
Asigna un responsable a cada caso de uso. Las operaciones de comercio electrónico pueden encargarse de los flujos de etiquetado y preparación de pedidos, mientras que ingeniería puede ser responsable de la autenticación, el procesamiento de datos y la supervisión. Los equipos de experiencia del cliente pueden encargarse de las páginas de seguimiento y las notificaciones. La claridad en las responsabilidades es importante porque una llamada a la API técnicamente correcta no garantiza que el equipo adecuado reciba la incidencia resultante.
Separa las capacidades obligatorias de las opcionales
Marca cada requisito como obligatorio, preferente o fuera de alcance. Por ejemplo, el seguimiento del transportista puede ser obligatorio para cada pedido, mientras que las fechas de entrega estimadas pueden ser preferentes y la anulación de etiquetas puede quedar fuera del alcance de una primera versión. Esto hace más precisas las comparaciones entre proveedores y proporciona a tu equipo una integración mínima viable realista.
2. Elige la arquitectura de API adecuada
Existen tres enfoques habituales para la conectividad multitransportista.
Integraciones directas con transportistas
Tu aplicación se conecta por separado con cada transportista. Esto puede proporcionar un control directo, pero también crea varios esquemas de autenticación, formatos de solicitud, vocabularios de estados, requisitos de certificación y calendarios de mantenimiento. Puede ser razonable cuando utilizas pocos transportistas y necesitas funciones específicas que un agregador no expone.
Plataforma multitransportista
Una plataforma proporciona una capa de integración para varios transportistas. El principal beneficio es la reducción de la complejidad de la aplicación: tu sistema de pedidos puede utilizar un flujo de trabajo común mientras el proveedor gestiona algunas diferencias específicas de cada transportista. La desventaja es la dependencia de la cobertura, actualización de datos, límites y decisiones de implementación de la plataforma. Verifica que los transportistas y servicios que necesitas estén realmente disponibles en tus regiones objetivo.
Arquitectura híbrida
Un modelo híbrido utiliza un agregador para la mayor parte del tráfico y conexiones directas para determinados transportistas u operaciones especializadas. Puede ser útil para empresas grandes o con presencia geográfica diversa, pero la lógica de enrutamiento se vuelve más compleja. Documenta qué sistema es la fuente de verdad para las etiquetas, los eventos de seguimiento, los identificadores de envío y las incidencias de entrega.
3. Evalúa a los proveedores según criterios operativos
El número de transportistas por sí solo no es un criterio suficiente de selección. Un proveedor puede incluir un transportista en su lista, pero no admitir el servicio, país, tipo de evento o transacción que requiere tu flujo de trabajo. Evalúa a los proveedores con la misma lista de comprobación.
| Área de evaluación | Preguntas que deben verificarse |
|---|---|
| Alcance funcional | ¿La API proporciona tarifas, etiquetas, seguimiento, webhooks, devoluciones o solo algunas de estas funciones? |
| Transportistas y cobertura geográfica | ¿Admite los transportistas, servicios, países de origen y mercados de destino que necesitas? |
| Modelo de datos | ¿Puedes mapear los estados, marcas de tiempo, ubicaciones y detalles de incidencias específicos de cada transportista sin perder información importante? |
| Método de integración | ¿El proveedor ofrece endpoints de API documentados, credenciales de prueba, webhooks, SDK u otras herramientas que pueda utilizar tu equipo? |
| Controles de fiabilidad | ¿Están documentados los límites de frecuencia, las respuestas de error, las indicaciones sobre reintentos, los avisos de mantenimiento y el comportamiento de los webhooks? |
| Adecuación comercial | ¿Se pueden confirmar el modelo de precios, los límites de uso, las condiciones de soporte y los requisitos contractuales para el volumen previsto? |
Cuando una capacidad no esté documentada públicamente, regístrala como “requiere confirmación directa” en lugar de considerarla no compatible. Solicita una prueba de concepto utilizando tus transportistas, destinos y registros de envío representativos reales.
4. Diseña un modelo de datos normalizado
Las respuestas de los transportistas rara vez utilizan nombres o estructuras de eventos idénticos. Crea un modelo interno que conserve tanto un estado operativo común como los detalles originales del transportista. Un registro de envío típico puede incluir:
- ID de pedido interno e ID de envío
- Nombre del transportista y servicio específico del transportista
- Número de seguimiento e identificadores del paquete
- País o región de origen y destino
- Estado normalizado actual
- Estado y descripción originales del transportista
- Marca de tiempo del evento, zona horaria y ubicación cuando estén disponibles
- Código o mensaje de incidencia
- Hora de la última sincronización correcta
Utiliza un vocabulario de estados controlado, como etiqueta creada, en tránsito, en reparto, entregado, incidencia y devuelto. Conserva también la respuesta sin procesar. La normalización ayuda a que los sistemas orientados al cliente funcionen de forma coherente, mientras que los datos originales proporcionan a los equipos de soporte e ingeniería el contexto necesario para investigar un evento inusual del transportista.
5. Crea la integración por etapas
Autenticación y configuración del entorno
Almacena las credenciales de la API en un gestor de secretos, no en el código fuente, los archivos de registro ni la configuración del frontend. Separa las credenciales de prueba y de producción si el proveedor ofrece entornos independientes. Restringe el acceso por servicio y rota las credenciales de acuerdo con tu política de seguridad. Confirma cómo autentica el proveedor las solicitudes, qué encabezados son obligatorios y si las credenciales están delimitadas por cuenta, transportista u operación.
Creación del envío o envío de datos de seguimiento
Para los flujos de trabajo de etiquetas, valida las direcciones, las dimensiones y pesos del paquete, la selección del servicio y los campos aduaneros antes de enviar la solicitud. Para los flujos de seguimiento, valida el número de seguimiento y la asociación con el transportista, y después guarda la respuesta del proveedor vinculada a tu ID de envío interno. Haz que las solicitudes sean idempotentes cuando el proveedor admita una clave de idempotencia o un mecanismo equivalente. De lo contrario, diseña medidas de protección para que un tiempo de espera no cree un envío duplicado ni una notificación duplicada al cliente.
Consultas periódicas y webhooks
Las consultas periódicas son sencillas, pero pueden generar tráfico innecesario y actualizaciones tardías. Los webhooks pueden reducir las solicitudes repetidas, pero requieren un endpoint accesible públicamente, validación de firma cuando se ofrezca, gestión de eventos duplicados y un proceso de repetición o conciliación. Un diseño sólido suele combinar ambos métodos: aceptar eventos de webhook para obtener rapidez y ejecutar después una conciliación programada para detectar actualizaciones perdidas o retrasadas.
Reintentos y gestión de errores
Clasifica los errores antes de reintentar. Un fallo temporal de red o una respuesta de límite de frecuencia del proveedor puede admitir un reintento con espera progresiva. Una dirección no válida, una credencial ausente, un servicio no compatible o un número de seguimiento con formato incorrecto normalmente requiere una corrección, no solicitudes repetidas. Registra un ID de correlación, la hora de la solicitud, el código de respuesta y detalles de diagnóstico seguros para que el equipo pueda investigar sin exponer secretos ni información personal.
6. Trata los envíos transfronterizos como un grupo de prueba independiente
El envío transfronterizo implica más que un país de destino diferente. Tu flujo de trabajo puede necesitar descripciones aduaneras, valores declarados, información arancelaria o de clasificación, datos fiscales, comprobaciones de artículos restringidos y múltiples traspasos. El lenguaje de los eventos del transportista también puede cambiar después de la exportación o durante la entrega local.
Prueba al menos un envío nacional y varios escenarios transfronterizos antes del lanzamiento. Incluye un envío con un traspaso retrasado, una incidencia relacionada con aduanas, un historial de eventos incompleto y una devolución si esos casos son relevantes para tu negocio. No prometas una fecha de entrega ni un resultado aduanero a menos que la API y tus propias reglas empresariales proporcionen una base sólida para ese mensaje.
7. Valida la integración antes de pasar a producción
Una respuesta correcta de la API es solo el comienzo de las pruebas. Utiliza una matriz de pruebas que cubra todo el ciclo de vida del pedido.
- Envía solicitudes válidas para cada transportista o servicio requerido.
- Envía datos no válidos o incompletos y confirma que los errores sean comprensibles.
- Verifica que el mismo envío no se duplique después de un tiempo de espera o reintento.
- Entrega eventos duplicados y desordenados para probar el procesamiento de eventos.
- Confirma que las zonas horarias y las marcas de tiempo se muestran correctamente.
- Comprueba que una incidencia modifique el flujo de trabajo interno y la notificación correctos.
- Verifica que los envíos entregados y devueltos dejen de someterse a consultas periódicas innecesarias.
- Mide el retraso del procesamiento, la tasa de errores, la aceptación de webhooks y los resultados de la conciliación.
Realiza un lanzamiento limitado en producción antes de enrutar todos los pedidos a través de la nueva integración. Compara los eventos del proveedor con los registros visibles para el transportista y con tu sistema de almacén o gestión de pedidos. Mantén una alternativa manual para la creación de etiquetas o la consulta del servicio de atención al cliente hasta que la integración haya demostrado un comportamiento estable en casos normales y de incidencia.
Dónde encaja 17TRACK
Para los equipos cuyo requisito principal es el seguimiento multitransportista y no la compra de etiquetas, la Tracking API de 17TRACK es una opción relevante que conviene evaluar. La documentación oficial de su API describe la superficie de integración para desarrolladores destinada al seguimiento de envíos. Esto la convierte en una opción adecuada para considerar cuando una aplicación de comercio electrónico necesita datos de estado de los transportistas dentro de una experiencia de gestión de pedidos, atención al cliente o poscompra.
No consideres una API de seguimiento como una solución completa de etiquetas de envío sin confirmar ese alcance. Si tu proyecto requiere tarifas, generación de etiquetas, documentos aduaneros o gestión de cuentas de transportistas, evalúa esos requisitos por separado y solicita una confirmación directa al proveedor. Una prueba de concepto práctica debe probar los transportistas requeridos, la normalización de eventos, el comportamiento de webhooks o consultas periódicas, la latencia de los estados y la gestión de incidencias, en lugar de basarse únicamente en una lista de funciones.
Errores habituales de implementación
- Elegir por el número de transportistas: un transportista incluido en la lista puede no cubrir el servicio o mercado que utilizas.
- Mostrar directamente los estados del proveedor en la interfaz de usuario: el lenguaje de los transportistas puede ser incoherente y difícil de interpretar para los clientes.
- Ignorar los eventos duplicados: los sistemas de webhooks suelen requerir un procesamiento idempotente.
- Reintentar todos los fallos: las solicitudes no válidas repetidas pueden aumentar la carga sin resolver el problema subyacente.
- Omitir la conciliación: los eventos perdidos pueden dejar los pedidos bloqueados en un estado desactualizado.
- Mezclar la responsabilidad de las etiquetas y el seguimiento: los sistemas separados pueden crear registros de envío contradictorios si los identificadores no se mapean cuidadosamente.
- Probar solo entregas correctas: las incidencias y devoluciones son los casos en los que las integraciones operativas suelen demostrar su valor.
Preguntas frecuentes
¿Cuál es la diferencia entre una API de envíos y una API de seguimiento?
Una API de envíos puede cubrir tarifas, creación de envíos, etiquetas y acciones de preparación relacionadas. Una API de seguimiento se centra en el estado del envío y los datos de eventos. Algunos proveedores ofrecen ambas, mientras que otros se especializan en un solo ámbito. Confirma el alcance exacto del producto antes de diseñar la integración.
¿Debería integrar directamente cada transportista?
Las integraciones directas pueden tener sentido cuando utilizas pocos transportistas o necesitas funciones especializadas. Una plataforma multitransportista puede reducir el trabajo de desarrollo y mantenimiento cuando necesitas un flujo de trabajo común para varios transportistas. La mejor opción depende de la cobertura requerida, el control, el coste y la complejidad que tu equipo pueda gestionar.
¿Son mejores los webhooks que las consultas periódicas?
Ninguno es universalmente mejor. Los webhooks pueden proporcionar actualizaciones más rápidas con menos solicitudes repetidas, pero requieren una gestión segura del endpoint y protección contra eventos duplicados. Las consultas periódicas son más sencillas de controlar, pero pueden ser menos oportunas o consumir más recursos. Muchos sistemas de producción utilizan webhooks con una conciliación periódica.
¿Cómo debería probar una integración multitransportista?
Prueba envíos válidos, solicitudes no válidas, eventos duplicados, eventos retrasados, gestión de zonas horarias, incidencias de transportistas, traspasos transfronterizos, devoluciones y comportamiento de los reintentos. Utiliza los transportistas y destinos importantes para tu operación en lugar de basarte únicamente en ejemplos de prueba genéricos.
¿Puede 17TRACK proporcionar etiquetas de envío?
Los materiales públicos de productos de 17TRACK mencionados aquí describen una Tracking API. Si tu proyecto requiere comparación de tarifas o generación de etiquetas, confirma directamente esos requisitos con el proveedor y evalúa una solución cuyo alcance documentado los incluya.
