Skip to main content
InicioBlogGuíasCómo enviar varios números de seguimiento en una sola solicitud de API (límites de lotes y fallos parciales)

Cómo enviar varios números de seguimiento en una sola solicitud de API (límites de lotes y fallos parciales)

17TRACK

Para enviar varios números de seguimiento en una sola solicitud de API, utiliza un endpoint de Tracking API que acepte explícitamente lotes, formatea cada envío de acuerdo con su esquema de solicitud y divide las listas grandes en lotes dentro de los límites documentados. Después, inspecciona tanto la respuesta HTTP como el resultado de cada envío: una solicitud HTTP exitosa no significa necesariamente que se hayan aceptado todos los números de seguimiento. Reintenta únicamente los fallos elegibles y reconcilia los resultados inciertos antes de volver a enviar un lote completo.

Cómo enviar varios números de seguimiento en una sola solicitud de API

Esta guía está dirigida a desarrolladores que conectan el seguimiento de envíos con un sistema de gestión de pedidos, una plataforma de almacén, una aplicación de comercio electrónico o un panel interno. El objetivo no es simplemente enviar menos solicitudes, sino contabilizar cada envío sin crear trabajo duplicado ni perder registros fallidos.

Primero, identifica qué hace realmente el endpoint de lotes

Una integración de seguimiento puede incluir varias operaciones distintas. Registrar envíos, recuperar su información de seguimiento más reciente y recibir actualizaciones posteriores no son operaciones intercambiables.

  • Registro: Envía los envíos para que el servicio pueda iniciar o mantener su seguimiento.
  • Consulta: Solicita información de seguimiento de los envíos, sujeta a las reglas de recuperación del endpoint.
  • Actualización de entrega: Recibe cambios posteriores mediante un mecanismo compatible, como webhooks, o recupéralos mediante solicitudes programadas.

Consulta la documentación para confirmar la operación exacta que necesitas. Un endpoint de registro que acepta varios registros no demuestra que un endpoint de consulta acepte la misma cantidad, utilice el mismo esquema o comparta el mismo límite de solicitudes.

Para una integración con 17TRACK, comienza por la página del producto Tracking API y utiliza la documentación oficial de la API para confirmar la operación, el método de autenticación, el formato de la solicitud y los campos de respuesta. Considera los ejemplos siguientes como patrones de implementación, no como sustitutos del contrato de esa API.

Los límites de los lotes son más que un número máximo de envíos

No existe un límite universal de lotes para una Tracking API. Los límites pueden variar según el proveedor, el endpoint, la versión de la API y la configuración de la cuenta. Antes de implementar el procesamiento por lotes, registra estas restricciones por separado.

RestricciónQué confirmarConsecuencia para la implementación
Elementos por solicitudNúmero máximo de registros para la operación específicaDivide la lista de entrada antes de enviarla
Tamaño del cuerpo de la solicitudCualquier límite de bytes documentadoTen en cuenta los campos opcionales y el tamaño de serialización
Frecuencia de solicitudesSolicitudes permitidas durante un intervalo definidoRegula las solicitudes mediante un limitador compartido
ConcurrenciaCualquier restricción sobre solicitudes simultáneasLimita el número de trabajadores activos
Contabilización del usoSi el uso se cuenta por solicitud, envío u otra unidadCalcula el consumo por separado del volumen de solicitudes

Por ejemplo, si un endpoint hipotético permite 25 registros por solicitud, 63 registros requieren tres solicitudes con 25, 25 y 13 registros. Estas cifras solo ilustran la división en bloques; no son límites indicados por 17TRACK.

No supongas que el procesamiento por lotes reduce el uso facturable. Puede reducir la sobrecarga de solicitudes HTTP, pero cualquier efecto sobre los cargos depende de las reglas reales de contabilización del proveedor. Del mismo modo, un tamaño de lote válido no autoriza solicitudes paralelas ilimitadas.

Prepara los registros antes de crear la solicitud

La mayoría de los fallos de lotes evitables comienzan con la preparación de los datos de entrada. Valida cada envío antes de añadirlo a un lote, pero evita reglas que rechacen accidentalmente números de seguimiento legítimos de distintos transportistas.

  1. Conserva los números de seguimiento como cadenas. Convertirlos en números puede eliminar ceros iniciales o alterar identificadores largos.
  2. Elimina los espacios en blanco accidentales del principio y del final. No elimines caracteres internos ni cambies las mayúsculas y minúsculas, salvo que la especificación correspondiente permita esa normalización.
  3. Valida los campos obligatorios. Algunos flujos de trabajo pueden requerir un identificador del transportista o información adicional del envío. Utiliza únicamente nombres y valores de campos documentados.
  4. Elige un ámbito de deduplicación explícito. Un número de seguimiento repetido no es automáticamente un duplicado entre todos los transportistas, comerciantes o envíos históricos.
  5. Conserva un identificador local del envío. Almacena la relación entre el elemento enviado y tu registro de pedido o envío, incluso cuando la API no acepte campos de referencia personalizados.

Para el seguimiento de transportistas en varias redes, no infieras el transportista únicamente a partir de la longitud o el prefijo de un número de seguimiento, a menos que dicha inferencia sea fiable para tu flujo de trabajo específico. Cuando la API admita la identificación del transportista, sigue el comportamiento documentado para gestionar ambigüedades.

Estructura ilustrativa de la solicitud

El siguiente JSON muestra el concepto de una carga por lotes. El contenedor, los nombres de las propiedades y los identificadores son ilustrativos, no un esquema de solicitud de 17TRACK. Algunas API esperan un array de nivel superior en lugar de un objeto que contenga un array.

{
  "shipments": [
    {
      "tracking_number": "EXAMPLE000001",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    },
    {
      "tracking_number": "EXAMPLE000002",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    }
  ]
}

Crea la carga mediante un serializador JSON en lugar de concatenar cadenas. Envía las credenciales de autenticación mediante el mecanismo documentado y mantenlas fuera del control de versiones, del código enviado al navegador y de los registros habituales.

Procesa la respuesta en dos niveles

Una solicitud por lotes tiene un resultado a nivel de transporte y otro a nivel de aplicación. Tu integración debe evaluar ambos.

Nivel 1: ¿La solicitud recibió una respuesta utilizable?

Comienza con el estado HTTP, los encabezados de respuesta y el cuerpo de la respuesta. Los errores de autenticación, las solicitudes mal formadas, la limitación de frecuencia y los fallos del servidor pueden impedir el procesamiento normal de los elementos. Un tiempo de espera de red es diferente: es posible que el cliente no sepa si el servidor recibió o procesó la solicitud.

La semántica HTTP está definida en RFC 9110. Sin embargo, la documentación del proveedor determina cómo sus campos de resultado a nivel de aplicación se relacionan con los resultados reales de los envíos.

Nivel 2: ¿Qué ocurrió con cada envío?

Si la respuesta admite resultados a nivel de elemento, clasifica cada registro enviado. No supongas que HTTP 200 significa que todos los registros tuvieron éxito ni que una lista de resultados conserva el orden de la solicitud, salvo que el contrato lo garantice explícitamente.

  • Aceptado: La operación tuvo éxito según la definición documentada del endpoint.
  • Fallo permanente de entrada: Corrige o investiga el registro antes de realizar otro intento.
  • Fallo reintentable: Programa otro intento conforme a las indicaciones de reintento del proveedor.
  • Resultado desconocido: Falta la respuesta, está incompleta o no puede asociarse de forma segura con el registro enviado.

Mantén separadas las respuestas como «ya registrado» o similares relacionadas con duplicados hasta comprender su significado documentado. Pueden indicar que el estado deseado ya existe, pero no deben tratarse automáticamente como confirmación de propiedad, configuración o suscripción exitosa.

Después de procesar una respuesta, cada registro de entrada debe tener exactamente un resultado local. Una comprobación de conciliación útil es: registros enviados = registros aceptados + fallos permanentes + fallos reintentables + resultados desconocidos. Esta es una regla de contabilidad local, no un formato de respuesta de API obligatorio.

Gestiona los fallos parciales sin repetir los registros exitosos

Supón que un lote ilustrativo contiene diez envíos: siete se aceptan, dos tienen campos obligatorios no válidos y uno encuentra un error temporal documentado. Guarda los siete resultados exitosos, envía los dos registros no válidos para su corrección y reintenta únicamente el fallo temporal.

Repetir los diez registros genera tráfico innecesario y puede complicar la gestión de duplicados. También dificulta distinguir un rechazo original de una respuesta posterior relacionada con un duplicado.

ResultadoAcción recomendada
Campo no válido o valor no compatibleCorrige la entrada; no reintentes sin cambios
Fallo de autenticación o permisosPausa el trabajo afectado y corrige las credenciales o el acceso
Respuesta de límite de frecuenciaEspera según las indicaciones documentadas y los encabezados de respuesta aplicables
Error temporal a nivel de elementoReintenta ese elemento con intentos y retroceso limitados
Tiempo de espera agotado después del envíoMárcalo como incierto; reconcilia o utiliza las garantías documentadas de seguridad ante reintentos
Resultado no reconocido o incompletoConserva las pruebas e investiga en lugar de asumir el éxito

HTTP 429 indica demasiadas solicitudes y su respuesta puede incluir un encabezado Retry-After, tal como se describe en RFC 6585. No supongas que ese encabezado siempre está presente. Cuando no se proporcione un retraso explícito para el reintento, utiliza una política de retroceso limitada y coherente con la documentación de la API.

Añade variación aleatoria para distribuir los reintentos entre varios trabajadores, establece un número máximo de intentos o una antigüedad máxima de reintento y envía los registros agotados a una cola de revisión. Reintentar indefinidamente puede ocultar un problema de configuración persistente.

Por qué los tiempos de espera requieren un tratamiento especial

Un tiempo de espera agotado no demuestra un rechazo. Es posible que el servidor haya aceptado el lote antes de que fallara la conexión. Por lo tanto, repetir automáticamente una solicitud que cambia el estado puede repetir el trabajo.

Si el endpoint admite claves de idempotencia documentadas, sigue sus reglas, incluido el ámbito y la conservación de la clave. No inventes un encabezado de idempotencia suponiendo que el servidor lo respeta. De lo contrario, utiliza un flujo de consulta o conciliación compatible para determinar si existe el estado deseado antes de volver a enviar la solicitud. La deduplicación local ayuda a coordinar tus propios trabajadores, pero no garantiza la idempotencia en el servidor.

Un flujo práctico de procesamiento por lotes

Mantén los detalles específicos del proveedor en un adaptador para que la cola, el programador de reintentos y la lógica de supervisión no dependan de nombres de campos de respuesta sin procesar.

validar los registros y conservar los ID locales de los envíos
resolver los duplicados dentro del ámbito empresarial previsto
dividir los registros utilizando los límites documentados de elementos y carga

para cada lote mediante un grupo de trabajadores limitado:
    guardar un registro del intento antes de enviar
    esperar al limitador de frecuencia compartido
    enviar mediante el adaptador específico del proveedor

    si el resultado es incierto:
        poner en cola la conciliación
        continuar

    clasificar los resultados a nivel de solicitud y de elemento
    guardar un resultado para cada registro enviado
    programar para reintento únicamente los fallos elegibles
    enviar los registros no válidos o agotados a revisión

Haz que la persistencia de resultados y la programación de reintentos puedan recuperarse. Por ejemplo, un registro de trabajo duradero o un patrón transaccional de puesta en cola puede evitar que un fallo del proceso provoque la pérdida de la decisión de reintento. Cuando los trabajadores se reinicien, deben poder distinguir el trabajo no enviado del trabajo cuyo resultado remoto aún sea incierto.

Utiliza el tamaño del lote como una configuración ajustable vinculada al endpoint correspondiente, no como una constante dispersa por toda la base de código. Un lote más pequeño puede ser útil al solucionar problemas o aislar registros problemáticos; el lote más grande permitido no es automáticamente el tamaño operativo óptimo.

Supervisa los resultados de los envíos, no solo el tiempo de actividad HTTP

La supervisión de la API debe mostrar si los envíos alcanzan el estado previsto. Un panel que informe únicamente de las tasas de éxito HTTP puede pasar por alto fallos parciales dentro de respuestas que, por lo demás, son exitosas.

  • Tasa de aceptación de elementos: Registros aceptados divididos por registros enviados, con un tratamiento claramente definido de los reintentos.
  • Distribución de fallos: Cantidades por endpoint, código de error documentado y contexto relevante del transportista.
  • Resultados desconocidos: Registros no conciliados y cuánto tiempo llevan sin resolverse.
  • Cola de reintentos: Reintentos pendientes, antigüedad del reintento más antiguo e intentos agotados.
  • Estado de las solicitudes: Latencia, tiempos de espera, limitación de frecuencia y errores del servidor.
  • Frescura del seguimiento: Si los envíos aceptados reciben posteriormente información de seguimiento utilizable.

La aceptación del registro no demuestra que exista un nuevo escaneo del transportista. Mantén separado el estado del procesamiento de la API del movimiento del envío y de la frescura de los datos para que un incidente de integración no se confunda con un retraso en la entrega.

Registra los ID locales de los lotes, las referencias de los envíos, el número de intentos, los códigos de error documentados y los ID de solicitud del proveedor cuando estén disponibles. Oculta las credenciales y la información personal innecesaria. Utiliza los identificadores de seguimiento únicamente cuando sea necesario desde el punto de vista operativo y evita colocar identificadores de envío sin procesar en etiquetas de métricas de alta cardinalidad.

Prueba estos casos antes de pasar a producción

Utiliza un entorno sandbox documentado o un entorno de pruebas controlado cuando esté disponible. No supongas que los números de seguimiento inventados producirán respuestas predecibles en producción.

  1. Envía un lote válido con el límite de elementos documentado y, después, prueba cómo tu cliente impide un lote demasiado grande.
  2. Verifica que los números de seguimiento con ceros iniciales sobrevivan a la serialización y el almacenamiento.
  3. Prueba elementos aceptados y rechazados mezclados sin reintentar los registros exitosos.
  4. Simula la limitación de frecuencia y confirma que varios trabajadores respeten el mismo límite.
  5. Simula un tiempo de espera agotado después del envío y verifica la ruta de conciliación.
  6. Reinicia un trabajador entre la recepción de la respuesta y la persistencia local.
  7. Prueba resultados de elementos ausentes, desconocidos o imposibles de asociar.
  8. Confirma que los registros no válidos lleguen a una cola de corrección visible en lugar de reintentarse indefinidamente.

Una integración lista para producción puede explicar el estado de cada envío enviado, incluidos aquellos cuyo resultado sea temporalmente desconocido. Reducir el número de solicitudes es útil; conservar esa responsabilidad es el objetivo de diseño más importante.

Preguntas frecuentes

¿Cuántos números de seguimiento puedo enviar en una sola solicitud?

Utiliza el límite documentado para el endpoint y la versión exactos de la API. Comprueba también el tamaño de la solicitud, los límites de frecuencia y cualquier restricción específica de la cuenta. No existe una cifra universal segura que pueda aplicarse a todas las API de seguimiento ni a todas las operaciones de una misma API.

¿Puede un número de seguimiento no válido hacer que falle todo el lote?

Sí, según las reglas de validación del endpoint. Algunas API devuelven rechazos individuales, mientras que otras pueden rechazar una solicitud antes de procesar los elementos. Comprueba tanto los errores a nivel de solicitud como los resultados a nivel de elemento; no supongas que todos los endpoints de lotes admiten aceptación parcial.

¿Debo reintentar un lote cuando la respuesta HTTP es exitosa?

No automáticamente. Primero analiza el estado documentado a nivel de aplicación y los resultados de los elementos. Guarda los registros exitosos y reintenta únicamente los fallos elegibles. Si el resultado no puede interpretarse de forma segura, clasifícalo como incierto e investiga.

¿Puedo mezclar transportistas en el mismo lote?

Solo cuando el endpoint admita esa estructura de solicitud. Confirma si la información del transportista se proporciona por envío, si se admite la identificación automática y qué ocurre cuando la identificación es ambigua. Un servicio de varios transportistas no establece por sí mismo las reglas de lotes de cada endpoint.

¿El procesamiento por lotes hace que las actualizaciones de seguimiento lleguen más rápido?

El procesamiento por lotes puede reducir el número de solicitudes que envía tu aplicación, pero por sí solo no hace que los eventos del transportista aparezcan antes. El registro, la recuperación de datos, la disponibilidad de los escaneos del transportista y la entrega de actualizaciones son partes separadas del flujo de trabajo.

Fuentes