Skip to main content
InicioBlogGuíasCómo validar los números de seguimiento antes de enviarlos a la API: 7 reglas que debes seguir

Cómo validar los números de seguimiento antes de enviarlos a la API: 7 reglas que debes seguir

17TRACK

Valide un número de seguimiento por capas antes de enviarlo a una API de seguimiento: normalice la entrada, compruebe su estructura básica, confirme el contexto del transportista, aplique una suma de comprobación solo cuando el transportista documente una, y rechace los valores claramente inseguros o incompletos. No dependa de una única expresión regular universal. Los formatos de los números de seguimiento varían según el transportista, el servicio, el país y el tipo de envío, por lo que un validador eficaz debe evitar solicitudes incorrectas sin bloquear números legítimos que utilicen un formato desconocido.

Cómo validar números de seguimiento antes de enviarlos a una API: 7 reglas

Esta guía está dirigida a desarrolladores y equipos de operaciones que integran el seguimiento de envíos en un sistema de gestión de pedidos, un flujo de trabajo de almacén, un portal de clientes o una aplicación de comercio electrónico. El objetivo no es demostrar que un paquete existe antes del envío. La validación sintáctica y la validación del estado del envío son pasos independientes.

Qué puede confirmar la validación y qué no

Un validador previo al envío puede identificar problemas comunes de entrada, como un valor vacío, espacios accidentales, caracteres no compatibles, una longitud excesiva o un número de seguimiento colocado en el campo equivocado. También puede identificar un transportista probable cuando este se conoce y el formato está documentado.

Normalmente no puede confirmar que un número pertenezca a un envío real, que el transportista haya aceptado el paquete o que el número pueda rastrearse actualmente. Esas cuestiones requieren una consulta al transportista o a la plataforma de seguimiento. Un número puede superar una comprobación de formato y aun así no haber sido utilizado, contener un error tipográfico sutil, haber caducado o estar asociado a un servicio diferente.

Las siete reglas

1. Normalice el valor sin cambiar su significado

Los usuarios y los sistemas ascendentes suelen añadir espacios iniciales o finales, saltos de línea, espacios de no separación o caracteres de formato. Normalice estos elementos de forma segura antes de la validación. Un primer paso habitual es eliminar los espacios en blanco circundantes y convertir los espacios no imprimibles en espacios ordinarios. Si el formato documentado por el transportista permite espacios internos o guiones, decida si debe eliminarlos para la solicitud a la API o conservar el valor original para su visualización y auditoría.

Cuando sea práctico, conserve dos valores: la entrada original y un valor canónico. El original ayuda a los equipos de soporte a investigar problemas de calidad de datos; el valor canónico se utiliza para la validación y el envío. Evite transformaciones que puedan alterar los identificadores. No convierta automáticamente letras en números, sustituya caracteres ambiguos ni elimine todos los signos de puntuación a menos que la documentación del transportista o de la API correspondiente admita explícitamente ese comportamiento.

El tratamiento de Unicode requiere atención. Un carácter visualmente similar de otro alfabeto puede no ser aceptado por una API aunque parezca una letra o un dígito ASCII. Restringir el valor canónico al conjunto de caracteres permitido por la integración seleccionada puede evitar errores posteriores confusos.

2. Rechace los valores que no superen las comprobaciones estructurales básicas

Antes de aplicar la lógica específica del transportista, compruebe si el valor está presente y es plausible. Entre las comprobaciones útiles se incluyen la longitud mínima y máxima, las clases de caracteres permitidas y si el valor contiene únicamente espacios en blanco o un marcador como “N/A”, “TBD” o “test”. Los límites exactos deben proceder del contrato de la API o de la documentación del transportista. Evite inventar un máximo universal simplemente porque la mayoría de los ejemplos son cortos.

Una comprobación estructural debe ser deliberadamente conservadora. Por ejemplo, una regla que permita solo dígitos rechazará identificadores alfanuméricos válidos. Una regla que exija una longitud fija puede rechazar variantes de servicio o formatos internacionales. Utilice comprobaciones genéricas para detectar errores evidentes y, después, aplique comprobaciones más específicas solo cuando se conozcan el transportista y el servicio.

Valide también el tipo de dato en el límite de la aplicación. Un número de seguimiento normalmente debe tratarse como una cadena, no como un entero. La conversión numérica puede eliminar ceros iniciales y causar problemas de precisión en sistemas que utilizan tipos numéricos de ancho fijo. Conserve el valor exactamente como una cadena después de la normalización aprobada.

3. Utilice el contexto del transportista en lugar de adivinar solo a partir del número

Un número de seguimiento sin transportista es una entrada ambigua. Distintos transportistas pueden utilizar longitudes, prefijos o conjuntos de caracteres coincidentes, y un formato que parece plausible para un transportista puede ser inválido para otro. Si el pedido, la etiqueta, el sistema de almacén o la cuenta del comerciante ya identifica al transportista, envíe ese contexto junto con el número de seguimiento siempre que la API lo admita.

El contexto del transportista mejora tanto la validación como el enrutamiento. Permite que la aplicación seleccione las reglas de formato pertinentes, reduce las coincidencias falsas y hace que los mensajes de error sean más útiles. También evita que un resultado de detección automática se trate como un hecho cuando varios transportistas podrían aceptar un valor de apariencia similar.

Si se desconoce el transportista, utilice un enfoque en dos etapas. Primero, ejecute comprobaciones genéricas de seguridad. Después, envíe el valor únicamente mediante un flujo de API que admita explícitamente la detección del transportista, o colóquelo en una cola de revisión cuando el proceso empresarial requiera un transportista confirmado. No asigne silenciosamente un transportista basándose solo en un prefijo, a menos que esa relación se mantenga y esté documentada.

4. Aplique sumas de comprobación solo cuando la regla esté documentada

Algunos sistemas de identificadores utilizan dígitos de control, pero los números de seguimiento no se rigen por un estándar universal de suma de comprobación. Una suma de comprobación puede detectar ciertos errores de transcripción, pero no demuestra que exista un envío. Más importante aún, aplicar el algoritmo de suma de comprobación incorrecto puede rechazar números válidos.

Implemente una suma de comprobación solo cuando el transportista, el servicio, la especificación de la etiqueta o la documentación de la API correspondiente defina el algoritmo y la parte de entrada que cubre. Registre la versión de la regla y pruébela con ejemplos oficiales. Si no existe una regla autorizada, omita la suma de comprobación en lugar de adivinar a partir de patrones observados en una muestra pequeña.

Considere el resultado de la suma de comprobación como una señal, no como una decisión de validación completa. Un fallo puede justificar el bloqueo de un envío cuando la regla es oficial. Un resultado correcto debe hacer avanzar el valor a la siguiente etapa, no marcarlo como un envío activo.

5. Separe la validación del formato de la elegibilidad para la API

Un valor puede estar bien formado y aun así no ser adecuado para el endpoint al que llama. Antes del envío, consulte la documentación de la API para conocer los campos obligatorios, los identificadores de transportista aceptados, los requisitos de autenticación, los límites de solicitudes, el comportamiento ante duplicados y cualquier restricción sobre tipos de servicio o destinos. Estas son reglas de integración, no reglas del número de seguimiento, pero determinan si un identificador válido puede procesarse correctamente.

La documentación de la API de seguimiento de 17TRACK es un ejemplo de por qué importa esta distinción: los desarrolladores deben seguir el modelo de solicitudes de la plataforma y el comportamiento de integración compatible, en lugar de inventar una solicitud basándose en el aspecto de un número de seguimiento. Consulte la documentación actual sobre los requisitos de los endpoints y el tratamiento de respuestas en documentación de la API de 17TRACK.

Mantenga separados los errores de validación de los errores de transporte y autenticación. “Formato de número de seguimiento no válido”, “transportista desconocido”, “límite de solicitudes alcanzado” y “autorización fallida” requieren acciones diferentes. Un único mensaje genérico de “fallo en el envío” hace que los reintentos y los informes operativos sean menos fiables.

6. Proteja la API con entradas limitadas, deduplicación y reintentos seguros

La validación también es una medida de protección operativa. Imponga una longitud máxima de entrada antes de analizar o registrar los datos. Rechace caracteres de control y estructuras de carga inesperadas. Aplique límites de frecuencia en el límite de su propia aplicación para que una importación defectuosa no genere un pico incontrolado de solicitudes.

Elimine duplicados antes del envío cuando el proceso empresarial no requiera registros repetidos. Una clave de deduplicación útil puede incluir el número de seguimiento canónico, el transportista, la cuenta y el contexto del envío. La clave correcta depende de su flujo de trabajo; el mismo identificador puede reutilizarse a veces en diferentes servicios o registros empresariales, por lo que no debe asumir que el número por sí solo siempre es único globalmente.

Utilice reintentos limitados con retroceso para fallos temporales y evite reintentar errores de validación permanentes. Almacene un registro de idempotencia o de envío cuando la API y su arquitectura lo permitan. Registre suficiente información para solucionar problemas de la solicitud, pero proteja las credenciales, los datos de los clientes y cualquier detalle confidencial del envío. Un validador debe reducir los fallos repetidos, no crear un segundo problema de seguridad mediante un registro excesivo.

7. Confirme el resultado después del envío y supervise los falsos positivos

La regla final es tratar la validación previa al envío como una puerta, no como un veredicto. Después de aceptar la solicitud, revise la respuesta de la API y conserve su estado, el identificador de solicitud, la asociación del transportista y cualquier código de error documentado. Si la plataforma acepta la solicitud pero todavía no puede devolver eventos de movimiento, esto puede indicar un retraso de procesamiento y no un número inválido.

Defina una política de seguimiento para los números que permanezcan sin resolver. El plazo debe reflejar el transportista, el servicio, el origen del envío y su política de atención al cliente; no existe un periodo universal que demuestre que un número es inválido. Escale los registros con transportista ausente, errores repetidos del proveedor, resultados contradictorios del transportista o un estado que no coincida con el registro del pedido.

Mida los rechazos y aceptaciones incorrectos. Una expresión regular estricta puede reducir los envíos mal formados y, al mismo tiempo, bloquear por error envíos legítimos. Un validador permisivo puede aumentar las solicitudes aceptadas, pero generar ruido posteriormente. Revise muestras fallidas por transportista y servicio, actualice las reglas documentadas mediante control de versiones y pruebe los cambios con un conjunto representativo de datos de prueba que proteja la privacidad.

Secuencia práctica de validación

Una implementación fácil de mantener puede utilizar la siguiente secuencia:

  1. Compruebe que la solicitud contiene un valor de cadena y un registro empresarial válido.
  2. Guarde la entrada original y, a continuación, cree una forma canónica documentada.
  3. Rechace valores vacíos, marcadores, caracteres inseguros y valores fuera del intervalo de longitud documentado.
  4. Resuelva el transportista a partir de datos fiables del pedido o utilice un flujo de detección admitido explícitamente.
  5. Aplique reglas de sintaxis y suma de comprobación específicas del transportista solo cuando la documentación autorizada las respalde.
  6. Compruebe los requisitos del endpoint, el estado de duplicación y la elegibilidad para reintentos.
  7. Envíe la solicitud, clasifique la respuesta, almacene el resultado y programe el seguimiento de los registros sin resolver.

Esta secuencia facilita las pruebas del validador porque cada decisión tiene un motivo diferente. También proporciona a los equipos de operaciones categorías de fallo accionables en lugar de un único error opaco.

Lista de comprobación de implementación

  • Almacene los números de seguimiento como cadenas para conservar los ceros iniciales.
  • Conserve por separado los valores originales y canónicos cuando la auditabilidad sea importante.
  • Mantenga las reglas del transportista como configuración con control de versiones, no como condiciones codificadas dispersas.
  • Pruebe letras, dígitos, guiones, espacios en blanco, caracteres Unicode parecidos, marcadores y longitudes límite.
  • Utilice el contexto fiable del transportista siempre que esté disponible.
  • No infiera la existencia de un envío a partir de una coincidencia exitosa con una expresión regular.
  • Clasifique los errores de validación permanentes por separado de los errores temporales de la API o de la red.
  • Revise la documentación del proveedor antes de cambiar las reglas de formato o la lógica de solicitudes.

Preguntas frecuentes

¿Puede una expresión regular validar un número de seguimiento?

Puede validar un patrón limitado cuando se conocen el transportista y el formato del servicio. No puede demostrar que el número exista, pertenezca a un envío concreto o esté activo actualmente. Es probable que una expresión universal genere rechazos o coincidencias incorrectos.

¿Debe enviarse a la API un número que parece inválido?

Los valores claramente vacíos, inseguros o estructuralmente imposibles normalmente deben detenerse antes del envío. Un formato desconocido pero seguro no debe rechazarse únicamente porque no coincida con una suposición interna. Consulte primero la documentación del transportista o utilice un proceso de detección compatible.

¿Es suficiente una suma de comprobación para confirmar un envío?

No. Una suma de comprobación, cuando corresponde, solo comprueba si el valor satisface una regla matemática. No confirma que un transportista haya emitido el número ni que el paquete haya entrado en la red.

¿Qué debe ocurrir cuando se desconoce el transportista?

Ejecute comprobaciones genéricas de seguridad y utilice un flujo de API que admita explícitamente la detección del transportista, si está disponible. De lo contrario, conserve el registro para enriquecerlo o revisarlo manualmente en lugar de adivinar silenciosamente el transportista.

¿Cómo deben gestionarse los errores de la API?

Clasifíquelos según la causa. Corrija las entradas mal formadas y los valores de transportista no compatibles; reintente los fallos temporales de red o del proveedor con límites y retroceso; y dirija los errores de autenticación o cuota al responsable de la integración. Almacene los detalles de respuesta necesarios para el diagnóstico sin exponer secretos.

Fuentes