Skip to main content
InicioBlogGuías15 preguntas que hacer a un proveedor de API de seguimiento antes de pasar a producción

15 preguntas que hacer a un proveedor de API de seguimiento antes de pasar a producción

17TRACK

Antes de poner una API de seguimiento en producción, pregunta cómo gestiona tus transportistas y tipos de envío reales, qué significan sus eventos, cómo llegan las actualizaciones y qué ocurre cuando fallan los datos o la integración. Las 15 preguntas siguientes ofrecen a los equipos de ingeniería y operaciones una forma práctica de comprobar esas respuestas antes de que los clientes, los agentes de soporte o los flujos de trabajo automatizados dependan de ellas.

15 Questions to Ask a Tracking API Provider before Going

Una demostración exitosa no es una prueba de producción. Utiliza una muestra representativa de envíos, incluidos paquetes retrasados, devueltos y difíciles de identificar. Para cada respuesta, solicita documentación, una carga útil de ejemplo o un resultado de prueba. Registra cualquier elemento no resuelto con un responsable y una fecha de decisión, en lugar de asumir que se solucionará después del lanzamiento.

Empieza por la compatibilidad con los envíos y el significado de los datos

1. ¿Cuáles de nuestros envíos reales pueden rastrear y qué significa la cobertura?

Proporciona al proveedor una muestra de tus transportistas, servicios, pares de origen y destino y formatos de números de seguimiento. Pídele que identifique qué envíos puede aceptar, qué transportistas puede identificar automáticamente y dónde debes proporcionar un código de transportista. Que un transportista aparezca en una lista no demuestra que todos los servicios, transferencias o tipos de envío produzcan los eventos que tu aplicación necesita.

Prueba ejemplos reales de rutas de gran volumen y casos operativos extremos. Incluye un envío que cambie de transportista durante el tránsito si eso ocurre en tu negocio. Registra si la API rechaza un envío, lo acepta sin encontrar eventos o devuelve eventos con detalles limitados. Esos resultados requieren un tratamiento diferente en un sistema de gestión de pedidos.

2. ¿Qué se necesita para registrar un envío y cómo evitan los registros duplicados?

Aclara los identificadores necesarios, las reglas de selección del transportista, el momento del registro y la respuesta ante un número de seguimiento no válido o aún no activo. Pregunta si un número de seguimiento por sí solo es suficiente para tu caso de uso o si se necesita información adicional. Confirma qué ocurre si el mismo envío se presenta dos veces, ya sea desde el mismo sistema o desde servicios independientes.

Crea un único flujo de registro con responsabilidades explícitas: qué sistema presenta los envíos, cuál almacena el identificador del proveedor y cuál reintenta un envío incierto. Si una solicitud agota el tiempo de espera después de que el proveedor la procese, un reintento ciego no debe crear silenciosamente un segundo registro ni notificaciones posteriores duplicadas.

3. ¿Qué significan sus estados y podemos consultar los eventos subyacentes del transportista?

Solicita un diccionario de estados y eventos sin procesar representativos. Términos como en tránsito, en reparto, excepción, entregado y devuelto son resúmenes útiles, pero tus reglas de negocio pueden necesitar más detalles. Determina si el proveedor proporciona las descripciones originales del transportista junto con los estados estandarizados y cómo gestiona un evento que no se puede asociar claramente.

Acuerda tu propio modelo de estados internos antes del lanzamiento. En particular, decide qué evento puede cerrar un envío, activar un mensaje de entrega o iniciar un flujo de trabajo de excepción. No trates una etiqueta de estado amplia como prueba de un evento físico específico a menos que los datos subyacentes respalden esa interpretación.

4. ¿Qué marcas de tiempo y ubicaciones se proporcionan y cómo debemos interpretarlas?

Para cada evento, distingue entre la hora en que el transportista afirma que ocurrió y la hora en que el proveedor lo recibió o publicó. Pregunta por las zonas horarias, los desplazamientos faltantes, la precisión de la ubicación y las actualizaciones que llegan después de eventos posteriores. Un evento recibido recientemente puede describir un escaneo antiguo; ordenar únicamente por la hora de recepción puede producir una cronología engañosa.

Prueba la carga útil con el esquema de tu base de datos y la visualización para el cliente. Decide cómo mostrar un evento cuando su zona horaria local sea incierta y evita presentar una hora o ubicación de entrega precisas si la fuente no las proporciona.

5. ¿Cómo se representan las excepciones, las devoluciones y la prueba de entrega?

Solicita ejemplos de intentos de entrega fallidos, retenciones aduaneras, problemas de dirección, movimientos de devolución al remitente y envíos entregados. Pregunta qué detalles están estandarizados, cuáles siguen siendo específicos de cada transportista y si la confirmación de entrega incluye pruebas de respaldo en los casos que te interesan. No asumas que un estado de entregado incluye el nombre del destinatario, una firma, una foto u otra prueba.

Asigna cada excepción a un responsable de acción. Algunos eventos justifican una revisión del soporte; otros no requieren ningún mensaje al cliente hasta que llegue más información. Si la prueba de entrega es necesaria para un flujo de trabajo de disputas, convierte su disponibilidad y formato en un criterio de aceptación independiente, en lugar de considerarlos una parte implícita de la cobertura de seguimiento.

Prueba cómo llegan las actualizaciones a tus sistemas

6. ¿Entregan actualizaciones mediante webhook, sondeo o ambos, y cuándo debemos utilizar cada uno?

Solicita el modelo de entrega documentado, ejemplos de cargas útiles, la configuración de suscripciones y las indicaciones para recuperar actualizaciones perdidas. Si ofrecen webhooks, determina si anuncian un envío modificado, proporcionan una instantánea completa o contienen un evento individual. Si el sondeo es obligatorio o se utiliza como alternativa, aclara el patrón de solicitud adecuado y cómo identificar los registros modificados.

Elige el modelo según el flujo de trabajo. Una cronología visible para el cliente puede tolerar un retraso de actualización diferente al de una cola de excepciones. Tu arquitectura no debe prometer alertas instantáneas simplemente porque una integración utiliza webhooks: el transportista debe hacer que el evento esté disponible primero y cada sistema posterior debe procesarlo.

7. ¿Qué ocurre cuando las notificaciones se duplican, se retrasan o llegan desordenadas?

Pregunta si el proveedor reintenta las entregas fallidas, durante cuánto tiempo y qué respuesta espera de tu endpoint. Solicita un identificador estable del evento o del envío, si está disponible. Después, prueba dos veces la misma notificación, envía un evento antiguo después de uno nuevo y devuelve temporalmente un error desde tu endpoint.

Tu receptor debe estar diseñado para confirmar únicamente lo que haya aceptado de forma segura, procesar los reintentos sin repetir los mensajes al cliente y reconstruir una cronología correcta cuando los eventos lleguen desordenados. Si un diseño propuesto depende de una única entrega exacta de cada notificación, cuestiona esa suposición antes del lanzamiento.

8. ¿Cómo mediremos la actualidad de los datos y qué la afecta?

Pregunta qué puede medir el proveedor en cada etapa: la hora del evento del transportista, la hora de recepción del proveedor y la hora de entrega a tu sistema. Separa esas mediciones de cualquier compromiso que asuma. Una brecha prolongada entre el movimiento físico y la actualización de tu aplicación puede originarse en el transportista, en el procesamiento del proveedor o en tu propia cola.

Durante un piloto, mide estas brechas para envíos representativos e investiga los valores atípicos. Establece umbrales de alerta según lo que realmente requiera tu flujo de trabajo. Si un escaneo retrasado pudiera provocar un mensaje perjudicial al cliente o una escalada omitida, define una alternativa, como una etiqueta de datos obsoletos o una revisión manual.

9. ¿Cómo se protegen las credenciales de la API y las solicitudes de webhook?

Solicita la documentación de autenticación y gestión de credenciales. Confirma cómo se emiten, delimitan, rotan y revocan las credenciales; si las credenciales de prueba y producción son independientes; y cómo puede un receptor de webhook verificar que una solicitud es auténtica. Pregunta también qué protecciones existen contra solicitudes de webhook reproducidas.

Pide a tu equipo de seguridad que revise la implementación propuesta, no solo la lista de funciones del proveedor. Mantén los secretos fuera del código y los registros del lado del cliente, restringe el acceso a las credenciales de producción y ensaya la rotación de credenciales. Si tu aplicación no puede verificar una notificación entrante mediante el mecanismo documentado, eso bloquea el lanzamiento de un flujo de trabajo basado en webhooks.

10. ¿Qué datos de envíos y clientes conservan y adónde van?

Enumera todos los campos que enviaría tu integración, incluidos números de seguimiento, referencias de pedidos, direcciones, datos de contacto y cualquier metadato personalizado. Pregunta qué campos son obligatorios, durante cuánto tiempo se conservan los datos y registros, cómo funcionan las solicitudes de eliminación y qué regiones o subencargados son relevantes para los requisitos de tu organización. Obtén documentación contractual o de seguridad cuando tu revisión lo requiera.

Minimiza los datos que transmites. Una integración de seguimiento no debe recibir información del cliente simplemente porque resulte práctico enviar un objeto de pedido completo. Tus equipos de privacidad, legal y seguridad deben decidir si el tratamiento documentado por el proveedor se ajusta a los mercados en los que operas.

Planifica los fallos y los cambios operativos

11. ¿Cuáles son los límites de velocidad y cómo deben responder los clientes a los errores?

Pregunta por los límites por endpoint, credencial y entorno, junto con las reglas de concurrencia y el comportamiento de reintento recomendado. Distingue una solicitud no válida de un problema temporal del servicio y de una solicitud limitada por velocidad. En las API HTTP, el significado de los códigos de estado es importante: RFC 6585 define 429 para demasiadas solicitudes, mientras que RFC 9110 describe la semántica HTTP, incluidos los errores del servidor.

Calcula el tráfico previsto para días normales y picos, y después prueba un cliente que reduzca progresivamente la frecuencia, ponga el trabajo en cola y alerte sobre fallos persistentes. Confirma si una escritura incierta puede reintentarse de forma segura. Una política de reintentos que multiplique el tráfico durante una interrupción puede dificultar la recuperación.

12. ¿Cómo se comunican los cambios de esquema, estados e integraciones con transportistas?

Pregunta por el control de versiones de la API, los avisos de desuso, los registros de cambios y si se pueden añadir campos de eventos sin modificar la versión. Las descripciones proporcionadas por los transportistas y el comportamiento del seguimiento también pueden cambiar. Determina cómo comunica el proveedor un cambio que afecta a un transportista o ruta concreta, en lugar de a toda la API.

Escribe analizadores tolerantes para campos opcionales y valores de estado desconocidos, pero no conviertas silenciosamente un valor desconocido en entregado o fallido. Almacena suficientes detalles de origen para diagnosticar un cambio de mapeo. Asigna a alguien la revisión de los avisos del proveedor y la actualización de las pruebas de integración antes de que un cambio llegue a los clientes.

13. ¿Qué podemos probar antes de producción y cuánto se parece el entorno de pruebas al comportamiento real?

Solicita acceso a la documentación, un entorno de prueba si se ofrece, respuestas de ejemplo y una forma de ejercitar las rutas de error. Pregunta qué escenarios se simulan y cuáles requieren envíos reales. Un entorno aislado puede demostrar que tu código gestiona una carga útil, pero decir poco sobre la integridad de los eventos del transportista, los tiempos de actualización o la adecuación regional.

Realiza dos tipos de pruebas: pruebas de integración deterministas para el análisis, los reintentos y la seguridad; y un piloto limitado con envíos reales para el comportamiento operativo. Incluye envíos duplicados, un tiempo de espera del proveedor, un escaneo retrasado, una devolución y un estado desconocido. Exige que tanto ingeniería como el equipo que actuará ante las excepciones aprueben los resultados.

14. ¿Qué compromisos de soporte e incidentes se aplican cuando el seguimiento deja de actualizarse?

Pregunta qué canales de soporte están disponibles para tu cuenta, cómo se comunican los incidentes y qué compromisos contractuales de servicio, si los hay, se aplican a la API o a la entrega de notificaciones. Aclara si un compromiso de disponibilidad cubre el endpoint de la API, la entrega de actualizaciones de seguimiento o ambos. No representan el mismo resultado operativo.

Establece tu propio manual operativo: quién detecta un fallo, quién contacta con el proveedor, cuándo se utiliza el sondeo u otra alternativa y qué ven los clientes mientras las actualizaciones están retrasadas. Solicita el proceso para resolver tanto un problema de datos específico de un envío como una interrupción de toda la plataforma. Prueba tu ruta de escalada antes de necesitarla.

15. ¿Cómo se calculan el uso y los costes y qué ocurre si nos marchamos?

Pregunta qué acciones cuentan para la facturación o los límites de uso: envíos, paquetes rastreados, solicitudes, notificaciones u otra unidad. Confirma cómo se tratan los registros duplicados, los reintentos, los envíos inactivos, los excesos y el tráfico de prueba según el acuerdo propuesto. Obtén por escrito las condiciones aplicables en lugar de estimar los costes a partir de una demostración de la API.

Planifica también la terminación. Determina cómo puedes exportar los historiales de envíos, durante cuánto tiempo seguirá disponible el acceso y qué ocurrirá con los registros de seguimiento activos. Un plan de salida viable no predice que cambiarás de proveedor; es una forma de evitar perder visibilidad sobre los envíos que ya están en movimiento.

Convierte las respuestas en una decisión de producción

Una revisión útil antes de la puesta en marcha tiene tres resultados:

  • Resultado de compatibilidad con los envíos: una muestra probada que muestre qué registros de seguimiento fueron aceptados y si sus eventos respaldan los flujos de trabajo previstos para clientes y operaciones.
  • Resultado de la integración: gestión demostrada de autenticación, duplicados, reintentos, eventos retrasados, variaciones del esquema y recuperación de actualizaciones perdidas.
  • Acuerdo operativo: límites documentados, condiciones de tratamiento de datos, contactos de soporte, supuestos de costes y responsables de los riesgos no resueltos.

17TRACK es un proveedor que puedes evaluar si una API de seguimiento multitransportista se ajusta a tu caso de uso; su página de Tracking API y su documentación de la API son puntos de partida para comprobar la integración según estas preguntas. El mismo estándar debe aplicarse a cualquier proveedor: la documentación establece cómo se pretende que funcione una interfaz, mientras que tus propias pruebas con envíos representativos establecen si funciona para tu flujo de producción. No publiques una notificación al cliente ni automatices excepciones hasta haber validado los eventos que las activan.

Preguntas frecuentes

¿Es suficiente una prueba en un entorno aislado para aprobar una API de seguimiento para producción?

No. Un entorno aislado puede validar los formatos de solicitud y parte de la gestión de fallos, pero se necesitan envíos reales para evaluar los eventos específicos del transportista, los tiempos y la utilidad de los datos de excepción en tus rutas reales. Utiliza ambos, con criterios de aceptación independientes.

¿Debemos utilizar webhooks o hacer sondeos para las actualizaciones de seguimiento?

Decídelo según las opciones de entrega documentadas por el proveedor y la tolerancia al retraso de tu flujo de trabajo. Los webhooks pueden reducir la necesidad de comprobaciones repetidas cuando están disponibles, pero tu receptor aún necesita gestionar reintentos y duplicados. El sondeo puede ser adecuado como método principal o como vía de recuperación, sujeto a los límites documentados.

¿Cuál es el error más común al asignar estados de seguimiento?

Utilizar un estado amplio como activador de una afirmación empresarial más específica. Por ejemplo, una etiqueta de entregado por sí sola puede no proporcionar la prueba necesaria para resolver una disputa. Define los activadores utilizando los detalles del evento subyacente que el proveedor realmente proporciona.

¿Quién debe aprobar la integración antes del lanzamiento?

Ingeniería debe aprobar la fiabilidad y la seguridad; operaciones o soporte deben aprobar la utilidad de los eventos y los flujos de trabajo de excepciones; y los responsables correspondientes de privacidad, legal y compras deben revisar el tratamiento de datos y las condiciones comerciales. Asigna un responsable identificado a cualquier brecha que permanezca abierta.

Fuentes