Cómo registrar un número de seguimiento mediante la API: campos de solicitud, códigos de transportista y respuestas
Para registrar un número de seguimiento mediante API, envía una solicitud de registro autenticada que contenga el número de seguimiento del envío y, cuando sea necesario, un identificador del transportista. Luego, revisa la respuesta de cada envío enviado —no solo el estado HTTP— y guarda si el registro se realizó correctamente, falló o sigue siendo incierto. El registro inicia el flujo de seguimiento; no demuestra que el transportista haya escaneado el paquete ni que los eventos de seguimiento ya estén disponibles.
Esta guía está dirigida a desarrolladores que conectan un sistema de gestión de pedidos, una aplicación de almacén o una plataforma de comercio electrónico con una API de seguimiento. Utiliza 17TRACK como ejemplo concreto de integración y explica qué detalles deben comprobarse en la documentación de la versión de API seleccionada.
Qué hace el registro y qué no hace
Una solicitud de registro indica a un servicio de seguimiento qué envío deseas rastrear. Es diferente de comprar una etiqueta de envío, reservar una recogida o pedir a un transportista que cree un envío. En una integración típica, el flujo de envío genera primero un número de seguimiento y tu aplicación registra ese número después.
Mantén estos tres eventos separados en tu aplicación:
- Envío creado: tu sistema de envíos ha asignado un número de seguimiento.
- Registro aceptado: el servicio de seguimiento ha aceptado el envío para realizar su seguimiento.
- Información de seguimiento recibida: los eventos del transportista están disponibles a través del servicio de seguimiento.
No actualices un pedido a “en tránsito” simplemente porque el registro se realizó correctamente. Es posible que una etiqueta recién creada aún no tenga un escaneo físico de aceptación. El estado del envío visible para el cliente debe proceder de eventos de seguimiento interpretados mediante tus reglas de asignación de estados, no de la respuesta de registro.
Para las integraciones con 17TRACK, comienza por la descripción general de Tracking API y utiliza la documentación oficial de la API como referencia autorizada para endpoints, definiciones de campos, autenticación y códigos de respuesta. Los ejemplos siguientes se centran en el registro, no en las tareas independientes de recuperar resultados o recibir actualizaciones.
Prepara los campos de la solicitud antes de escribir la llamada a la API
La preparación más útil consiste en definir un pequeño contrato de campos entre tu sistema de envíos y tu integración de seguimiento. Decide de dónde procede cada valor, si puede faltar y cómo se validará.
| Campo o valor | Finalidad | Regla de implementación |
|---|---|---|
| Número de seguimiento | Identifica el envío que se debe rastrear. | Almacénalo y transmítelo como una cadena; conserva los ceros iniciales. |
| Identificador del transportista | Identifica al transportista dentro del sistema del proveedor de seguimiento. | Utiliza el identificador documentado por el proveedor, no un código interno del almacén. |
| Referencia interna | Relaciona el registro con tu registro de envío. | Utiliza un campo de referencia compatible si está disponible; conserva tu propia correspondencia en la base de datos independientemente de ello. |
| Datos de identificación adicionales | Pueden ayudar a identificar un envío cuando un transportista requiere más que su número de seguimiento. | Envía únicamente los campos documentados para esa integración y ese transportista. |
| Credencial de API | Autentica la cuenta que realiza la llamada. | Consérvala en el servidor y exclúyela de los registros de la aplicación. |
Trata el número de seguimiento como un identificador
Nunca conviertas un número de seguimiento en un entero. La conversión numérica puede eliminar los ceros iniciales y los valores grandes pueden perder precisión en algunos entornos de programación. Elimina los espacios en blanco accidentales al principio y al final, pero no quites signos de puntuación ni cambies las mayúsculas y minúsculas, salvo que la documentación correspondiente o el formato del transportista permitan esa normalización.
Valida los errores de entrada evidentes antes de llamar a la API: cadenas vacías, saltos de línea inesperados y un número de pedido copiado en el campo del número de seguimiento. Evita imponer una única regla universal de longitud o caracteres para todos los transportistas. Una regla que funciona para un transportista puede rechazar números válidos de otro.
Mantén separadas las referencias de pedido y las identidades de los envíos
Un pedido puede tener varios paquetes y un envío de reemplazo puede introducir otro número de seguimiento. Modela el registro a nivel de envío o paquete en lugar de asumir que cada pedido tiene un único número de seguimiento.
Si utilizas una etiqueta o un campo de referencia compatible con el proveedor, es preferible una referencia de envío opaca a la dirección de correo electrónico o postal del cliente. Tu propia base de datos debe seguir siendo la conexión autorizada entre pedidos, envíos, números de seguimiento y asignaciones de transportistas.
Elige el código de transportista correcto
Un código de transportista no es necesariamente un identificador universal del sector. El valor reconocido por una plataforma de seguimiento puede diferir del nombre del transportista almacenado en tu software de envíos. Incluso dos sistemas que utilizan códigos numéricos pueden asignar números distintos al mismo transportista.
Mantén una asignación explícita entre tu servicio de envíos y el identificador de transportista del proveedor de seguimiento. Cuando sea necesario, distingue la operación regional o el servicio de un transportista de su marca general. Una asignación basada únicamente en un nombre visible puede resultar ambigua cuando los sistemas de envío utilizan alias.
- Cuando se conoce el transportista: utiliza el identificador documentado cuando sea compatible, especialmente cuando se superponen los formatos de los números de seguimiento.
- Cuando se desconoce el transportista: utiliza la detección automática únicamente mediante el mecanismo documentado. No supongas que omitir el valor, una cadena vacía, cero y null significan lo mismo.
- Cuando el resultado parece incorrecto: verifica la etiqueta original, el servicio de envío y la asignación antes de registrar repetidamente el mismo número.
La detección automática es útil, pero no demuestra que un transportista concreto tenga físicamente el envío. Del mismo modo, un código de transportista válido no garantiza que el número de seguimiento proporcionado pertenezca a ese transportista.
Mantén las asignaciones de transportistas configurables en lugar de distribuirlas por el código de la aplicación. Registra cuándo se comprobó una asignación por última vez e incluye un envío conocido en las pruebas de regresión cada vez que la modifiques.
Ejemplo: enviar una solicitud de registro a 17TRACK
El siguiente ejemplo ilustra el endpoint de registro de 17TRACK v2.2, el encabezado de autenticación 17token y una matriz que contiene un objeto de número de seguimiento. Confirma que esta versión y sus requisitos de solicitud coincidan con tu cuenta y con la documentación oficial antes de implementarla. El número de seguimiento es un marcador de posición y debe sustituirse por un identificador de envío real.
curl --request POST \
--url 'https://api.17track.net/track/v2.2/register' \
--header "17token: ${TRACKING_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data '[
{
"number": "YOUR_TRACKING_NUMBER"
}
]'
Este ejemplo mínimo no muestra la selección del transportista ni los campos complementarios específicos de cada transportista. Consulta la documentación de registro para determinar cómo funciona la detección cuando se omite el campo del transportista y si tu envío necesita información adicional. Si proporcionas un transportista, utiliza el campo carrier documentado y el identificador esperado por esa versión de la API.
Ejecuta esta solicitud desde un entorno del lado del servidor. No incluyas el token en una tienda pública, un script del navegador o una aplicación móvil distribuida a los clientes. Una variable de entorno resulta práctica para un ejemplo local; las implementaciones de producción deben utilizar los controles de gestión de secretos de tu organización.
Antes de aumentar el volumen, prueba un envío conocido y revisa la respuesta completa. Después, prueba una entrada no válida y un lote que contenga elementos válidos y no válidos. Estas comprobaciones muestran si tu integración gestiona realmente los resultados a nivel de elemento, en lugar de limitarse a reconocer una respuesta HTTP correcta.
Lee la respuesta en tres niveles
Un gestor de respuestas fiable responde a tres preguntas independientes: ¿la solicitud llegó al servicio?, ¿el servicio aceptó la operación? y ¿qué ocurrió con cada envío?
1. Resultado HTTP y de transporte
Un tiempo de espera de conexión, un fallo de TLS o una respuesta interrumpida no indican necesariamente si el servidor procesó la solicitud. Marca ese resultado como incierto hasta poder reconciliarlo. Un estado HTTP correcto confirma un intercambio HTTP satisfactorio, pero aún debes revisar la respuesta de la aplicación.
2. Resultado a nivel de solicitud
Revisa el resultado principal y los campos de error documentados de la API. Los errores de autenticación, el JSON mal formado y las restricciones de la cuenta requieren acciones diferentes. Guarda el código y el mensaje de error originales del proveedor en lugar de reducir todos los fallos a “seguimiento no disponible”.
No supongas que un código numérico de la aplicación tiene el mismo significado que un código de estado HTTP. Sus significados proceden de capas diferentes y deben interpretarse por separado.
3. Resultado a nivel de envío
En el registro por lotes, ten en cuenta cada elemento enviado. Una respuesta puede distinguir entre envíos aceptados y rechazados; tu analizador debe seguir el esquema exacto documentado para la versión seleccionada. No marques todo el lote como registrado simplemente porque un elemento se haya procesado correctamente.
Normaliza las respuestas del proveedor en estados estables propios de tu aplicación. Por ejemplo, tu base de datos podría utilizar accepted, rejected y uncertain. Estos son estados internos sugeridos, no valores literales de respuesta de 17TRACK. Conserva la respuesta original del proveedor conforme a una política adecuada de retención y acceso para que los desarrolladores puedan investigar las discrepancias.
Un registro de registro útil contiene el ID interno del envío, el número enviado, la selección del transportista, la hora del intento, la versión de la API, el resultado y los detalles del error del proveedor. Mantén separado el estado del registro del estado de entrega.
Gestiona los reintentos sin crear un bucle interminable
La política de reintentos debe depender del fallo, no simplemente de si se produjo una excepción.
- Entrada no válida: corrige el campo antes de volver a intentarlo. Repetir una solicitud mal formada sin cambios probablemente no ayudará.
- Fallo de autenticación: verifica las credenciales y la configuración de la cuenta. Evita enviar repetidamente el mismo lote fallido.
- Límite de velocidad: respeta los límites documentados y las instrucciones de reintento aplicables. Utiliza un retroceso limitado en lugar de reintentos paralelos inmediatos.
- Fallo temporal del servicio: reintenta dentro de un presupuesto definido de intentos y tiempo.
- Tiempo de espera después del envío: reconcilia el estado de registro del envío mediante el comportamiento documentado de la API antes de asumir que el primer intento falló.
- Respuesta relacionada con duplicados: comprueba si el envío ya está registrado y asociado correctamente con el registro de tu aplicación.
No supongas que el registro es idempotente a menos que la documentación defina ese comportamiento. La deduplicación en el lado de la aplicación reduce los envíos repetidos accidentales, pero no establece la política del proveedor para gestionar duplicados.
Utiliza una regla de unicidad interna adecuada para tu modelo de envíos. El número de seguimiento por sí solo puede no ser una clave permanente suficiente entre transportistas y durante largos periodos de retención. Conserva el contexto del transportista y tu propio identificador de envío, y documenta cómo se gestionan los reemplazos y los números corregidos.
Supervisa el registro por separado de las actualizaciones de seguimiento
La supervisión de la API debe distinguir un fallo de integración de un envío que simplemente no tiene un nuevo evento del transportista. Estas condiciones requieren responsables y soluciones diferentes.
Para el registro, supervisa los recuentos de aceptaciones y rechazos, las categorías de errores, los resultados inciertos, la cola de reintentos y la latencia de respuesta. Para el seguimiento posterior, supervisa por separado la recepción de actualizaciones o los fallos de recuperación. Evita asignar umbrales numéricos de alerta hasta comprender el tráfico normal y los límites operativos documentados del proveedor.
Una comprobación práctica de producción debe responder:
- ¿Tiene un registro de registro cada envío pendiente de seguimiento?
- ¿Puede rastrearse cada registro aceptado hasta el paquete correcto?
- ¿Se envían los elementos rechazados a alguien que pueda corregir los datos subyacentes?
- ¿Se reconcilian las solicitudes inciertas en lugar de abandonarlas o reintentarlas indefinidamente?
- ¿Se derivan los estados visibles para el cliente de los eventos del envío y no de la aceptación del registro?
- ¿Se excluyen de los registros las credenciales y la información personal innecesaria?
En las operaciones de comercio electrónico, la transferencia operativa es tan importante como la llamada a la API. Los desarrolladores deben encargarse de los fallos de transporte y análisis; los equipos de envíos o preparación deben poder investigar etiquetas incorrectas, asignaciones de transportistas e información de envío ausente.
Preguntas frecuentes
¿Puedo registrar un número de seguimiento antes del primer escaneo del transportista?
El registro y los escaneos del transportista son eventos independientes. Un servicio puede aceptar un número antes de que haya eventos de seguimiento disponibles, sujeto a sus reglas de validación. No interpretes la aceptación como una prueba de que el transportista ha recibido el paquete.
¿Siempre tengo que proporcionar un código de transportista?
Depende del comportamiento de detección documentado por la API y del envío en cuestión. Si se conoce el transportista, un identificador explícito y correctamente asignado puede reducir la ambigüedad. Si se desconoce, utiliza el método documentado de detección automática en lugar de inventar un valor de transportista.
¿Por qué la API devolvió un éxito HTTP mientras el envío falló?
La solicitud HTTP puede completarse correctamente mientras la aplicación rechaza un elemento individual. Lee el resultado principal de la aplicación y los resultados a nivel de envío. Esta distinción es especialmente importante para las solicitudes por lotes.
¿Qué debo hacer cuando una solicitud de registro agota el tiempo de espera?
Trata el resultado como incierto. Es posible que el servidor haya procesado la solicitud antes de que fallara la conexión. Comprueba el comportamiento documentado del proveedor respecto a duplicados y los métodos disponibles de consulta de registro o seguimiento; después, reconcilia o reintenta conforme a una política limitada.
¿El registro configura automáticamente las notificaciones de seguimiento?
No lo supongas. El registro, la recuperación del seguimiento y la configuración de webhooks son aspectos independientes de la integración. Verifica la documentación pertinente y prueba el flujo completo de actualizaciones antes de depender de él para las notificaciones al cliente.
Fuentes
- Documentación de la API de 17TRACK — referencia para endpoints de registro, autenticación, campos de solicitud, identificadores de transportistas, esquemas de respuesta y gestión de errores. Ajusta los detalles de implementación a la versión de la API que implementes.
- Descripción general de Tracking API de 17TRACK — punto de partida oficial para el producto de API de seguimiento y los recursos de integración para desarrolladores.


