1. 物流追跡とは

物流追跡は輸送プロセスを監視するための重要なツールであり、ユーザーは輸送ルート、例外、および主要なステータスの変更を追跡できます。

追跡 API の主な機能は次のとおりです。

• 自動監視: 追跡番号が登録されると、自動的に監視され、追加のクォータを消費することなくクエリ結果がプッシュされます。注: この機能は非同期で動作し、フロントエンドの Web ページ、ミニプログラム、またはアプリには適していません。
• エンタープライズ レベルの容量: 追跡 API はエンタープライズ レベルのデータ処理機能を提供し、1 時間あたり 400,000 件の追跡番号を登録できます。
• グローバル キャリア統合: 追跡 API は 2,000 を超えるグローバル キャリアとの統合をサポートし、統一された呼び出し方法、応答構造、およびステータス ノードを提供し、開発コストを効果的に削減します。
• データ管理のベスト プラクティス: 物流情報はサーバーまたはストレージ サービスに保存することを強くお勧めします。
• 一意のデータ識別: 各データは、追跡番号 + キャリアの組み合わせによって一意に識別されます。
• 運用プロセスの概要: 運用プロセスには、出荷サブスクリプション > 定期追跡 > 出荷ステータス変更の検査 > 結果のプッシュが含まれます。

2. 使用する前に

2.1 17TR​​ACK アカウントを作成する

API アカウントは環境固有ではありません。環境固有の構成とデータの整合性を確保するために、テスト環境と本番環境で別々の API アカウントを維持することをお勧めします。アカウントを開設するには、17TRACK-Api にアクセスしてください。

 

2.2 追跡番号と運送業者コード

• 17TRACK にアクセスして、用意した追跡番号が利用可能かどうかを確認してください
• 運送業者にアクセスして、サポートされている運送業者を確認してください
• 運送業者コードとは何ですか? 運送業者コードは、追跡 API で使用するために特別に開発されたパラメータ仕様です。詳細については、運送業者コードを参照してください。たとえば、USPS の運送業者コードは 21051 です。

3. 統合ガイド

3.1 サードパーティ以外のシステムとの統合

対象ユーザー

以下の統合ガイドは、独自のシステムと IT 開発チームを持つ大手物流プロバイダー、販売業者、サービス プロバイダー、システム プロバイダー向けです。

ステップ 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-Settings の API 設定ページにアクセスし、API キーを取得します。
2. データ受信用のインターフェイスを設定するには、ログインして Api-settings の API 設定ページに移動します。次に、WebHook セクションにインターフェイス URL を入力します。

ステップ 3

1. 追跡番号を登録するには、登録インターフェイス (/register) を呼び出します。プッシュ結果を将来使用しやすくするために、ビジネス システムのデータ ID をタグ経由で渡すことをお勧めします。(インターフェイス参照: 追跡番号の登録)

ステップ 4

• 情報受信インターフェースの動作を監視します。追跡結果がビジネス側で効果的かつタイムリーに使用されるようにするには、データが同時状態で継続的にプッシュされ、各プッシュに完全なデータセットが含まれる可能性があることに注意してください。通常の受信が失敗し、一時的に 200 以外のステータス コードが返された場合、17TRACK は補償プッシュを提供します。詳細については、プッシュの仕組みをご覧ください。
  追跡結果が見つからない場合は、次のシナリオが原因の可能性があります:

追跡結果が見つからない場合は、次のシナリオが原因の可能性があります:

clear

追跡が進行中です。(通常の状況では、最初の追跡結果は 1 分以内に利用可能になり、その後の追跡は配達まで 24 時間ごとに 3 ～ 4 回実行されます。)

    追跡番号が間違っています。この場合、追跡削除インターフェイス (/deletetrack) を呼び出して、再度登録してください。

運送業者が間違っています。この場合、運送業者変更インターフェイス (/changecarrier) を呼び出して、運送業者を更新してください。
運送業者のインターフェイスに異常があります。
運送業者が追跡データを更新していません。
追加の追跡パラメータがありません。登録時に、携帯電話番号や郵便番号など、特定の運送業者の追加追跡パラメータを含める必要があります。
運送業者が 30 日間連続してデータを更新していません。この場合、17TRACK は自動的に追跡を停止します。

翻译结

3.2 サードパーティシステムの統合

対象ユーザー

以下の統合ガイドは、サードパーティの ERP、TMS、WMS、CRM システムを利用する中小規模の物流業者および中規模商人向けに設計されています

ステップ 1

(簡単なテストのみの場合は、https://webhook.site でプッシュを確認できます)

1. 現在のシステムが Webhook 方式によるプッシュ追跡データの受信をサポートしているかどうか、システムプロバイダーに確認してください。[自社開発システムとは異なります]
2. プッシュがサポートされていない場合に代替ソリューションを利用できるかどうか、システムプロバイダーに確認してください。gettrackinfo インターフェイス (/gettrackinfo) を呼び出して、定期的にデータを取得します。(注: この方法では、プッシュ方式と同じデータ返送効率を保証することはできません。また、17TRACK では推奨されていません。) [自社開発システムとは異なります]
3. 17TRACK API アクセスがサポートされているかどうか、システムプロバイダーに確認してください。サポートされている場合は、現在の統合バージョンがビジネス要件を満たしているかどうかを確認してください。そうでない場合は、システムプロバイダーと交渉して別のバージョンを統合してください。 [自社開発システムとの違い]
4. プッシュがサポートされている場合は、情報受信インターフェースで署名検証ロジックを完了し、情報ソースが安全で有効であることを確認します。署名の検証を参照してください。サンプルコードは次のとおりです。

/**
* 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. システム プロバイダーがプッシュ メソッドをサポートしていない場合は、この手順をスキップします。サポートしている場合は、システム プロバイダーに連絡してプッシュ インターフェイス URL を提供します。(Api-Settings を参照)

ステップ 3

1. 登録インターフェイス (/register) を呼び出して追跡番号をサブスクライブします。システム プロバイダーは、ビジネス システムのデータ ID をタグ経由で渡すことをお勧めします。これにより、プッシュ結果の今後の使用が容易になります。(インターフェイス参照: 追跡番号の登録)

ステップ 4

1. 使用しているシステムにログインし、追跡モジュールで結果を確認してください。必要に応じて、システム プロバイダーのカスタマー サービスに支援と回答を求めてください。
2. 情報受信インターフェイスの操作を監視します。追跡結果がビジネス エンドによってタイムリーかつ効果的に利用されるようにするには、次の点に注意してください。データは同時状態で継続的にプッシュされ、各プッシュには完全なデータセットが含まれる場合があります。通常の受信が失敗し、一時的に 200 以外のステータス コードが返された場合、17TRACK は補償プッシュを提供します。詳細については、プッシュの仕組みを参照してください。

追跡結果が見つからない場合は、次のシナリオが原因の可能性があります:

• 追跡が進行中です。(通常の状況では、最初の追跡結果は 1 分以内に利用可能になり、その後の追跡は配達まで 24 時間ごとに 3 ～ 4 回実行されます。)
• 追跡番号が間違っています。この場合、追跡削除インターフェイス (/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 年 8 月更新):

1. 3 つのクリアランス サブ状態を追加しました。
2. イベント ステータス ノードを追加しました。
3. 登録インターフェイスは、注文番号とメモ パラメータをサポートします。
4. gettracklist インターフェイスに注文番号、時間制限、その他の情報を追加しました。

v2.2 (2023 年 10 月更新):

1. 物流イベントのタイミングに関する生の情報構造を組み込みました。