1. Что такое отслеживание логистики

Отслеживание логистики — это важный инструмент для мониторинга процесса транспортировки, позволяющий пользователям отслеживать маршруты транспортировки, исключения и основные изменения статуса.

Основные функции API отслеживания включают:

• Автоматический мониторинг: после регистрации номера отслеживания он отслеживается автоматически с отправкой результатов запроса без использования дополнительных квот. Примечание: эта функция работает    

• асинхронно и не подходит для интерфейсных веб-страниц, мини-программ или приложений.

  翻译结

• Емкость корпоративного уровня: API отслеживания предлагает возможности обработки данных корпоративного уровня, позволяя регистрировать 400 000 номеров отслеживания в час.
• Лучшие практики управления данными: настоятельно рекомендуется хранить логистическую информацию на вашем сервере или в службе хранения.
• Уникальная идентификация данных: каждый фрагмент данных уникально идентифицируется с помощью комбинации номера отслеживания + оператора.
• Обзор операционного процесса: операционный процесс включает подписку на отправку > периодическое отслеживание > проверку изменений статуса отправки > отправку результатов.

2. Перед использованием

2.1 Создайте учетную запись 17TRACK

Учетные записи API не привязаны к среде. Рекомендуется поддерживать отдельные учетные записи API для тестовых и производственных сред, чтобы обеспечить специфичные для среды конфигурации и целостность данных. Пожалуйста, посетите 17TRACK-Api, чтобы открыть учетную запись.

 

2.2 Номер отслеживания и код перевозчика

• Посетите 17TRACK, чтобы проверить доступность подготовленного номера отслеживания
• Посетите Carriers, чтобы проверить поддерживаемых перевозчиков
• Что такое код перевозчика? Код перевозчика — это спецификация параметра, разработанная специально для использования с API отслеживания. Дополнительную информацию можно найти на сайте Carrier Code. Например, код перевозчика для USPS — 21051.

3. Руководство по интеграции

3.1 Интеграция сторонних систем

Целевой пользователь

Следующее руководство по интеграции предназначено специально для ведущих поставщиков логистических услуг, торговцев, поставщиков услуг и поставщиков систем, которые имеют собственные фирменные системы и команды разработчиков ИТ.

Шаг 1

(Для быстрого теста вы можете проверить отправку через https://webhook.site)

1. Убедитесь, что ваш сервер доступен из публичной сети для получения обновлений отслеживания. Для этого может потребоваться настройка конфигураций брандмауэра и шлюза, чтобы разрешить входящие соединения с серверов 17TRACK.
2. Разработайте интерфейс, который может получать информацию об отслеживании, и убедитесь, что он может обрабатывать несколько одновременных запросов. Рекомендуется распределять данные с помощью независимых служб, таких как очереди или кэши, для улучшения масштабируемости.
3. Внедрите проверку подписи в интерфейсе получения информации, чтобы подтвердить подлинность и целостность данных, полученных от 17TRACK. См. раздел Проверка подписи для получения инструкций. Пример кода приведен ниже:

/**
* 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();
}

 

Шаг 2

1. Получите ключ API, войдя в систему и посетив страницу настроек API в Api-Settings.
2. Чтобы настроить интерфейс для получения данных, войдите в систему и перейдите на страницу настроек API в Api-settings. Затем введите URL-адрес интерфейса в разделе WebHook.

Шаг 3

1. Вызовите интерфейс регистрации (/register), чтобы подписаться на номера отслеживания. Рекомендуется передавать идентификатор данных в бизнес-системе через тег, чтобы облегчить будущее использование результатов push-уведомлений. (Ссылка на интерфейс: Register Tracking Number)

Шаг 4

1. Überwachen Sie den Betrieb der Informationsabrufschnittstelle. Um sicherzustellen, dass die Tracking-Ergebnisse von der Unternehmensseite effektiv und zeitnah genutzt werden, beachten Sie bitte, dass Daten kontinuierlich in parallelen Zuständen gesendet werden können, wobei jede Push-Benachrichtigung den vollständigen Datensatz enthält. Wenn der normale Empfang fehlschlägt und ein anderer temporärer Statuscode als 200 zurückgegeben wird, stellt 17TRACK kompensierende Push-Benachrichtigungen bereit, wie hier beschrieben: Funktionsweise von Push-Benachrichtigungen
   
   Wenn keine Tracking-Ergebnisse gefunden werden können, kann dies folgende Gründe haben:
   • Das Tracking läuft. (Unter normalen Umständen sollten die ersten Tracking-Ergebnisse innerhalb von 1 Minute verfügbar sein, wobei das nachfolgende Tracking bis zur Zustellung 3 bis 4 Mal alle 24 Stunden durchgeführt wird.)
   • Falsche Tracking-Nummer. Rufen Sie in diesem Fall die Schnittstelle zum Löschen von Trackings (/deletetrack) auf und abonnieren Sie dann erneut.
   • Falscher Spediteur. Rufen Sie in diesem Fall die Schnittstelle zum Ändern von Spediteuren (/changecarrier) auf, um den Spediteur zu aktualisieren.
   • Eine Anomalie in der Schnittstelle des Spediteurs.
   • Spediteure haben die Tracking-Daten nicht aktualisiert.
   • Zusätzliche Tracking-Parameter fehlen. Beim Abonnieren müssen für bestimmte Spediteure zusätzliche Tracking-Parameter angegeben werden, z. B. Handynummern und Postleitzahlen.
   • Spediteure haben ihre Daten 30 Tage in Folge nicht aktualisiert. In diesem Fall stoppt 17TRACK das Tracking automatisch.

3.2 Integration von Drittsystemen

Zielbenutzer

Die folgende Integrationsanleitung richtet sich an kleine bis mittelgroße Logistikanbieter und mittelgroße Händler, die ERP-, TMS-, WMS- und CRM-Systeme von Drittanbietern nutzen

Schritt 1

(Wenn auch nur für einen schnellen Test, können Sie das Pushen über https://webhook.site überprüfen)

1. Bitte bestätigen Sie mit dem Systemanbieter, ob das aktuelle System den Empfang von Push-Tracking-Daten über die Webhook-Methode unterstützt. [Unterschiedlich zu selbst entwickelten Systemen]
2. Bitte bestätigen Sie mit dem Systemanbieter, ob eine alternative Lösung verfügbar ist, falls Push nicht unterstützt wird: Rufen Sie die gettrackinfo-Schnittstelle (/gettrackinfo) auf, um die Daten in regelmäßigen Abständen abzurufen. (Hinweis: Diese Methode kann nicht die gleiche Effizienz bei der Datenrückgabe wie die Push-Methode garantieren und wird von 17TRACK auch nicht empfohlen.) [Unterschiedlich zu selbst entwickelten Systemen]
3. Bitte bestätigen Sie mit dem Systemanbieter, ob der 17TRACK-API-Zugriff unterstützt wird. Wenn dies unterstützt wird, bestätigen Sie, ob die aktuelle integrierte Version den Geschäftsanforderungen entspricht. Wenn nicht, verhandeln Sie bitte mit dem Systemanbieter, um eine andere Version zu integrieren. [Unterschiedlich zu selbst entwickelten Systemen]
4. Wenn Push unterstützt wird, vervollständigen Sie die Signaturüberprüfungslogik in der Informationsempfangsschnittstelle, um sicherzustellen, dass die Informationsquelle sicher und gültig ist. Bitte lesen Sie „Überprüfen der Signatur“, Beispielcode ist wie folgt:

/**
* 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();
}

Schritt 2

1. API-Schlüssel abrufen: Melden Sie sich bei der API-Konsole an, rufen Sie den Schlüssel auf der Seite „Einstellungen“ ab und geben Sie ihn an den für die Integration zuständigen Systemanbieter weiter. (Siehe API-Einstellungen)
2. Überspringen Sie diesen Schritt, wenn der Systemanbieter die Push-Methode nicht unterstützt. Wenn dies der Fall ist, wenden Sie sich an den Systemanbieter, um die URL der Push-Schnittstelle anzugeben. (Siehe API-Einstellungen)

Schritt 3

1. Rufen Sie die Registrierungsschnittstelle (/register) auf, um Trackingnummern zu abonnieren. Es wird empfohlen, dass der Systemanbieter die Daten-ID im Geschäftssystem über ein Tag weitergibt, um die zukünftige Verwendung von Push-Ergebnissen zu erleichtern. (Schnittstellenreferenz: Trackingnummer registrieren)

Schritt 4

1. Melden Sie sich bitte bei dem von Ihnen verwendeten System an und überprüfen Sie die Ergebnisse im Tracking-Modul. Wenden Sie sich bei Bedarf an den Kundendienst des Systemanbieters, um Hilfe und Antworten zu erhalten.
2. Überwachen Sie den Vorgang der Schnittstelle zum Empfangen von Informationen. Um sicherzustellen, dass die Tracking-Ergebnisse zeitnah und effektiv vom Unternehmen genutzt werden, beachten Sie bitte: Daten können kontinuierlich in gleichzeitigen Zuständen gepusht werden, wobei jeder Push den vollständigen Datensatz enthält. In Fällen, in denen der normale Empfang fehlschlägt und ein temporärer Statuscode ungleich 200 zurückgegeben wird, bietet 17TRACK kompensierende Pushes, wie hier beschrieben: Wie funktioniert der Push?

Если результаты отслеживания не могут быть найдены, это может быть связано со следующими сценариями:

• Отслеживание выполняется. (При нормальных обстоятельствах первоначальные результаты отслеживания должны быть доступны в течение 1 минуты, а последующее отслеживание выполняется 3–4 раза каждые 24 часа до доставки.)
• Неправильный номер отслеживания. В этом случае вызовите интерфейс удаления трека (/deletetrack), а затем повторно подпишитесь.
• Неправильный оператор. В этом случае вызовите интерфейс смены оператора (/changecarrier), чтобы обновить оператора.
• Неисправность в интерфейсе оператора.
• Операторы не обновили данные отслеживания.
• Отсутствуют дополнительные параметры отслеживания. При подписке необходимо включить дополнительные параметры отслеживания для определенных операторов, такие как номера мобильных телефонов и почтовые индексы.
• Операторы не обновляли свои данные в течение 30 последовательных дней. В этом случае 17TRACK автоматически прекратит отслеживание.

4. Версии

Основные версии

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

Подверсии

v2.1 (обновлено в августе 2023 г.):

1. Добавлено 3 подсостояния оформления.
2. Добавлен узел статуса события.
3. Интерфейс регистрации поддерживает параметры номера заказа и примечания.
4. Добавлен номер заказа, ограничение по времени и другая информация в интерфейс gettracklist.

v2.2 (обновлено в октябре 2023 г.):

1. Включена структура необработанной информации для определения времени логистического события.