Skip to main content
InicioBlogGuíasFlujo de trabajo de la API de seguimiento de envíos: desde el registro de un envío hasta la obtención de los detalles de seguimiento

Flujo de trabajo de la API de seguimiento de envíos: desde el registro de un envío hasta la obtención de los detalles de seguimiento

17TRACK

Un flujo de trabajo de una API de seguimiento de envíos comienza con el envío de un número de seguimiento y cualquier información requerida del transportista, la comprobación de si el registro se realizó correctamente, la espera a que los datos de seguimiento estén disponibles y la recuperación del estado y el historial de eventos del envío. Para una integración en producción, los desarrolladores también deben vincular cada registro de seguimiento con un pedido, gestionar los fallos parciales, procesar las actualizaciones de forma segura y distinguir entre un registro aceptado y un escaneo real del transportista.

Flujo de trabajo de la API de seguimiento de envíos: desde el registro de un envío hasta la recuperación de la información

Esta guía explica ese flujo de trabajo para desarrolladores que conectan una plataforma de comercio electrónico, un sistema de gestión de pedidos, una aplicación de almacén o una herramienta de atención al cliente. Separa las recomendaciones de diseño de aplicaciones de los requisitos específicos de la API del proveedor. Para una integración con 17TRACK, utiliza la documentación oficial de la API para confirmar el esquema de la solicitud, la autenticación, las operaciones compatibles y los campos de respuesta antes de implementar los ejemplos siguientes.

Comprende qué hace y qué no hace el registro

Registrar un envío con un servicio de seguimiento significa enviar un identificador para que el servicio pueda realizar el seguimiento o gestionar dicho envío de acuerdo con el contrato de su API. No es la misma operación que comprar franqueo, generar una etiqueta de envío, reservar una recogida o entregar un paquete a un transportista.

Mantén separados tres resultados en tu aplicación:

  • Solicitud recibida: La API devolvió una respuesta a tu solicitud HTTP.
  • Registro aceptado: El servicio aceptó el registro de seguimiento individual para su procesamiento.
  • Información de seguimiento disponible: El servicio dispone de información del envío que tu aplicación puede recuperar o recibir.

Estos resultados no deben reducirse a un único indicador de «éxito». Un número de seguimiento aceptado puede no tener todavía eventos del transportista. Del mismo modo, una respuesta HTTP correcta para una solicitud por lotes no demuestra que todos los elementos del lote hayan sido aceptados; inspecciona la estructura del resultado a nivel de aplicación definida por el proveedor.

1. Prepara la identidad del envío y la configuración de la API

Antes de realizar una solicitud de registro, decide cómo se identificará un envío dentro de tu propio sistema. Por lo general, un identificador de pedido por sí solo no es suficiente, porque un pedido puede dividirse en varios paquetes. Asigna a cada envío o paquete su propio registro interno y asocia ese registro con el pedido correspondiente.

Un registro interno útil incluye la siguiente información. Estos son campos de aplicación sugeridos, no un esquema de solicitud de 17TRACK.

  • ID interno del envío: Tu identificador estable para el paquete.
  • Referencia del pedido: El pedido o registro de cumplimiento al que pertenece.
  • Número de seguimiento: El identificador asignado por el transportista, almacenado como texto para conservar los ceros iniciales.
  • Información del transportista: La identidad del transportista proporcionada por tu sistema de cumplimiento, si se conoce.
  • Referencia del proveedor: Cualquier identificador devuelto por el servicio de seguimiento que sea necesario para operaciones posteriores.
  • Estado del registro: Tu registro de si el envío está pendiente, aceptado, rechazado o a la espera de conciliación.
  • Estado del seguimiento: El estado más reciente del envío, mantenido por separado del estado del registro.

Valida los datos antes del envío. Elimina los espacios en blanco accidentales de los extremos, pero no reescribas el número de seguimiento basándote en suposiciones sobre el formato del transportista. Conserva el valor original para solucionar problemas. Si se conoce el transportista, asígnalo al identificador documentado del proveedor en lugar de enviar un nombre informal para mostrar.

Configura la autenticación en el servidor. Mantén las credenciales fuera del control de versiones, separa la configuración de desarrollo de la de producción y elimina los secretos de los registros. Confirma la versión documentada de la API, los límites de solicitudes, los límites de lotes y los requisitos de la cuenta, en lugar de tomar valores de una integración no relacionada.

2. Registra el envío y guarda el resultado a nivel de elemento

Envía el registro de seguimiento mediante la operación de registro descrita en la documentación de tu proveedor. Incluye únicamente los campos obligatorios y la información opcional que tenga un propósito definido. Evita enviar nombres de clientes, direcciones u otros datos personales simplemente porque estén disponibles en tu base de datos de pedidos.

El siguiente pseudocódigo ilustra la secuencia de la aplicación. Los nombres de las funciones son ilustrativos; no son endpoints de API ni métodos de SDK.

shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)

result = tracking_adapter.register(shipment)

if result.item_accepted:
    save_registration_result(shipment_id, result)
elif result.outcome_unknown:
    schedule_registration_reconciliation(shipment_id)
else:
    save_registration_error(shipment_id, result)
    route_for_retry_or_correction(result)

Guarda suficiente información para explicar lo ocurrido: el ID interno del envío, la hora de envío, el número de intento, el resultado a nivel de elemento y cualquier referencia de solicitud del proveedor. No dependas únicamente de un registro temporal del proceso. Tus equipos de atención al cliente y operaciones necesitan una respuesta duradera sobre si un envío se registró correctamente.

Gestiona individualmente los envíos por lotes

Si la API admite el registro por lotes, relaciona cada elemento devuelto con su envío original. No marques todo el lote como aceptado porque la solicitud HTTP haya finalizado correctamente. Guarda los elementos aceptados, aísla los rechazados e investiga por separado los resultados ambiguos.

Esto evita que un número de seguimiento mal formado obligue a repetir innecesariamente los registros que ya se procesaron correctamente. También proporciona al personal de operaciones una lista práctica de registros que requieren corrección.

Trata los tiempos de espera como un resultado desconocido

Un tiempo de espera no demuestra que el registro haya fallado. El proveedor podría haber aceptado la solicitud antes de que se interrumpiera la conexión. Utiliza el comportamiento de idempotencia, la gestión de duplicados o las operaciones de consulta documentadas para conciliar el resultado antes de volver a enviarlo a ciegas.

Cuando el comportamiento del proveedor ante duplicados no esté claro, pruébalo con registros controlados y confirma el contrato antes de activar los reintentos automáticos. Deduplicar internamente los trabajos de registro sigue siendo útil, pero no sustituye la comprensión de cómo gestiona el servicio remoto las solicitudes repetidas.

3. Espera a que llegue la primera información de seguimiento

Después de aceptar el registro, es posible que los detalles de seguimiento no estén disponibles de inmediato. Puede existir una etiqueta antes de que el transportista haya registrado un evento físico de manipulación. La falta de información también puede requerir comprobar el número de seguimiento, la selección del transportista o los requisitos de consulta específicos del envío.

Representa esta condición explícitamente. «Registrado; esperando información de seguimiento» es más preciso que «En tránsito» o «Registro fallido». No inventes una estimación de entrega ni un evento de movimiento para llenar una interfaz vacía.

Cuando un registro siga vacío, investiga en este orden práctico:

  1. Confirma que el registro individual fue aceptado.
  2. Compara el número de seguimiento enviado con el registro de cumplimiento.
  3. Comprueba la asignación del transportista y cualquier requisito adicional de consulta documentado.
  4. Comprueba la página de seguimiento del propio transportista para el mismo envío.
  5. Si el transportista tiene eventos pero tu integración no, inspecciona las respuestas de recuperación y contacta con el proveedor de la API proporcionando información de diagnóstico anonimizada.

Evita adoptar un periodo de espera universal sin pruebas. Las reglas de escalamiento deben reflejar el servicio de envío, el proceso de entrega esperado y tus propios compromisos operativos.

4. Recupera los detalles de seguimiento e interprétalos correctamente

Cuando el registro esté disponible, llama a la operación documentada de detalles de seguimiento utilizando los identificadores que requiere. No supongas que el registro y la recuperación aceptan campos idénticos. Algunos contratos de API distinguen entre números de seguimiento, identificadores de transportista y referencias de registro generadas por el proveedor.

Tu aplicación debe distinguir tres capas de información:

  • Resumen del envío: El estado general utilizado en paneles, páginas de pedidos y filtros operativos.
  • Historial de eventos: Las observaciones individuales, incluidas las descripciones de eventos, las marcas de tiempo y las ubicaciones cuando se proporcionen.
  • Metadatos de recuperación: Cuándo recibió o recuperó la información tu aplicación y si la solicitud finalizó correctamente.

Una consulta correcta significa que la operación de recuperación se realizó correctamente. No significa que el paquete se haya movido desde la consulta anterior. Compara la información de seguimiento devuelta con el registro almacenado antes de generar una notificación o un flujo de trabajo posterior.

Mantén separados el momento del evento y el momento de recuperación

Almacena por separado la hora asociada a un evento del transportista y la hora en que tu sistema lo recibió. Un evento recuperado esta tarde puede describir un escaneo anterior. Sustituir su hora de evento por la hora de recuperación haría que una actualización antigua pareciera un movimiento físico nuevo.

Conserva la marca de tiempo original y cualquier desfase proporcionado. Normaliza las marcas de tiempo para compararlas solo cuando se conozca la zona horaria. Si un evento no incluye información de zona horaria, conserva esa incertidumbre en lugar de asignarle silenciosamente la zona horaria de tu servidor.

Conserva el significado original junto al estado normalizado

Un estado normalizado resulta útil para agrupar envíos de distintos transportistas, pero la descripción original del evento puede explicar con mayor precisión un problema operativo. Conserva ambos cuando estén disponibles. Una categoría de excepción general por sí sola puede no indicar a un agente de soporte si la siguiente acción consiste en comprobar una dirección, contactar con el destinatario o esperar otra actualización.

No deduzcas una garantía de entrega, una pérdida confirmada ni un resultado aduanero concreto a partir de un estado impreciso. Escala el caso según la información subyacente y tu política operativa.

5. Mantén los registros actualizados mediante consultas periódicas o webhooks

Recuperar los detalles una sola vez basta para probar la conectividad, pero no para mantener la visibilidad del envío. Tu diseño de producción necesita un mecanismo de actualización. Confirma los mecanismos compatibles con el proveedor elegido y las condiciones asociadas.

Con las consultas periódicas, tu aplicación solicita los detalles de seguimiento según un calendario. Programa las solicitudes dentro de los límites documentados, evita consultar repetidamente registros sin cambios si no hay un motivo y utiliza una espera progresiva para los fallos que admitan reintentos. La apertura de una página de pedido por parte de un cliente no debería activar automáticamente una solicitud ascendente sin restricciones; una vista de seguimiento almacenada puede servir la página mientras un proceso en segundo plano controlado la actualiza.

Si utilizas webhooks, valida las solicitudes entrantes mediante el mecanismo de verificación documentado por el proveedor. Guarda o coloca en una cola duradera los mensajes aceptados antes de confirmarlos de acuerdo con el contrato del webhook y, después, procesa los eventos de forma asíncrona.

Diseña el receptor para tolerar duplicados y un orden de llegada inesperado, salvo que el contrato de entrega documentado garantice lo contrario. Utiliza un identificador de evento del proveedor para la deduplicación cuando esté disponible. De lo contrario, define y prueba una huella basada en campos de evento adecuados, teniendo en cuenta que dicha huella puede requerir ajustes para tus datos.

Una integración basada en webhooks también puede utilizar recuperaciones controladas para la conciliación. Por ejemplo, un trabajo de recuperación puede comprobar los registros afectados por una interrupción del receptor. Este es un patrón de resiliencia, no un permiso para ignorar los límites de frecuencia ni las instrucciones específicas del proveedor.

6. Convierte la información de seguimiento en acciones empresariales seguras

Actualiza el registro interno del envío antes de activar acciones dirigidas al cliente. Conserva un registro duradero de las notificaciones y las transiciones del flujo de trabajo para que un evento repetido no genere mensajes duplicados.

Asocia las acciones empresariales con cambios significativos, no con cada respuesta de la API. Un evento de entrega observado por primera vez puede justificar una notificación de entrega. Una respuesta repetida que contenga el mismo evento no debería hacerlo. Una excepción puede justificar una revisión interna, pero el mensaje al cliente debe reflejar lo que realmente indica el evento.

Define cómo gestionarás los eventos recibidos después de considerar completado un envío. No elimines el historial de eventos ni bloquees permanentemente todas las actualizaciones posteriores simplemente porque un resumen haya alcanzado un estado terminal. Tus reglas de retención, conciliación y notificación deben contemplar correcciones legítimas sin reabrir repetidamente los flujos de trabajo completados.

Aplicación del flujo de trabajo a una integración con 17TRACK

Para una integración de seguimiento personalizada, los puntos de partida relevantes son la página de la API de seguimiento de 17TRACK y su documentación para desarrolladores. Utiliza la página del producto para evaluar la oferta y la documentación para establecer el contrato real de integración. Las páginas de seguimiento para consumidores no sustituyen a las especificaciones de la API.

Antes de escribir tu adaptador, confirma el formato de autenticación, las operaciones de registro y recuperación, las reglas de identificación del transportista, la gestión de respuestas a nivel de elemento y los límites de solicitudes aplicables. Para el procesamiento basado en webhooks, confirma también el esquema de carga útil, el proceso de verificación, los requisitos de confirmación y el comportamiento de los reintentos.

Mantén esos detalles específicos del proveedor dentro de un adaptador en lugar de distribuir por todo tu sistema de pedidos las suposiciones sobre los campos de respuesta. De este modo, el resto de la aplicación puede trabajar con conceptos internos como resultado del registro, estado del envío, historial de eventos y última sincronización correcta.

Comprobaciones previas al lanzamiento que evitan errores costosos

  • Registro aceptado pero vacío: La interfaz muestra que la información de seguimiento está pendiente, no que el paquete esté en movimiento.
  • Resultado de lote mixto: Cada envío recibe su propio resultado persistente.
  • Tiempo de espera después del envío: El proceso concilia el resultado incierto en lugar de asumir un fallo.
  • Evento repetido: La cronología del envío y la notificación al cliente permanecen deduplicadas.
  • Evento antiguo recibido posteriormente: El evento se conserva sin sustituir ciegamente un resumen más reciente.
  • Servicio ascendente no disponible: La página del cliente puede mostrar el último resultado almacenado con una indicación adecuada de su antigüedad.
  • Asignación incorrecta del transportista: El registro puede corregirse mediante un proceso de recuperación documentado.
  • Pedido dividido: Cada paquete conserva su propio estado de seguimiento y su historial de eventos.
  • Exposición de credenciales o carga útil: Los registros contienen referencias de diagnóstico sin filtrar secretos ni información personal innecesaria.

El criterio práctico de finalización no consiste simplemente en recibir una respuesta de registro correcta. Consiste en poder rastrear un paquete desde el envío hasta las actualizaciones, explicar un resultado vacío o fallido y recuperarse de un procesamiento interrumpido sin perder eventos ni duplicar acciones dirigidas al cliente.

Preguntas frecuentes

¿Registrar un número de seguimiento crea un envío?

No en el flujo de trabajo descrito aquí. El registro de seguimiento envía un identificador existente a un servicio de seguimiento. La creación de etiquetas, la compra de franqueo y la reserva con el transportista son operaciones independientes, salvo que una API concreta las combine explícitamente.

¿Por qué los detalles de seguimiento están vacíos después de que el registro se realiza correctamente?

La aceptación del registro y la disponibilidad de los datos de seguimiento son condiciones diferentes. Es posible que el transportista todavía no haya registrado un evento, o que sea necesario comprobar el número de seguimiento, la asignación del transportista o información adicional de consulta. Inspecciona el resultado a nivel de elemento antes de considerar que el registro se realizó correctamente.

¿Debo registrar el envío cada vez que recupero su estado?

No utilices el registro repetido como mecanismo de actualización predeterminado. Guarda el estado de registro aceptado y utiliza el mecanismo documentado de recuperación o actualización. Sigue las reglas explícitas del proveedor para correcciones, reactivaciones o envíos duplicados.

¿Debo utilizar consultas periódicas o webhooks?

Utiliza el mecanismo que se ajuste al contrato documentado de la API y a tus requisitos operativos. Las consultas periódicas requieren un calendario de solicitudes controlado. Los webhooks requieren un receptor seguro y duradero, además de un procesamiento capaz de gestionar duplicados. Cuando sea compatible, combinar actualizaciones mediante webhooks con una conciliación específica puede ofrecer un método práctico de recuperación.

¿Puedo utilizar un número de seguimiento como único identificador de envío de mi base de datos?

Utiliza en su lugar un identificador interno del envío. Guarda el número de seguimiento y el contexto relevante del transportista como atributos de ese registro. Esto facilita la gestión de pedidos divididos, números de seguimiento corregidos y referencias específicas del proveedor sin cambiar la identidad de tu envío interno.

Fuentes

  • API de seguimiento de 17TRACK — punto de entrada oficial del producto para evaluar una integración con la API de 17TRACK.
  • Documentación de la API de 17TRACK — referencia oficial para los formatos de solicitud, las operaciones, las respuestas y los requisitos de integración específicos de la implementación. El pseudocódigo y las sugerencias de campos internos de esta guía son ejemplos de diseño de aplicaciones, no citas de este contrato de API.