Skip to main content
InicioBlogGuías¿Qué campos de respuesta de la API de seguimiento permiten crear una línea de tiempo completa del seguimiento del envío?

¿Qué campos de respuesta de la API de seguimiento permiten crear una línea de tiempo completa del seguimiento del envío?

17TRACK

Una cronología completa del seguimiento de un envío necesita más que un estado actual. Para cada evento de seguimiento, conserva un identificador del envío, la marca de tiempo del evento, la descripción o el código del evento del transportista, un estado normalizado cuando esté disponible y la ubicación del evento cuando se proporcione. Añade el contexto del transportista y del número de seguimiento, los detalles de entrega o excepción y una forma de conservar el orden y las actualizaciones de los eventos. Los nombres exactos de los campos varían según la API; el objetivo es reconstruir qué ocurrió, cuándo, dónde y con qué paquete.

Qué campos de respuesta de la API de seguimiento permiten crear un seguimiento completo del envío

Para un desarrollador que crea una página de pedidos, un panel de soporte o un flujo de trabajo logístico, la distinción más útil es entre el resumen del envío y el historial de eventos. Un resumen responde a «¿Cuál es el estado conocido más reciente?». Una cronología responde a «¿Cómo llegó el envío a ese estado?». Ambos son necesarios, pero no deben tratarse como intercambiables.

Comienza con la identidad del envío, no con el estado

Cada evento debe estar asociado al envío correcto. Un número de seguimiento suele ser el punto de partida, pero no debería ser el único identificador del modelo de datos interno. Conserva el identificador del envío o del registro de seguimiento de la API si se proporciona, junto con tus propios identificadores del pedido y del paquete. Registra el identificador o el nombre del transportista y, cuando corresponda, el contexto de destino u origen utilizado para identificar el envío.

Esto es importante cuando un pedido tiene varios paquetes, se corrige un número de seguimiento o una transferencia introduce otro transportista o número de referencia. Si una API expone números de seguimiento relacionados o detalles de la transferencia entre transportistas, almacena la relación en lugar de combinar dos historiales simplemente porque pertenecen al mismo pedido. Un pedido puede tener varias cronologías de envío válidas.

A nivel de evento, un conjunto práctico de identificadores incluye la referencia del envío, el transportista responsable del evento si se conoce y un ID de evento estable proporcionado por la API o suficientes datos de origen para identificar un evento repetido. No supongas que dos escaneos con el mismo estado son duplicados: un paquete puede recibir el mismo tipo de escaneo en distintas instalaciones o momentos.

Los campos de respuesta que hacen útil cada evento

Los nombres de campos como event_time y status que aparecen a continuación describen funciones de datos, no un esquema universal de una API de seguimiento. Adáptalos a la respuesta real documentada por tu proveedor.

  • Hora del evento: La hora en la que el transportista indica que ocurrió el evento. Conserva el valor original y la información de zona horaria cuando se proporcione. Normalmente es la marca de tiempo principal para una cronología orientada al cliente.
  • Descripción del evento o código del transportista: El texto original del escaneo o el código de evento legible por máquina. Conservar el valor de origen hace que la etiqueta normalizada pueda auditarse y ayuda a los equipos de soporte a investigar escaneos desconocidos.
  • Estado normalizado: Una categoría del proveedor o de la aplicación, como en tránsito, en reparto, entregado o excepción. Úsala para agrupar eventos, pero no permitas que sustituya los detalles del escaneo original.
  • Ubicación: La instalación, ciudad, región, país u otros campos de ubicación que proporcione realmente el transportista. Muestra únicamente la precisión presente en la respuesta; no conviertas un escaneo a nivel de país en una ubicación implícita a nivel de calle.
  • Contexto del transportista y del seguimiento: El identificador del transportista, el número de seguimiento y cualquier número relacionado necesario para explicar una transferencia o distinguir paquetes.
  • Metadatos del evento: Un ID de evento de origen, número de secuencia u otra referencia del proveedor, si está disponible. Estos campos pueden ayudar con la eliminación de duplicados, las correcciones y el orden estable.

Aun cuando falten algunos campos opcionales, se puede crear una cronología útil. Por ejemplo, un evento válido de «entregado» puede no tener una ubicación pública de entrega. La aplicación debe mostrar el evento confirmado sin inventar una ubicación o un destinatario.

Mantén separadas la hora del evento y la hora de procesamiento

Los sistemas de seguimiento pueden exponer varias marcas de tiempo: cuándo ocurrió un escaneo, cuándo lo publicó un transportista, cuándo lo registró un proveedor de API y cuándo lo recibió tu aplicación. Estas marcas responden a preguntas diferentes. Ordena el recorrido mostrado principalmente por la hora de ocurrencia del evento cuando sea fiable; utiliza la hora de ingesta para explicar cuándo tu sistema conoció el evento y detectar actualizaciones recibidas con retraso.

Los datos recibidos con retraso son lo bastante habituales como para diseñar pensando en ellos. Un transportista puede publicar un escaneo anterior después de que ya sea visible uno posterior. Si la aplicación simplemente añade cada nueva respuesta de la API al final de la página, la cronología resultante puede ser incorrecta. Concilia los eventos con el historial almacenado y después ordénalos usando una regla documentada. Si dos eventos tienen la misma hora de ocurrencia, una secuencia de origen o un ID de evento puede servir como desempate. De lo contrario, conserva un orden interno determinista sin afirmar que el origen estableció uno.

El tratamiento de las zonas horarias merece especial atención. Una marca de tiempo con desplazamiento horario puede normalizarse para el almacenamiento mientras la marca original permanece disponible para su visualización o investigación. Una marca de tiempo sin desplazamiento indicado no debe interpretarse silenciosamente como UTC. Para integraciones que aceptan o emiten marcas de tiempo de Internet, RFC 3339 es una referencia útil para la representación de marcas de tiempo; por sí sola, no indica qué zona horaria pretendía el transportista cuando sus datos omiten una.

Separa el estado más reciente del historial completo

Muchas respuestas de seguimiento incluyen tanto el estado actual del envío como una lista de eventos históricos. El estado actual es útil para una tarjeta de pedido compacta, los filtros y las notificaciones. El historial es la fuente de la secuencia de escaneos. No crees un nuevo evento histórico cada vez que consultes un estado actual que no ha cambiado, ni descartes eventos anteriores simplemente porque el objeto del estado más reciente esté completo.

Evita también suponer que el último elemento de una matriz es el escaneo más reciente. Comprueba las reglas de ordenación del proveedor y después ordena o reconcilia según corresponda. Una respuesta puede contener solo una parte del historial, o una integración puede necesitar recuperar páginas adicionales. Si la API documenta la paginación o un límite del historial, sigue ese mecanismo antes de describir el recorrido mostrado como completo. Cuando el historial no esté disponible, etiqueta la vista como los eventos recibidos en lugar de insinuar que no ocurrieron escaneos anteriores.

Para una representación interna sólida, almacena la respuesta sin procesar o los campos de origen necesarios para reproducir tu interpretación junto con un registro de evento normalizado. Conservar los valores de origen es especialmente valioso cuando cambia una correspondencia: puedes volver a procesar eventos antiguos sin pedir al transportista que recree datos que quizá ya no se puedan recuperar.

Modela cuidadosamente los hitos, las excepciones y las pruebas de entrega

Una etiqueta de estado no siempre es un hito. «En tránsito» puede resumir varios escaneos, mientras que «en reparto» y «entregado» suelen representar etapas distintas. Crea hitos a partir de los significados documentados de los eventos en lugar de suponer que todos los transportistas utilizan una redacción idéntica. Si un estado es ambiguo, muestra la descripción original y evita añadir una afirmación más contundente.

Los eventos de excepción necesitan tanto una categoría como los detalles del transportista cuando estén disponibles. «Entrega intentada» cuenta una historia diferente de «Despacho de aduanas pendiente», aunque una aplicación agrupe ambos en un estado que requiere atención. Conserva el texto del motivo, el código del motivo y la información sobre la próxima acción como campos separados si la respuesta los proporciona. Así, un agente de soporte puede distinguir un retraso temporal de un evento que puede requerir una acción del destinatario.

La confirmación de entrega debe tratarse con el mismo cuidado. Si la respuesta incluye un evento de entrega, registra su marca de tiempo y la ubicación o los datos del destinatario disponibles. Si incluye información de comprobante de entrega, conserva el tipo de prueba y las restricciones de acceso definidas por el proveedor. No infieras una firma, una fotografía ni un destinatario identificado a partir de un estado de entregado por sí solo. Del mismo modo, una fecha estimada de entrega es una previsión, no un evento completado; muéstrala por separado de la cronología histórica.

Flujo práctico de correspondencia para desarrolladores

  1. Inspecciona una respuesta real y su documentación. Identifica el objeto a nivel de envío, la matriz de eventos, los formatos de las marcas de tiempo, el vocabulario de estados y cualquier límite o paginación documentados. No supongas que los nombres de campos ilustrativos de un artículo coinciden con un esquema de producción.
  2. Define un único modelo interno de eventos. Incluye la identidad del envío, el transportista de origen, la hora de ocurrencia, el texto o código de estado original, la categoría normalizada, la ubicación opcional, el identificador del evento de origen y la hora de recepción. Haz que los campos opcionales acepten valores nulos en lugar de rellenarlos con suposiciones.
  3. Escribe reglas de correspondencia explícitas. Registra cómo cada campo de origen se convierte en un campo interno y qué valor de origen respalda cada estado normalizado. Mantén visibles los códigos desconocidos para su revisión en lugar de forzarlos a un hito incorrecto.
  4. Concilia las respuestas repetidas. Utiliza un ID de evento documentado cuando esté disponible. De lo contrario, define una regla de coincidencia prudente utilizando valores de origen estables y pruébala con varios escaneos que compartan legítimamente un estado.
  5. Prueba recorridos difíciles. Incluye varios paquetes, escaneos retrasados, marcas de tiempo iguales, transferencias entre transportistas, intentos de entrega, ubicaciones ausentes, cambios en las estimaciones y un evento de entrega con detalles de confirmación limitados.
  6. Comprueba lo que promete la interfaz. La cronología debe distinguir los eventos observados de las previsiones, conservar la incertidumbre y evitar presentar un historial incompleto como un relato completo del envío.

Para una integración con la API de seguimiento de 17TRACK, utiliza la documentación oficial de la API para confirmar la estructura real de la respuesta y el significado de los campos antes de implementar esta correspondencia. Las funciones de los campos de esta guía son una lista de comprobación de implementación, no una afirmación de que 17TRACK devuelva campos con estos nombres exactos o de que todos los transportistas proporcionen todos los detalles.

¿Qué se considera una cronología completa?

Una cronología está completa para tu aplicación cuando conecta cada evento mostrado con el paquete correcto, conserva el evento de origen y su hora, ordena los eventos conocidos de forma coherente y representa el estado, la ubicación, las excepciones y la confirmación de entrega únicamente en la medida respaldada por la respuesta. La integridad operativa también exige conocer los límites de los datos: si la API devolvió todo el historial disponible, una ventana limitada o solo eventos de un transportista o registro de seguimiento concreto.

La mejor prueba de aceptación no es el número de campos rellenados. Es si un cliente o un agente de soporte puede leer el recorrido sin llevarse a engaño. Si la aplicación puede responder qué ocurrió, cuándo ocurrió, a qué envío corresponde y qué sigue siendo incierto, los campos de respuesta están cumpliendo su función.

Preguntas frecuentes

¿Es suficiente un campo de estado actual para crear una cronología del envío?

No. Un estado actual proporciona una instantánea. Una cronología necesita registros históricos de eventos con marcas de tiempo y el contexto necesario para asociar cada registro con el envío correcto.

¿Debo mostrar el texto de escaneo del transportista o solo los estados normalizados?

Conserva ambos cuando la API los proporcione. Los estados normalizados facilitan la lectura del recorrido; las descripciones originales conservan los detalles y ayudan a explicar eventos inusuales o específicos del transportista.

¿Qué marca de tiempo debe determinar el orden de los eventos?

Utiliza la hora de ocurrencia del evento cuando su significado y zona horaria sean suficientemente claros. Conserva la hora de recepción de la API por separado y define un desempate estable para los eventos con horas de ocurrencia idénticas o inciertas.

¿Qué ocurre si un evento de seguimiento no tiene ubicación?

Muestra el evento sin ubicación. La ausencia de datos de ubicación no invalida el evento, pero tampoco justifica inferir una instalación, ciudad o dirección de entrega.

¿Cómo puedo saber si la API devolvió todo el recorrido?

Consulta la documentación del proveedor sobre el alcance del historial, la paginación y los límites de respuesta; después, verifica cómo tu integración recupera eventos adicionales. Si no se puede confirmar el alcance, describe la cronología como los eventos disponibles para tu aplicación.

Fuentes