Skip to main content
InicioBlogGuíasCómo obtener el estado más reciente del envío mediante la API sin esperar un webhook

Cómo obtener el estado más reciente del envío mediante la API sin esperar un webhook

17TRACK

Para obtener el estado de envío más reciente disponible sin esperar a un webhook, envía una solicitud autenticada a la API de consulta de envíos de tu proveedor de seguimiento. Usa la respuesta para actualizar inmediatamente tu aplicación y, después, mantén los webhooks habilitados para los cambios posteriores. La distinción importante es que una consulta normalmente recupera la información de seguimiento más reciente almacenada por el proveedor; no necesariamente activa una nueva comprobación por parte del transportista.

Cómo obtener el estado de envío más reciente mediante la API sin

Este enfoque es útil cuando un cliente abre una página de pedido, un agente de soporte necesita una actualización o tu sistema debe recuperarse de una notificación perdida. Una implementación fiable combina consultas bajo demanda, indicadores claros de actualidad y protecciones contra actualizaciones duplicadas o fuera de orden.

Decide qué significa “estado de envío más reciente”

Antes de elegir un endpoint, distingue entre tres operaciones que pueden parecer similares, pero producen resultados diferentes.

OperaciónQué haceQué no establece
Leer tu propia base de datosDevuelve la información de seguimiento que tu aplicación ya tiene.Si el proveedor ha recibido una actualización más reciente.
Consultar la API de seguimientoRecupera la información disponible mediante la operación de consulta del proveedor.Si se realizó una nueva consulta al transportista durante esa solicitud.
Solicitar una actualización del seguimientoSolicita otra comprobación ascendente, si el proveedor ofrece esa operación.Que el transportista tenga un nuevo escaneo o que la actualización se complete de forma síncrona.

Usa una consulta cuando necesites una respuesta ahora. Investiga una operación de actualización solo cuando necesites que el proveedor intente otra comprobación ascendente. No supongas que añadir un parámetro para evitar la caché, repetir una solicitud o enviar un encabezado HTTP de control de caché obligará al transportista a proporcionar información nueva.

La visibilidad del envío tiene varias etapas: el transportista registra un evento, el proveedor de seguimiento lo obtiene y tu aplicación lo recibe o recupera. Una solicitud directa a la API puede evitar la espera de la entrega de una notificación, pero no puede eliminar los retrasos anteriores en esa cadena.

Comprueba el contrato de consulta antes de escribir código

El desarrollador que integra el servicio de seguimiento es responsable de este flujo de trabajo. Empieza con la documentación actual del proveedor, no con un endpoint copiado de un ejemplo antiguo de integración. Confirma estos detalles:

  • Identidad del envío: ¿La consulta acepta un número de seguimiento, un ID de envío interno o un número de seguimiento combinado con un identificador del transportista?
  • Requisitos de registro: ¿Es necesario registrar el envío antes de poder consultarlo?
  • Autenticación: ¿Qué encabezado o mecanismo de autenticación se requiere?
  • Significado de la respuesta: ¿La operación devuelve información almacenada, inicia la recopilación o devuelve un trabajo que debe comprobarse más tarde?
  • Gestión del resultado: ¿Una respuesta HTTP correcta puede contener un error a nivel de envío o un resultado pendiente?
  • Limitaciones de uso: ¿Qué límites de frecuencia, límites por lote y restricciones específicas de la cuenta se aplican?
  • Campos de actualidad: ¿Qué marcas de tiempo representan los eventos del transportista, las actualizaciones del proveedor y la generación de la respuesta?

Para una integración con 17TRACK, la API de seguimiento es el producto pertinente, en lugar de una página de seguimiento para consumidores o una interfaz de seguimiento de tienda. Usa la documentación oficial de la API para confirmar la operación de consulta de información de seguimiento, la autenticación, los campos de solicitud y la estructura de respuesta de tu integración. Trata las consultas y la gestión de webhooks como rutas de aplicación independientes que actualizan el mismo registro de envío.

Evita codificar de forma fija suposiciones sobre el comportamiento de actualización o la frecuencia de las consultas. Esos detalles deben coincidir con la operación y las condiciones del servicio que realmente utilizas.

Crea una consulta bajo demanda a través de tu backend

Un diseño práctico consiste en exponer un endpoint autenticado en tu propia aplicación. El navegador solicita una actualización del envío a ese endpoint; tu servidor comprueba la autorización, decide si es necesaria una consulta al proveedor y devuelve un resultado normalizado.

La siguiente ruta es un ejemplo de un endpoint que crearías en tu aplicación. No es un endpoint de 17TRACK ni una especificación de solicitud del proveedor.

GET /api/orders/{order_id}/shipment-status

Usa el identificador del pedido para buscar el envío en el servidor. No permitas que un solicitante recupere el historial de seguimiento de otro cliente simplemente reemplazando un número de seguimiento en una solicitud. Mantén las credenciales de la API del proveedor en tu backend, no en JavaScript del navegador ni en el paquete de una aplicación móvil.

Un flujo de solicitud que puedes implementar

  1. Autoriza el acceso. Confirma que el cliente o miembro del personal puede ver el pedido.
  2. Resuelve el envío. Lee el identificador de seguimiento almacenado y la información del transportista, cuando corresponda.
  3. Comprueba la actualidad local. Si ya existe una consulta correcta reciente, reutilízala según la política de actualidad de tu aplicación.
  4. Consulta al proveedor cuando sea necesario. Usa la operación documentada y un tiempo de espera limitado para la solicitud.
  5. Valida el resultado. Comprueba tanto el resultado HTTP como el resultado a nivel de envío.
  6. Combina la información. Aplica las mismas reglas de normalización y conciliación utilizadas para los eventos de webhook.
  7. Devuelve el estado y la actualidad. Incluye la hora del evento más reciente y la hora de la última comprobación correcta del proveedor, cuando estén disponibles.

La política de actualidad local es una decisión de ingeniería, no una afirmación sobre la frecuencia de actualización del transportista. Elígela según los requisitos de tu interfaz, los límites del proveedor, el volumen de envíos y la utilidad observada de las consultas. Un cliente que pulse repetidamente un botón de actualización no debería crear un flujo ilimitado de solicitudes ascendentes.

Normaliza la respuesta sin inventar la actualidad

Tu aplicación puede devolver un formato interno estable incluso cuando las estructuras de respuesta del proveedor difieren. Este objeto ilustrativo es el contrato de tu propia aplicación, no un payload real del proveedor:

{
  "shipment_id": "internal-shipment-id",
  "status": "in_transit",
  "latest_event_at": null,
  "provider_updated_at": null,
  "last_successful_query_at": null,
  "retrieval_state": "success",
  "source": "provider_query"
}

Rellena cada marca de tiempo solo cuando se conozca su significado. La hora en que tu servidor recibió una respuesta pertenece a los metadatos de la consulta; no debe presentarse como la hora en que se movió el paquete. Si el proveedor no proporciona una marca de tiempo de actualización del proveedor, deja ese campo ausente o con valor null en lugar de sustituirlo por otra marca de tiempo.

En la interfaz del cliente, separa los mensajes: “Último evento del transportista” describe la actividad del envío, mientras que “Seguimiento comprobado” describe la actividad de recuperación de tu aplicación. Esta distinción evita que un escaneo sin cambios parezca recién registrado.

Evita que las consultas de la API y los webhooks se sobrescriban entre sí

Cuando ambos mecanismos están activos, el mismo evento puede llegar mediante una consulta y un webhook. También pueden finalizar en un orden diferente al de inicio. Una consulta iniciada primero puede completarse después de que un webhook ya haya proporcionado información más reciente.

No uses una lógica de “gana la última respuesta”. El payload recibido más recientemente no es necesariamente el estado de envío más reciente.

  • Comparte una única canalización de actualización. Envía los resultados de las consultas y los payloads de los webhooks mediante las mismas funciones de validación, normalización y persistencia.
  • Deduplica los eventos. Da prioridad a un identificador de evento documentado. Si no existe, crea una huella definida cuidadosamente a partir de los campos disponibles, como la hora del evento, el estado, la ubicación y la descripción.
  • Usa campos de ordenación con semántica conocida. Una revisión o secuencia documentada es más útil que suponer que la hora de llegada representa el orden de los eventos.
  • Conserva el historial. Un evento recibido recientemente puede completar una brecha histórica sin cambiar el resumen actual del envío.
  • Permite correcciones. Los estados no forman una escala lineal universal. Sigue el comportamiento de corrección documentado en lugar de rechazar permanentemente toda transición aparentemente regresiva.

Cuando el orden de los eventos sea incierto, conserva el payload original y su procedencia para investigarlo. No resuelvas la ambigüedad inventando una marca de tiempo del evento o suponiendo que todas las marcas de tiempo del transportista comparten la misma zona horaria.

Gestiona de forma diferente los datos faltantes y las solicitudes fallidas

Un resultado vacío, un resultado sin cambios y una solicitud fallida no deberían generar el mismo mensaje para el cliente.

La consulta tiene éxito, pero el estado no ha cambiado

Mantén el estado de envío existente y actualiza la hora de la última consulta correcta. No generes un nuevo evento de envío simplemente porque se completó otra consulta. Si el cliente necesita más detalles, muestra el historial de eventos existente y explica que no se devolvió ningún evento de seguimiento más reciente.

El envío aún no tiene información de seguimiento

Comprueba si es necesario registrarlo, si el identificador y el transportista son correctos y cómo representa el proveedor la recopilación pendiente. La ausencia de eventos no demuestra por sí sola que el número de seguimiento no sea válido o que el paquete se haya perdido. Conserva la distinción del proveedor entre un identificador desconocido, un envío registrado a la espera de información y una solicitud que no pudo procesarse.

La solicitud al proveedor agota el tiempo de espera o falla

Si tienes un estado válido anterior, devuélvelo con una indicación explícita de que la última comprobación no tuvo éxito. Mantén sin cambios la marca de tiempo de la consulta correcta anterior. Un error de red no es una excepción de entrega y no debería cambiar el estado comercial del paquete.

Usa reintentos limitados con retroceso y variación aleatoria para los fallos transitorios apropiados. No repitas continuamente los reintentos de credenciales no válidas o solicitudes con formato incorrecto. Cuando una respuesta proporcione Retry-After, interprétala según el contrato del proveedor y la semántica HTTP. La especificación HTTP permite expresar ese valor como un retraso en segundos o como una fecha HTTP.

Llegan varias solicitudes para el mismo envío

Combina las consultas simultáneas para que puedan compartir una única solicitud ascendente. Aplica límites por cuenta y envío, y evita que un reintento automático se multiplique en varias capas de la aplicación. Cuando se admita el procesamiento por lotes, inspecciona el resultado de cada envío en lugar de considerar correcto todo el lote porque la solicitud HTTP se completó.

Usa el sondeo como alternativa controlada

Sin webhooks, el sondeo programado puede mantener actualizada tu base de datos, pero requiere una política operativa explícita. Decide qué envíos siguen siendo aptos, cómo afectan los fallos al calendario y cuándo debe detenerse el sondeo rutinario.

Para la mayoría de las integraciones, un diseño híbrido es un punto de partida sensato: los webhooks gestionan los cambios en segundo plano, las consultas bajo demanda atienden las solicitudes interactivas y los trabajos de conciliación comprueban los registros que requieren atención. Esta es una recomendación arquitectónica, no una garantía de que minimice los costes para todas las cuentas.

  • Da prioridad a los envíos activos y a los registros con errores de recuperación no resueltos.
  • Evita consultar todos los envíos históricos en cada ejecución programada.
  • Define cómo se gestionan los envíos completados, incluida cualquier ventana de corrección que requiera tu negocio.
  • Registra con qué frecuencia las consultas encuentran información realmente nueva.
  • Investiga los problemas de entrega de webhooks en lugar de ocultarlos mediante un sondeo cada vez más frecuente.

Supervisa la latencia de las solicitudes al proveedor, las consultas fallidas, las respuestas por límite de frecuencia y las diferencias entre los datos consultados y los registros alimentados por webhooks. Supervisa por separado la antigüedad del último evento del transportista. Pueden coexistir respuestas correctas de la API con información de seguimiento que no haya cambiado.

Prueba el flujo de trabajo antes del lanzamiento

Una solicitud correcta es solo la primera prueba. Verifica las situaciones que, de otro modo, podrían generar actualizaciones de estado engañosas:

  • Llega un webhook mientras una consulta bajo demanda todavía está en ejecución.
  • Dos clientes o sesiones del personal solicitan el mismo envío simultáneamente.
  • El proveedor devuelve éxito HTTP, pero informa de un error a nivel de envío.
  • Una solicitud falla después de que tu aplicación ya tenga información de seguimiento válida.
  • Un evento no tiene zona horaria o contiene un código de estado desconocido.
  • Una corrección del transportista cambia un resultado mostrado anteriormente.
  • Un usuario intenta acceder a un envío perteneciente a otra cuenta.

Tu criterio de lanzamiento debería ser que la aplicación devuelva la mejor información de envío conocida, explique su actualidad con precisión y no la corrompa cuando las solicitudes fallen o lleguen fuera de orden.

Preguntas frecuentes

¿Consultar la API obliga al transportista a escanear o actualizar un paquete?

No. Recuperar información de seguimiento no puede provocar un escaneo físico. Que una solicitud active una consulta ascendente depende de la operación documentada. Incluso una actualización compatible puede devolver información sin cambios si el transportista no tiene ningún evento más reciente.

¿Puedo usar consultas de la API sin configurar webhooks?

Si el proveedor admite el flujo de consulta requerido, puedes crear una integración basada en solicitudes bajo demanda o sondeo. Confirma primero los requisitos de registro y consulta. A partir de entonces, tu aplicación será responsable de decidir cuándo comprobar, controlar el volumen de solicitudes y detectar cambios.

¿Con qué frecuencia debería consultar el estado del envío?

No existe un intervalo universal. Elige un calendario que se ajuste a los límites de tu proveedor, al volumen de envíos y al valor comercial de encontrar antes las actualizaciones. Mide con qué frecuencia el sondeo devuelve eventos nuevos y ajusta el calendario, en lugar de suponer que las solicitudes frecuentes producen datos más recientes del transportista.

¿Por qué la API devuelve información que ya recibí mediante un webhook?

Ambas rutas pueden exponer el mismo registro de envío subyacente. Un webhook entrega una notificación, mientras que una consulta recupera información bajo demanda. Recibir el mismo evento por ambas vías no es necesariamente un error; tu aplicación debe deduplicarlo.

¿El botón de actualización debería decir “Actualizar seguimiento”?

Solo si esa expresión describe con precisión la operación. Si el botón recupera datos almacenados del proveedor, “Comprobar actualizaciones” es más claro. Muestra el último evento del transportista por separado de la hora en que tu aplicación completó por última vez una comprobación correcta.

Fuentes