Cómo utilizar la API de seguimiento de UPS: guía de configuración paso a paso

Para utilizar la API de seguimiento de UPS, crea una cuenta de UPS Developer, registra una aplicación, obtén credenciales de OAuth 2.0, solicita un token de acceso y envía solicitudes de seguimiento autenticadas con un número de seguimiento válido de UPS. Las etiquetas exactas del portal, los pasos de aprobación y los requisitos de la API pueden cambiar, por lo que debes confirmar las instrucciones actuales en el Portal oficial para desarrolladores de UPS antes de poner en funcionamiento una integración de producción.

Esta guía está dirigida a desarrolladores y equipos de operaciones de comercio electrónico que necesitan consultar el estado de los envíos dentro de una tienda en línea, un sistema de gestión de pedidos, un flujo de trabajo de almacén, una herramienta de atención al cliente o un panel interno. Se centra en la secuencia de integración, las decisiones que afectan a la fiabilidad y las comprobaciones que evitan errores habituales de seguimiento.

Qué hace la API de seguimiento de UPS

Una integración mediante API permite que el software solicite información sobre los envíos a UPS, en lugar de exigir que un empleado o cliente abra manualmente la página de seguimiento del transportista. Tu aplicación puede utilizar la respuesta para mostrar el último estado conocido, identificar eventos de entrega, ayudar en investigaciones del servicio de atención al cliente o activar un flujo de trabajo interno.

La API no es lo mismo que una página de seguimiento. Una página de seguimiento está diseñada para que la lea una persona. Una respuesta de API contiene datos estructurados que el software debe analizar, almacenar y presentar. Tu sistema sigue siendo responsable de la autenticación, el manejo de errores, la consulta periódica o recopilación de eventos, la conservación de datos, el diseño de la interfaz de usuario y cualquier regla comercial basada en los eventos de entrega.

Antes de comenzar

Prepara los siguientes elementos antes de abrir el portal para desarrolladores:

• Una cuenta de UPS Developer o el tipo de cuenta requerido por el proceso actual de incorporación de UPS.
• Una aplicación registrada y las credenciales emitidas para ella.
• Un número de seguimiento de prueba u otro método de prueba aprobado. No comiences con datos reales de clientes si la documentación de UPS proporciona un entorno o procedimiento de prueba independiente.
• Una decisión clara sobre qué sistema es propietario de los registros de envíos, los eventos de seguimiento y los mensajes de estado dirigidos a los clientes.
• Un lugar seguro para almacenar las credenciales del cliente y los tokens de acceso. Nunca coloques secretos en código del navegador, repositorios públicos, capturas de pantalla o aplicaciones móviles que los usuarios puedan inspeccionar.

También debes decidir si tu aplicación necesita únicamente seguimiento o una integración más amplia con UPS. El seguimiento, las tarifas, los envíos, la validación de direcciones y los servicios de documentos pueden tener productos, permisos, formatos de solicitud y requisitos operativos diferentes.

Paso 1: Abre el Portal para desarrolladores de UPS

Comienza en el Portal oficial para desarrolladores de UPS. Revisa el catálogo actual de API, las instrucciones de autenticación, los requisitos de incorporación, los términos y la información sobre los entornos. Busca específicamente la documentación de la API de seguimiento, en lugar de asumir que las instrucciones de otro servicio de UPS también se aplican al seguimiento.

El portal es la fuente adecuada para consultar los campos actuales de las solicitudes, los ámbitos de autorización, las definiciones de las respuestas, los límites de frecuencia, los códigos de error y los detalles de los entornos. Estos detalles pueden cambiar, y un ejemplo de código de terceros puede utilizar una interfaz antigua de UPS o un método de autenticación obsoleto.

Paso 2: Registra una aplicación

Crea una aplicación en el portal para desarrolladores y selecciona las API de UPS que realmente necesita la aplicación. Para un proyecto que solo requiera seguimiento, solicita únicamente la capacidad de seguimiento, a menos que tu flujo de trabajo necesite servicios adicionales. Limitar los permisos reduce la complejidad de la configuración y facilita la resolución de problemas posteriormente.

Guarda el identificador y el secreto de la aplicación en un gestor de secretos del servidor o en un sistema protegido de variables de entorno. Trata el secreto como una contraseña. Si queda expuesto, rótalo mediante el proceso proporcionado por UPS y revisa los registros para detectar usos no autorizados.

Si el portal solicita información de cuenta, facturación, empresa o aplicación, proporciona datos precisos. Evita inventar un caso de uso de producción o utilizar la información de la cuenta de otra persona simplemente para completar una prueba. El acceso a un servicio puede depender de la configuración de la cuenta y del proceso de aprobación vigente de UPS.

Paso 3: Implementa la autenticación OAuth 2.0

La documentación actual para desarrolladores de UPS utiliza autenticación basada en OAuth para sus API. Normalmente, tu servidor intercambia las credenciales de la aplicación mediante el flujo de tokens documentado y recibe un token de acceso. Después incluye ese token en el encabezado de autorización de una solicitud a la API.

Mantén la autenticación separada de la lógica de seguimiento. Un diseño práctico cuenta con un componente que obtiene y almacena en caché un token válido y otro que llama al endpoint de seguimiento. El componente de tokens debe:

• Enviar las credenciales únicamente al endpoint de autorización de UPS documentado.
• Utilizar el tipo de contenido y los parámetros de concesión especificados en la documentación actual de UPS.
• Almacenar temporalmente el token y reutilizarlo hasta que caduque, en lugar de solicitar un token nuevo para cada número de seguimiento.
• Actualizar u obtener de nuevo el token cuando se produzca la condición de caducidad documentada.
• Ocultar las credenciales y los tokens en los registros de la aplicación, los informes de errores y las solicitudes de asistencia.

No copies un token de una sesión del navegador para utilizarlo en una integración permanente. Generalmente, un servicio backend es un lugar más seguro para gestionar las credenciales, ya que mantiene los secretos alejados del código cliente público.

Paso 4: Crea la solicitud de seguimiento

Utiliza el formato de solicitud mostrado en la referencia oficial de la API de seguimiento. Una solicitud típica incluye un número de seguimiento en la ruta o en los parámetros de la solicitud, un token de acceso en el encabezado de autorización y los encabezados requeridos por la API de UPS. No supongas que el número de seguimiento es el único valor obligatorio: la referencia actual puede especificar encabezados de versión, transacción, tipo de contenido o correlación.

Un patrón de solicitud simplificado sería el siguiente:

GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/json

Este es un ejemplo estructural, no un endpoint listo para copiar y pegar. Utiliza el endpoint, la versión, los encabezados y los nombres de parámetros publicados en la documentación de UPS para tu aplicación. Mantén el número de seguimiento normalizado de acuerdo con las reglas de tus propios datos de pedidos, pero no elimines caracteres a menos que la documentación del transportista confirme que hacerlo es seguro.

Paso 5: Analiza los eventos en tu modelo de datos

Las respuestas de los transportistas suelen contener más información que una única etiqueta de estado. Antes de programar la página orientada al cliente, asigna la respuesta a un modelo interno que incluya, por ejemplo, el identificador del envío, el transportista, el último estado, el código del evento, la descripción del evento, la fecha y hora del evento, la ubicación, la información de entrega estimada y la fecha y hora de entrega cuando estén disponibles.

Conserva la respuesta original del transportista cuando tus políticas de conservación y privacidad lo permitan. Una respuesta sin procesar puede ayudar a diagnosticar un error de asignación o explicar por qué tu estado normalizado difiere de la redacción del transportista. Al mismo tiempo, evita mostrar códigos técnicos de eventos a los clientes sin una explicación comprensible.

No trates todos los estados como un resultado final de entrega. Por ejemplo, un evento en tránsito, una excepción, un intento de entrega y un evento de entrega completada no deben reducirse al mismo mensaje para el cliente. Crea asignaciones explícitas y define qué ocurre cuando UPS añade un valor de evento que tu código no reconoce.

Paso 6: Añade reintentos, validación y supervisión

Una integración de producción necesita más que una solicitud exitosa en una consola de desarrollo. Añade validaciones y protecciones operativas:

• Validación de entradas: rechaza los números de seguimiento vacíos, con formato incorrecto o evidentemente incompletos antes de enviar las solicitudes.
• Tiempos de espera: evita que una respuesta lenta del transportista bloquee todo un flujo de pago, atención al cliente o almacén.
• Reglas de reintento: reintenta cuidadosamente los fallos temporales de red o del servicio, utilizando intervalos progresivos. No reintentes repetidamente los errores de autenticación ni los números de seguimiento no válidos.
• Control de la frecuencia: respeta los límites y las reglas de uso de la documentación de UPS. Almacena en caché los resultados recientes cuando tu proceso empresarial lo permita.
• Estados desconocidos: conserva para revisión un evento no reconocido en lugar de etiquetarlo erróneamente como entregado o perdido.
• Observabilidad: registra el tiempo de las solicitudes, la categoría de la respuesta y la información de correlación sin registrar secretos ni datos personales innecesarios.

Un sistema de seguimiento también debe definir con qué frecuencia actualiza un envío. Consultar con demasiada frecuencia puede generar una carga evitable y quizá no produzca información nueva. Consultar con poca frecuencia puede hacer que una página orientada al cliente parezca desactualizada. Elige un intervalo según el volumen de envíos, la urgencia operativa, las reglas del transportista y la actualización que realmente necesitan tus usuarios.

Paso 7: Prueba con escenarios realistas

Prueba más que un envío entregado correctamente. Incluye un número de seguimiento desconocido, un envío en tránsito, una excepción, un envío con varios eventos, un token caducado, un tiempo de espera agotado, un fallo de autorización y una respuesta que contenga campos que tu analizador no espere. Si UPS proporciona un entorno o credenciales de prueba independientes, sigue primero ese procedimiento.

Comprueba todo el recorrido desde la solicitud hasta la interfaz de usuario. Confirma que el pedido correcto recibe el envío correcto, que las fechas y horas se muestran con la zona horaria prevista, que los eventos duplicados no generan mensajes duplicados para el cliente y que una interrupción del transportista no sobrescribe un estado válido anterior con un texto engañoso.

Cuándo es más adecuada una API de seguimiento multitransportista

Una integración directa con UPS puede ser adecuada cuando tu operación realiza envíos principalmente con UPS y necesita un control detallado del flujo de trabajo del transportista. Resulta menos conveniente cuando los pedidos pueden pasar por varios transportistas, marketplaces, operadores postales o empresas de entrega regionales. En esa situación, las credenciales, los formatos de respuesta, los vocabularios de estados y las reglas de reintento independientes pueden aumentar el trabajo de mantenimiento.

Un servicio multitransportista como 17TRACK Tracking API puede ofrecer un modelo de integración alternativo para aplicaciones que necesitan seguimiento con varios transportistas. Debes revisar directamente su documentación para desarrolladores con el fin de consultar los transportistas compatibles, los formatos de solicitud, la autenticación, los términos de uso y las capacidades disponibles. Esto no significa que sea automáticamente mejor que una conexión directa con UPS: la opción adecuada depende de la combinación de transportistas, los requisitos de datos, el control sobre la integración y las limitaciones comerciales o de cumplimiento.

Para una consulta orientada al consumidor en lugar de una integración para desarrolladores, la página de seguimiento de 17TRACK puede ser más adecuada que crear una conexión API. Para una tienda en línea que necesite actualizaciones posteriores a la compra con su propia marca, revisa por separado la integración correspondiente de la plataforma en lugar de añadir trabajo de API que la tienda no necesita.

Errores habituales de implementación

• Usar ejemplos antiguos: un ejemplo de código puede hacer referencia a una versión retirada, un método de autenticación antiguo o un servicio de UPS diferente.
• Colocar secretos en el código frontend: todo lo que se envía a un navegador debe considerarse susceptible de inspección.
• Suponer que un resultado vacío significa que no existe el envío: verifica el número de seguimiento, los permisos de la cuenta, el entorno y el mensaje de respuesta antes de extraer una conclusión comercial.
• Asignar únicamente el texto: las descripciones de estado pueden variar. Utiliza los códigos documentados y conserva los valores desconocidos para su revisión.
• Ignorar los requisitos de cuenta y uso: el código técnico puede ser correcto aunque la aplicación no esté configurada para el servicio solicitado.
• Actualizar sin una regla empresarial: las consultas innecesarias pueden aumentar el coste, la carga y el ruido operativo sin mejorar la experiencia del cliente.

Lista práctica de comprobación para la puesta en producción

1. Confirma que la aplicación utiliza la documentación actual de UPS y el entorno aprobado.
2. Verifica que las credenciales se almacenan en el servidor y pueden rotarse.
3. Prueba los fallos de autenticación, los errores del transportista, las entradas con formato incorrecto y los tiempos de espera.
4. Compara los estados normalizados con la respuesta original para envíos representativos.
5. Establece una política de actualización y supervisa el volumen de solicitudes.
6. Define quién es responsable de los eventos no identificados, las actualizaciones retrasadas y las escalaciones de clientes.
7. Documenta la integración para que otro desarrollador pueda actualizar de forma segura las credenciales, las versiones de los endpoints y las asignaciones de estados.

Preguntas frecuentes

¿Necesito una cuenta de UPS para utilizar la API de seguimiento?

Debes revisar los requisitos actuales de incorporación y acceso de UPS en el Portal para desarrolladores. El acceso a la API puede depender del registro de la aplicación, las credenciales, la configuración de la cuenta y el servicio específico solicitado. No supongas que el inicio de sesión de una página pública de seguimiento es intercambiable con el acceso a la API para desarrolladores.

¿La API de seguimiento de UPS es gratuita?

No supongas que el acceso a la API no tiene condiciones comerciales o de uso. UPS publica la información actual sobre servicios y cuentas a través de sus canales oficiales, y algunos requisitos pueden depender del producto, la cuenta o el acuerdo. Confirma directamente los términos aplicables antes de planificar un presupuesto de producción.

¿Puedo llamar directamente a la API de UPS desde JavaScript en un navegador?

Una llamada desde el navegador puede exponer las credenciales de la aplicación y crear problemas de origen cruzado, seguridad y control de uso. Por lo general, una integración en el servidor es el patrón más seguro para almacenar secretos, obtener tokens, aplicar reglas de reintento y limitar el acceso a los datos de los envíos.

¿Con qué frecuencia debe mi aplicación solicitar actualizaciones de seguimiento?

Utiliza una política de actualización basada en los límites documentados del transportista, el volumen de envíos, la urgencia operativa y la actualización que necesitan tus usuarios. Almacena en caché los resultados recientes cuando corresponda, utiliza intervalos progresivos después de fallos temporales y evita tratar las consultas repetidas como sustituto de una capacidad documentada de eventos o notificaciones.

¿Debo utilizar una integración directa con UPS o una API multitransportista?

Una integración directa con UPS puede adaptarse a un flujo de trabajo centrado en UPS que necesite un control específico del transportista. Una API multitransportista puede reducir el número de integraciones cuando tus envíos utilizan varios transportistas. Compara los transportistas compatibles, la autenticación, los campos de datos, los requisitos de fiabilidad, los términos de uso y el esfuerzo de implementación antes de elegir.

Fuentes

• Portal para desarrolladores de UPS — catálogo oficial de API, acceso a aplicaciones, autenticación y documentación para desarrolladores.
• Integración tecnológica de UPS — información oficial sobre la integración de la tecnología de UPS con sistemas empresariales.
• 17TRACK Tracking API — punto oficial de acceso al producto y a los recursos para desarrolladores del seguimiento multitransportista.
• Documentación de la API de 17TRACK — documentación oficial de la API para autenticación, solicitudes y gestión de respuestas.