1. ¿Qué es el seguimiento logístico?

El seguimiento logístico es una herramienta fundamental para supervisar el proceso de transporte, ya que permite a los usuarios realizar un seguimiento de las rutas de transporte, las excepciones y los cambios de estado importantes.

Las principales características de la API de seguimiento incluyen:

• Monitoreo automático: una vez que se registra un número de seguimiento, se monitorea automáticamente y los resultados de la consulta se envían sin consumir cuotas adicionales. Nota: esta función funciona de manera asincrónica y no es adecuada para páginas web front-end, miniprogramas o aplicaciones.
• Capacidad a nivel empresarial: la API de seguimiento ofrece capacidades de procesamiento de datos a nivel empresarial, lo que permite el registro de 400 000 números de seguimiento por hora.
• Integración de transportistas globales: la API de seguimiento admite la integración con más de 2000 transportistas globales, lo que proporciona métodos de llamada unificados, estructuras de respuesta y nodos de estado, lo que reduce de manera efectiva los costos de desarrollo.
• Mejores prácticas de administración de datos: se recomienda enfáticamente almacenar la información logística en su servidor o servicio de almacenamiento.
• Identificación única de datos: cada pieza de datos se identifica de manera única a través de la combinación de número de seguimiento + transportista.
• Descripción general del proceso operativo: el proceso operativo incluye suscripción de envío > seguimiento periódico > examen de cambios de estado de envío > envío de resultados.

2. Antes de usar

2.1 Crear una cuenta 17TRACK

Las cuentas API no son específicas de cada entorno. Se recomienda mantener cuentas API separadas para los entornos de prueba y producción para garantizar la integridad de los datos y las configuraciones específicas del entorno. Visite 17TRACK-Api para abrir una cuenta.

 

2.2 Número de seguimiento y código de transportista

• Visite 17TRACK para verificar la disponibilidad del número de seguimiento preparado
• Visite Transportistas para consultar los transportistas admitidos
• ¿Qué es un código de transportista? El código de transportista es una especificación de parámetros desarrollada específicamente para su uso con la API de seguimiento. Puede encontrar más información en Código de transportista. Por ejemplo, el código de transportista para USPS es 21051.

3. Guía de integración

3.1 Integración de sistemas que no sean de terceros

Usuario de destino

La siguiente guía de integración está destinada específicamente a los principales proveedores de logística, comerciantes, proveedores de servicios y proveedores de sistemas que cuentan con sus propios sistemas patentados y equipos de desarrollo de TI.

Paso 1

(Para una prueba rápida, puede verificar el envío a través de https://webhook.site)

1. Asegúrese de que su servidor sea accesible desde la red pública para recibir actualizaciones de seguimiento. Esto puede requerir ajustar las configuraciones de su firewall y puerta de enlace para permitir conexiones entrantes desde los servidores de 17TRACK.
2. Desarrolle una interfaz que pueda recibir información de seguimiento y asegúrese de que pueda manejar múltiples solicitudes simultáneas. Es recomendable distribuir datos mediante servicios independientes, como colas o cachés, para mejorar la escalabilidad.
3. Implemente la verificación de firma en su interfaz de recepción de información para confirmar la autenticidad e integridad de los datos recibidos de 17TRACK. Consulte Verificar la firma para obtener orientación. A continuación, se proporciona un código de muestra:

/**
* requestText {String} The notification message
* key      {String} The security key
* return    {String} The signature returned
*/
private String getGeneratedSignature(String requestText, String key) throws NoSuchAlgorithmException {

    String src = requestText + "/" + key;

    MessageDigest md = MessageDigest.getInstance("SHA-256");
    byte[] hash = md.digest(src.getBytes(StandardCharsets.UTF_8));

    BigInteger number = new BigInteger(1, hash);
    StringBuilder hexString = new StringBuilder(number.toString(16));
    while (hexString.length() < 64) {
        hexString.insert(0, '0');
    }
    return hexString.toString();
}

 

Paso 2

1. Obtenga la clave API iniciando sesión y visitando la página de configuración de API en Api-Settings.
2. Para configurar la interfaz para recibir datos, inicie sesión y vaya a la página de configuración de API en Api-settings. Luego, ingrese la URL de la interfaz en la sección WebHook.

Paso 3

1. Llame a la interfaz de registro (/register) para suscribirse a los números de seguimiento. Se recomienda pasar el ID de datos en el sistema empresarial a través de una etiqueta para facilitar el uso futuro de los resultados de envío. (Referencia de interfaz: Registrar número de seguimiento)

Paso 4

1. Supervise el funcionamiento de la interfaz de recepción de información. Para garantizar que los resultados de seguimiento se utilicen de manera eficaz y oportuna por parte del extremo empresarial, tenga en cuenta que los datos pueden enviarse continuamente en estados concurrentes, y cada envío contiene el conjunto de datos completo. Si la recepción normal falla y se devuelve un código de estado temporal distinto de 200, 17TRACK proporciona envíos compensatorios, como se detalla aquí: ¿cómo funciona el envío?
   
   Si no se pueden encontrar los resultados del seguimiento, puede deberse a las siguientes situaciones:
   • El seguimiento está en curso. (En circunstancias normales, los resultados iniciales del seguimiento deberían estar disponibles en 1 minuto, y los seguimientos posteriores se realizan de 3 a 4 veces cada 24 horas hasta la entrega).
   • Número de seguimiento incorrecto. En este caso, llame a la interfaz Eliminar seguimiento (/deletetrack) y luego vuelva a suscribirse.
   • Transportista incorrecto. En este caso, llame a la interfaz Cambiar transportista (/changecarrier) para actualizar el transportista.
   • Una anomalía en la interfaz del transportista.
   • Los transportistas no han actualizado los datos de seguimiento.
   • Faltan parámetros de seguimiento adicionales. Al suscribirse, es necesario incluir parámetros de seguimiento adicionales para ciertos transportistas, como números de teléfono celular y códigos postales.
   • Los transportistas no han actualizado sus datos durante 30 días consecutivos. En este caso, 17TRACK detendrá automáticamente el seguimiento.

3.2 Integración de sistemas de terceros

Usuario de destino

La siguiente guía de integración está diseñada para proveedores de logística de tamaño pequeño a mediano y comerciantes de tamaño mediano que utilizan sistemas ERP, TMS, WMS y CRM de terceros

Paso 1

(Si solo es para una prueba rápida, puede verificar el envío a través de https://webhook.site)

1. Confirme con el proveedor del sistema si el sistema actual admite la recepción de datos de seguimiento push a través del método Webhook. [Diferente de los sistemas desarrollados por uno mismo]
2. Confirme con el proveedor del sistema si hay una solución alternativa disponible en caso de que no se admita el método push: llame a la interfaz gettrackinfo (/gettrackinfo) para recuperar los datos a intervalos regulares. (Nota: este método no puede garantizar la misma eficiencia de retorno de datos que el método push y tampoco lo recomienda 17TRACK). [Diferente de los sistemas desarrollados por uno mismo]
3. Confirme con el proveedor del sistema si se admite el acceso a la API de 17TRACK. Si se admite, confirme si la versión integrada actual cumple con las demandas comerciales. Si no es así, negocie con el proveedor del sistema para integrar otra versión. [Diferente de los sistemas desarrollados por uno mismo]
4. Si se admite el método push, complete la lógica de verificación de firma en la interfaz de recepción de información para garantizar que la fuente de información sea segura y válida. Consulte Verificar la firma; el código de ejemplo es el siguiente:

/**
* requestText {String} The notification message
* key      {String} The security key
* return    {String} The signature returned
*/
private String getGeneratedSignature(String requestText, String key) throws NoSuchAlgorithmException {

   String src = requestText + "/" + key;

   MessageDigest md = MessageDigest.getInstance("SHA-256");
   byte[] hash = md.digest(src.getBytes(StandardCharsets.UTF_8));

   BigInteger number = new BigInteger(1, hash);
   StringBuilder hexString = new StringBuilder(number.toString(16));
   while (hexString.length() < 64) {
       hexString.insert(0, '0');
   }
   return hexString.toString();
}

Paso 2

1. Obtener la clave de API: inicie sesión en la consola de API, obtenga la clave en la página de configuración y proporciónela al proveedor del sistema responsable de la integración. (Consulte Configuración de API)
2. Omita este paso si el proveedor del sistema no admite el método push. Si lo hace, comuníquese con el proveedor del sistema para proporcionarle la URL de la interfaz push. (Consulte Configuración de API)

Paso 3

1. Llame a la interfaz de registro (/register) para suscribirse a los números de seguimiento. Se recomienda que el proveedor del sistema pase la identificación de los datos en el sistema empresarial a través de una etiqueta para facilitar el uso futuro de los resultados de envío. (Referencia de la interfaz: Registrar número de seguimiento)

Paso 4

•  Inicie sesión en el sistema que está utilizando y revise los resultados en el módulo de seguimiento. Si es necesario, solicite asistencia y respuestas al servicio de atención al cliente del proveedor del sistema.
  Supervise el funcionamiento de la interfaz de recepción de información. Para garantizar que los resultados de seguimiento se utilicen de manera oportuna y eficaz por parte del extremo empresarial, tenga en cuenta que los datos pueden enviarse continuamente en estados concurrentes, y cada envío contendrá el conjunto de datos completo. En los casos en que la recepción normal falla y se devuelve un código de estado temporal distinto de 200, 17TRACK proporciona envíos compensatorios, como se detalla aquí: ¿cómo funciona el envío?

Si no se pueden encontrar los resultados del seguimiento, puede deberse a las siguientes situaciones:

• El seguimiento está en curso. (En circunstancias normales, los resultados iniciales del seguimiento deberían estar disponibles en 1 minuto, y los seguimientos posteriores se realizan de 3 a 4 veces cada 24 horas hasta la entrega).
• Número de seguimiento incorrecto. En este caso, llame a la interfaz Eliminar seguimiento (/deletetrack) y luego vuelva a suscribirse.
• Transportista incorrecto. En este caso, llame a la interfaz Cambiar transportista (/changecarrier) para actualizar el transportista.
• Una anomalía en la interfaz del transportista.
• Los transportistas no han actualizado los datos de seguimiento.
• Faltan parámetros de seguimiento adicionales. Al suscribirse, es necesario incluir parámetros de seguimiento adicionales para ciertos transportistas, como números de teléfono celular y códigos postales.
• Los transportistas no han actualizado sus datos durante 30 días consecutivos. En este caso, 17TRACK detendrá automáticamente el seguimiento.

4. Versiones

Versiones principales

Difference	V1.0	V2.0 (May 2022)
Request Address	https://api.17track.net/track/v1	https://api.17track.net/track/v2
Registration interface (/register) simplifies auto-recognition operations	{ carrier : null , auto_detection : true }	{ carrier : null }
Simplified signature verification	TRACKING_STOPPED/ {"number":"RM101474005CN", "carrier":3011,"tag":""} /6A8D7CFC3F7A41149E0A4EE8ABD0DD8A	{"event":"TRACKING_UPDATED", "data":{"number":"RR123456789CN", "carrier":3011,"tag":null}} /123456ABCDEF
Response structuring + node semantics	Not supported	Supported
Independent query additional parameters	Used in conjunction with a tracking number	Independent parameter
Origin and Destination	Not supported	Supported
Timeliness information	Not supported	Supported
Status	7 status	9 main status, 27 sub-status
Attachment Information	Not supported	Weight, volume, etc. (if supported by the carrier).
Carrier information	Not supported	Name, alias, official phone number, official website, etc.
Translation of events	Not supported	8 languages supported

Subversiones

v2.1 (actualizada en agosto de 2023):

1. Se agregaron 3 subestados de autorización.
2. Se agregó un nodo de estado de evento.
3. La interfaz de registro admite parámetros de nota y número de pedido.
4. Se agregó número de pedido, límite de tiempo y otra información a la interfaz gettracklist.

v2.2 (actualizada en octubre de 2023):

1. Se incorporó la estructura de información sin procesar para el cronograma del evento logístico.