Skip to main content
InicioBlogGuías¿Qué datos debería devolver una API de seguimiento? ¿12 campos más allá del estado actual?

¿Qué datos debería devolver una API de seguimiento? ¿12 campos más allá del estado actual?

17TRACK

Una API de seguimiento debería devolver algo más que una etiqueta como «En tránsito». Además del estado actual, busca identificadores del envío, identidad del transportista, información detallada del estado, mensajes originales del transportista, historial de eventos, marcas de tiempo de los eventos, ubicaciones, estimaciones de entrega, excepciones, transferencias entre transportistas, detalles de entrega y metadatos de actualización de los datos. En conjunto, estos 12 grupos de datos ayudan a los desarrolladores a crear flujos de trabajo fiables y proporcionan a los equipos de operaciones el contexto suficiente para actuar.

Qué datos debería devolver una API de seguimiento: 12 campos adicionales

Este es un contrato de respuesta recomendado para desarrolladores, compradores técnicos y equipos de operaciones de comercio electrónico; no afirma que todos los transportistas o API proporcionen todos los campos. Algunos valores legítimamente no estarán disponibles. Un mejor diseño hace explícitas esas carencias en lugar de rellenarlas con suposiciones.

¿Qué hace útiles los datos de seguimiento?

Un estado actual responde a una pregunta concreta: ¿cuál es el estado resumido del envío? No necesariamente explica qué ocurrió, cuándo ocurrió, si la información es reciente o qué debería hacer alguien a continuación.

Por ejemplo, dos envíos pueden mostrar «En tránsito» y, sin embargo, requerir respuestas diferentes. Uno puede tener un escaneo reciente en una instalación y ningún problema registrado. Otro puede tener un problema de dirección sin resolver anotado en su historial de eventos. Una aplicación que solo lee el estado principal puede pasar por alto esa diferencia.

Evalúa la respuesta según tres tareas prácticas: asociar el envío con el pedido correcto, explicar su progreso con precisión y decidir si está justificada alguna acción. Los siguientes campos respaldan esas tareas. Los nombres de los campos son ilustrativos; no constituyen un estándar universal ni el esquema de un proveedor específico.

12 campos que deben evaluarse además del estado actual

1. Identificadores del envío y del seguimiento

La respuesta debería identificar el envío que se está describiendo. Entre los valores útiles se incluyen el número de seguimiento enviado, el identificador del registro de seguimiento de la API y una referencia del cliente que tu sistema pueda asociar con un registro de preparación o paquete.

No des por hecho que un pedido equivale a un solo envío. Un pedido puede dividirse en varios paquetes y un reemplazo puede generar otro envío. Almacena los registros de seguimiento en el nivel del paquete o de la preparación y, después, relaciónalos con el pedido. Conserva los números de seguimiento como cadenas para no perder el formato ni los ceros iniciales.

2. Identidad del transportista

Busca un identificador estable del transportista junto con un nombre legible. Cuando esté disponible, la respuesta debería distinguir entre un transportista proporcionado explícitamente por tu aplicación y uno seleccionado mediante detección automática.

El contexto del transportista es importante al interpretar un número de seguimiento y sus eventos. Si la detección es ambigua, tu integración debería permitir resolverla en lugar de mostrar silenciosamente una coincidencia incierta como confirmada. Mantén separada la información del nivel de servicio: el nombre de un transportista por sí solo no establece si el envío utiliza un servicio exprés, postal u otro.

3. Detalle del estado normalizado

Junto al estado principal, solicita un código de detalle o subestado documentado. Una categoría general puede describir un envío como una excepción, mientras que el detalle identifica un intento de entrega, un problema de dirección o una retención relacionada con aduanas.

Usa códigos estables para la lógica empresarial y etiquetas legibles para la presentación. Confirma cómo asigna el proveedor los eventos del transportista a esos códigos, incluido el modo en que gestiona eventos desconocidos o no asignados. Una etiqueta normalizada facilita el consumo de diferentes fuentes de transportistas, pero no debería eliminar las distinciones que necesita tu equipo de soporte.

4. Mensajes y códigos originales del transportista

Conserva la descripción original del evento y el código del evento del transportista cuando se proporcionen. Estos valores ofrecen a los agentes de soporte un contexto que puede faltar en un estado normalizado, especialmente cuando un transportista utiliza una expresión operativa específica.

Mantén el texto original separado de las descripciones traducidas o reescritas. De lo contrario, una explicación dirigida al cliente podría confundirse con la redacción exacta del transportista. Trata el texto del transportista como una entrada no confiable al mostrarlo: escápalo adecuadamente y no lo renderices como HTML ejecutable.

5. Historial de eventos de seguimiento

Una respuesta útil debería exponer la cronología del envío, no solo su último evento. Idealmente, cada evento debería incluir un identificador, un estado o código, una descripción, una marca de tiempo y la información de ubicación disponible.

Comprueba si la API devuelve el historial completo, una ventana limitada o resultados paginados. Establece también cómo se representan las correcciones y las observaciones duplicadas. Tu aplicación no debería asumir que el primer elemento es siempre el más reciente, a menos que el contrato de respuesta garantice explícitamente ese orden.

6. Marcas de tiempo de los eventos e información de zona horaria

La hora en que ocurre un evento es diferente de la hora en que la API lo recibe o devuelve. Conserva ambas cuando estén disponibles. Esta distinción ayuda a explicar por qué una actualización recién recibida puede describir algo que ocurrió anteriormente.

Solicita marcas de tiempo con desplazamientos UTC explícitos o notación UTC. RFC 3339 define un formato de marca de tiempo adecuado para protocolos de Internet, incluidos los desplazamientos numéricos de zona horaria. Si una fuente solo proporciona la hora local sin un desplazamiento conocido, conserva esa incertidumbre en lugar de tratarla silenciosamente como UTC. Nunca sugieras una precisión de segundos cuando la fuente subyacente solo proporciona una fecha.

7. Ubicaciones de los eventos y geografía del envío

Busca componentes de ubicación estructurados, como ciudad, región, país y código postal, cuando se proporcionen. Conserva también una cadena de ubicación sin procesar si convertirla en campos estructurados pudiera hacer que perdiera significado.

La ubicación de un escaneo no es necesariamente la posición actual del paquete. Del mismo modo, la última instalación registrada no demuestra que el paquete siga allí. Las páginas dirigidas al cliente deberían describirla como la última ubicación registrada. Evita inferir coordenadas o una dirección exacta de entrega a partir de un texto de escaneo incompleto.

8. Fecha o intervalo estimado de entrega

Un campo de entrega estimada debería indicar si contiene una fecha única o un intervalo, quién lo generó y cuándo se actualizó por última vez. Una estimación proporcionada por el transportista y una predicción calculada por separado deberían seguir siendo distinguibles.

No conviertas una estimación que solo contiene una fecha en una hora precisa de llegada. Tu integración también debería gestionar estimaciones revisadas o retiradas sin conservar una promesa desactualizada en la página de seguimiento. Si no existe ninguna estimación, muestra que no está disponible en lugar de calcularla a partir de una suposición no respaldada.

9. Motivo de la excepción y acción requerida

La información sobre la excepción debería explicar el problema y, cuando la fuente lo admita, identificar una acción, una parte responsable o un plazo. Un aviso general de retraso es operativamente diferente de una solicitud de información del destinatario.

Mantén los hechos registrados separados de tus propias decisiones de flujo de trabajo. Por ejemplo, tu empresa podría abrir una tarea de soporte después de un periodo configurado sin actualizaciones. Esa es una regla interna de escalamiento, no una prueba de que el transportista haya declarado perdido el paquete. No generes instrucciones de pago ni solicitudes de información confidencial a partir de texto de seguimiento ambiguo.

10. Transferencias entre transportistas y números de seguimiento relacionados

Cuando un envío pasa de un operador a otro, los datos útiles incluyen el siguiente transportista, un número de seguimiento asociado y la relación entre los registros original y posterior. Esto puede ayudar a conservar la continuidad cuando el tramo de entrega utiliza un identificador diferente.

Trata una transferencia registrada como una relación en lugar de sobrescribir el transportista original. No fusiones registros simplemente porque sus destinos o números de seguimiento parezcan similares. Si la relación no se proporciona o confirma de otro modo, mantenla sin resolver en lugar de inventar un trayecto continuo.

11. Resultado de la entrega y referencias de comprobación

Cuando se registre una entrega, la respuesta debería proporcionar la hora de entrega registrada y cualquier detalle disponible, como una descripción del lugar seguro o la categoría del destinatario. Una referencia de comprobante de entrega también puede ser útil cuando el transportista y el servicio la pongan a disposición.

Un estado de entregado no debería tratarse como prueba de que el destinatario previsto aceptó personalmente el paquete. Las firmas, fotografías, nombres y ubicaciones precisas pueden contener información personal. Limita el acceso, evita exponer estos datos en páginas públicas de seguimiento y confirma los requisitos de autorización o caducidad de los enlaces de comprobante.

12. Actualización, estado de recuperación y metadatos de respuesta

Solicita suficientes metadatos para distinguir el último evento del envío de la última recuperación correcta de datos. Entre los valores útiles se incluyen la última comprobación correcta, el último intento fallido, la hora de generación de la respuesta y si los datos devueltos están almacenados en caché o son parciales.

Una solicitud correcta a la API no establece por sí misma que el transportista haya publicado un nuevo escaneo. La semántica de la respuesta HTTP describe el resultado de la solicitud; el progreso del envío pertenece a los datos de la aplicación. Conserva los errores de recuperación separados de las excepciones del envío para que un problema temporal de conexión no se convierta en una alerta falsa de entrega.

Los datos faltantes necesitan un significado definido

La presencia de un campo es solo una parte del contrato. Tu equipo también necesita entender qué significa la ausencia de un valor. Una estimación de entrega podría no estar disponible en la fuente, no haberse recuperado todavía o dejar de ser aplicable después de la entrega. Estas situaciones no deberían generar automáticamente el mismo mensaje para el cliente.

  • Desconocido: El valor no se ha establecido.
  • No proporcionado: La fuente no proporcionó el valor en los datos recuperados.
  • No aplicable: El campo no se aplica a este registro o estado.
  • Error de recuperación: El sistema no pudo completar la consulta correspondiente.

Estas son distinciones recomendadas, no valores literales obligatorios. Sea cual sea la representación que elijas, documéntala. Evita fechas de marcador de posición, objetos vacíos que parezcan registros válidos y coordenadas predeterminadas que puedan confundirse con ubicaciones reales.

Cómo probar la respuesta antes de integrarla

Evalúa cargas útiles reales de los transportistas, servicios y rutas de envío que utiliza tu empresa. Un esquema puede enumerar un campo opcional sin garantizar que todas las fuentes subyacentes lo completen. Para una integración con 17TRACK, utiliza la documentación oficial de Tracking API para comprobar el contrato de respuesta, en lugar de tratar los nombres conceptuales de los campos de esta guía como parámetros listos para copiar.

  1. Construye una muestra representativa. Incluye envíos recién registrados, envíos activos, intentos de entrega, entregas completadas y casos de transferencia disponibles.
  2. Rastrea los campos hasta los eventos. Confirma que el estado mostrado, el último evento y los detalles de entrega describan un registro coherente. Investiga las discrepancias en lugar de ocultarlas.
  3. Prueba las actualizaciones retrasadas y repetidas. Vuelve a procesar la misma carga útil y recibe un evento más antiguo después de uno más reciente. Confirma que ninguno de los casos cree notificaciones duplicadas ni revierta incorrectamente el estado mostrado.
  4. Prueba valores ausentes y malformados. Incluye estimaciones ausentes, ubicaciones desconocidas, códigos de estado no familiares y marcas de tiempo incompletas. La aplicación debería seguir siendo utilizable sin inventar reemplazos.
  5. Separa los fallos de transporte de los resultados del seguimiento. Un fallo de autenticación, un tiempo de espera agotado o una respuesta malformada deberían entrar en una ruta de error de integración, no en un flujo de trabajo de excepción del envío.
  6. Valida la vista del cliente. Comprueba que las referencias internas, los detalles de diagnóstico sin procesar y la información personal no se filtren en páginas públicas ni notificaciones.

Para las actualizaciones basadas en webhooks, comprueba también los identificadores de entrega, la autenticación, el comportamiento de reintento y la gestión de repeticiones en la documentación del proveedor. Estos son requisitos de integración, no hechos del envío. Tu receptor debería procesar las entregas repetidas de forma segura y no debería asumir que el orden de llegada equivale al orden de los eventos.

El criterio de aceptación debería ser práctico: ¿puede tu aplicación explicar el envío sin realizar afirmaciones no respaldadas y puede tu equipo de operaciones identificar la siguiente acción justificada? Una carga útil más pequeña y bien definida puede ser más útil que una respuesta más grande llena de valores opcionales inexplicados.

Preguntas frecuentes

¿Es necesario que todos los envíos tengan completos los 12 grupos de datos?

No. Las pruebas de entrega, los números de seguimiento posteriores y las fechas estimadas de entrega pueden no estar disponibles o no ser aplicables. Exige definiciones claras de los campos y un comportamiento predecible para los valores faltantes en lugar de exigir que todos estén siempre completos. Comprueba los campos más importantes según tu combinación real de envíos.

¿Debemos almacenar la respuesta sin procesar o solo los campos normalizados?

Almacena campos normalizados para la lógica de la aplicación. Conservar las cargas útiles pertinentes de la fuente también puede ayudar con la depuración y los cambios de mapeo, sujeto a tus requisitos de privacidad, seguridad, contractuales y de conservación. Restringe el acceso y evita conservar contenido confidencial simplemente porque aparezca en una respuesta.

¿Qué marca de tiempo debería determinar el último evento?

Utiliza la cronología documentada de los eventos y las reglas de ordenación del proveedor, teniendo en cuenta las zonas horarias y las correcciones. La hora de recepción indica cuándo tu sistema conoció un evento, no necesariamente cuándo ocurrió. Si las marcas de tiempo están incompletas o entran en conflicto, conserva la ambigüedad en lugar de afirmar una secuencia precisa.

¿Puede una API de seguimiento confirmar que un paquete se ha perdido?

Trata una pérdida como comunicada por el transportista únicamente cuando la fuente admita explícitamente esa interpretación. Un periodo prolongado sin escaneos puede justificar una investigación conforme a tus reglas operativas, pero el silencio por sí solo no demuestra una pérdida. Mantén «seguimiento obsoleto» y «pérdida comunicada» como conceptos separados.

¿Es suficiente un estado de entregado para cerrar una reclamación del cliente?

No automáticamente. Establece el resultado registrado del seguimiento, pero puede no resolver la disputa del destinatario. Revisa los detalles de entrega disponibles, la cuenta del cliente y tu proceso de soporte. Evita tratar una etiqueta de estado como sustituto de la investigación de información contradictoria.

Fuentes