API送信前に追跡番号を検証する方法:従うべき7つのルール
追跡APIに送信する前に、追跡番号を段階的に検証します。入力を正規化し、基本構造を確認し、配送業者のコンテキストを確認し、配送業者の文書でチェックサムが定義されている場合に限って適用し、明らかに安全でない値や不完全な値を拒否します。単一の汎用正規表現に依存しないでください。追跡番号の形式は配送業者、サービス、国、出荷タイプによって異なるため、効果的なバリデーターは不正なリクエストを防ぎつつ、未知の形式を使用する正当な番号をブロックしないようにする必要があります。
このガイドは、注文管理システム、倉庫ワークフロー、カスタマーポータル、またはEコマースアプリケーションに配送追跡を統合する開発者と運用チームを対象としています。目的は、送信前に荷物の存在を証明することではありません。構文検証と配送状況の検証は別々の手順です。
検証で確認できること、確認できないこと
送信前のバリデーターは、空の値、誤って含まれたスペース、サポートされていない文字、過度に長い値、追跡番号が誤ったフィールドに入力されている場合など、一般的な入力上の問題を特定できます。また、配送業者が既知で形式が文書化されている場合は、該当する可能性の高い配送業者を特定できることもあります。
通常、番号が実在する出荷に属していること、荷物が配送業者に受け付けられたこと、または現在追跡可能であることまでは確認できません。これらの確認には、配送業者または追跡プラットフォームへの照会が必要です。形式チェックに合格しても、未使用であったり、気付きにくい誤入力があったり、期限切れであったり、別のサービスに関連付けられていたりする可能性があります。
7つのルール
1. 意味を変えずに値を正規化する
ユーザーや上流システムによって、先頭または末尾のスペース、改行、ノーブレークスペース、書式設定用の文字が追加されることがあります。検証前に、これらを安全に正規化してください。一般的な最初の手順は、周囲の空白を削除し、印字されない空白を通常のスペースに変換することです。配送業者の文書化された形式で内部スペースやハイフンが許可されている場合は、APIリクエスト用に削除するのか、表示および監査用に元の値を保持するのかを決めます。
可能な場合は、2つの値を保持してください。元の入力値と正規形です。元の値は、サポートチームがデータ品質の問題を調査するのに役立ちます。正規形は検証と送信に使用します。識別子を変更する可能性のある変換は避けてください。関連する配送業者またはAPIのドキュメントで明示的にサポートされていない限り、文字を数字に自動変換したり、曖昧な文字を置き換えたり、すべての句読点を削除したりしないでください。
Unicodeの処理にも注意が必要です。別のアルファベットに属する、見た目が似た文字は、ASCIIの英字や数字のように見えてもAPIで受け付けられない場合があります。選択した統合で許可されている文字セットに正規形の値を制限すると、下流で発生する分かりにくいエラーを防止できます。
2. 基本的な構造チェックに失敗する値を拒否する
配送業者固有のロジックを適用する前に、値が存在し、妥当そうであるかを確認します。役立つチェックには、最小・最大長、許可される文字クラス、値が空白だけで構成されていないか、「N/A」、「TBD」、「test」などのプレースホルダーでないかの確認が含まれます。正確な制限値は、API契約または配送業者のドキュメントに基づく必要があります。ほとんどの例が短いという理由だけで、汎用的な最大長を勝手に設定しないでください。
構造チェックは意図的に保守的に行う必要があります。たとえば、数字だけを許可するルールは、有効な英数字の識別子を拒否します。固定長を要求するルールは、サービスのバリエーションや国際形式を拒否する可能性があります。一般的なチェックで明らかなエラーを検出し、配送業者とサービスが判明している場合にのみ、より具体的なチェックを適用してください。
また、アプリケーション境界でデータ型を検証してください。追跡番号は通常、整数ではなく文字列として扱う必要があります。数値に変換すると先頭のゼロが失われる可能性があり、固定幅の数値型を使用するシステムでは精度の問題が発生することがあります。承認済みの正規化後も、値は文字列として正確に保持してください。
3. 番号だけで推測せず、配送業者のコンテキストを使用する
配送業者のない追跡番号は曖昧な入力です。配送業者によって長さ、接頭辞、文字セットが重複することがあり、ある配送業者では妥当そうな形式でも、別の配送業者では無効な場合があります。注文、ラベル、倉庫システム、または加盟店アカウントですでに配送業者が特定されている場合は、APIが対応している限り、そのコンテキストを追跡番号とともに渡してください。
配送業者のコンテキストにより、検証とルーティングの両方が改善されます。関連する形式ルールを選択でき、誤検出を減らし、より有用なエラーメッセージを表示できます。また、複数の配送業者が似た値を受け付けられる場合に、自動検出の結果を事実として扱うことも防げます。
配送業者が不明な場合は、2段階の方法を使用します。まず、一般的な安全チェックを実行します。次に、配送業者検出に明示的に対応するAPIフローを通じてのみ値を送信するか、業務プロセスで配送業者の確認が必要な場合はレビューキューに入れます。接頭辞だけに基づいて配送業者を黙って割り当てないでください。ただし、その対応関係が維持管理され、文書化されている場合を除きます。
4. ルールが文書化されている場合にのみチェックサムを適用する
一部の識別子システムではチェックディジットが使用されますが、追跡番号を統一的に管理するチェックサム標準はありません。チェックサムによって特定の転記ミスを検出できる場合がありますが、出荷の存在を証明するものではありません。さらに、誤ったチェックサムアルゴリズムを適用すると、有効な番号を拒否する可能性があります。
関連する配送業者、サービス、ラベル仕様、またはAPIドキュメントでアルゴリズムと対象となる入力部分が定義されている場合にのみ、チェックサムを実装してください。ルールのバージョンを記録し、公式の例でテストします。信頼できるルールがない場合は、少数のサンプルから推測せず、チェックサムを省略してください。
チェックサムの結果は、完全な検証判断ではなく、1つのシグナルとして扱います。ルールが正式なものである場合、チェック失敗を送信ブロックの根拠にできます。チェックに合格しても、値を次の段階に進めるだけであり、実際に稼働中の出荷と判断してはいけません。
5. 形式検証とAPI利用資格を分離する
値の形式が正しくても、呼び出しているエンドポイントには適さない場合があります。送信前に、APIドキュメントで必須フィールド、受け付けられる配送業者識別子、認証要件、リクエスト制限、重複処理、サービス種別や配送先に関する制限を確認してください。これらは追跡番号のルールではなく統合ルールですが、有効な識別子を正常に処理できるかどうかを決定します。
17TRACK Tracking APIのドキュメントは、この区別が重要である理由の一例です。開発者は、追跡番号の見た目からリクエストを推測するのではなく、プラットフォームのリクエストモデルとサポートされている統合動作に従う必要があります。エンドポイント要件とレスポンス処理については、最新の17TRACK APIドキュメントを参照してください。
検証エラーを、通信エラーや認証エラーとは分けてください。「追跡番号の形式が無効」、「配送業者が不明」、「レート制限に達した」、「認証に失敗した」では、必要な対応が異なります。単一の「送信に失敗しました」という汎用メッセージでは、再試行と運用レポートの信頼性が低下します。
6. 入力の上限、重複排除、安全な再試行でAPIを保護する
検証は運用上の安全対策でもあります。解析やログ記録の前に、入力長に上限を設けます。制御文字や予期しないペイロード構造を拒否します。障害のあるインポートによって制御不能なリクエストの急増が起きないよう、独自のアプリケーション境界でレート制限を適用してください。
業務プロセスで登録の繰り返しが必要ない場合は、送信前に重複を排除します。重複排除キーには、正規化された追跡番号、配送業者、アカウント、出荷コンテキストを含めることができます。適切なキーはワークフローによって異なります。同じ識別子が異なるサービスや業務レコードで再利用される場合もあるため、番号だけが常にグローバルに一意だとは考えないでください。
一時的な障害には、バックオフを伴う上限付き再試行を使用し、恒久的な検証エラーは再試行しないでください。APIとアーキテクチャが対応している場合は、べき等性キーまたは送信記録を保存します。リクエストのトラブルシューティングに十分な情報をログに記録しますが、認証情報、顧客データ、機密性の高い出荷情報を保護してください。バリデーターは繰り返し発生する障害を減らすべきであり、過剰なログ記録によって新たなセキュリティ問題を生み出してはいけません。
7. 送信後に結果を確認し、誤検出を監視する
最後のルールは、送信前の検証を判定ではなくゲートとして扱うことです。リクエストが受け付けられた後、APIレスポンスを確認し、そのステータス、リクエスト識別子、配送業者との関連付け、文書化されたエラーコードを保存します。プラットフォームがリクエストを受け付けても、まだ移動イベントを返せない場合、それは番号が無効なのではなく、処理の遅延を示している可能性があります。
未解決のまま残る番号について、フォローアップ方針を定義します。期間は配送業者、サービス、出荷元、カスタマーサービス方針を反映させる必要があり、番号が無効であることを証明する普遍的な期間はありません。配送業者が欠落している記録、プロバイダーエラーが繰り返される記録、配送業者の結果が一致しない記録、注文レコードと一致しないステータスをエスカレーションします。
誤った拒否と誤った受け入れを測定します。厳格な正規表現は不正な送信を減らす一方で、正当な出荷を誤ってブロックする可能性があります。寛容なバリデーターは受け付けるリクエストを増やせますが、下流にノイズを生じさせる可能性があります。配送業者とサービス別に失敗サンプルを確認し、文書化されたルールをバージョン管理で更新し、代表的でプライバシーに配慮したフィクスチャセットに対して変更をテストしてください。
実用的な検証手順
保守しやすい実装では、次の手順を使用できます。
- リクエストに文字列値と有効な業務レコードが含まれていることを確認します。
- 元の入力を保存し、文書化された正規形を作成します。
- 空の値、プレースホルダー、安全でない文字、文書化された長さの範囲外の値を拒否します。
- 信頼できる注文データから配送業者を解決するか、明示的にサポートされた検出フローを使用します。
- 信頼できる文書で裏付けられている場合にのみ、配送業者固有の構文ルールとチェックサムルールを適用します。
- エンドポイント要件、重複状態、再試行の可否を確認します。
- 送信し、レスポンスを分類して結果を保存し、未解決のレコードについてフォローアップを予定します。
この手順では、各判断に異なる理由があるため、バリデーターをテストしやすくなります。また、運用チームに単一の不透明なエラーではなく、実行可能な失敗カテゴリを提供できます。
実装チェックリスト
- 先頭のゼロを保持できるよう、追跡番号を文字列として保存します。
- 監査可能性が重要な場合は、元の値と正規形を別々に保持します。
- 配送業者のルールは、分散したハードコード条件ではなく、バージョン管理された設定として管理します。
- 英字、数字、ハイフン、空白、Unicodeの類似文字、プレースホルダー、境界長をテストします。
- 利用可能な場合は、信頼できる配送業者のコンテキストを使用します。
- 正規表現の一致に成功したことから、出荷の存在を推測しないでください。
- 恒久的な検証エラーを、一時的なAPIエラーやネットワークエラーとは別に分類します。
- 形式ルールやリクエストロジックを変更する前に、プロバイダーのドキュメントを確認します。
FAQ
正規表現で追跡番号を検証できますか?
配送業者とサービスの形式が既知であれば、限定的なパターンを検証できます。ただし、その番号が存在すること、特定の出荷に属すること、現在有効であることまでは証明できません。汎用的な正規表現は、誤った拒否や誤った一致を生みやすくなります。
無効に見える番号をAPIに送信すべきですか?
明らかに空、安全でない、または構造上不可能な値は、通常、送信前に停止すべきです。見慣れない形式であっても、それ以外は安全な値を、社内の推測に一致しないという理由だけで拒否してはいけません。まず配送業者のドキュメントを確認するか、サポートされている検出プロセスを使用してください。
チェックサムだけで出荷を確認できますか?
いいえ。適用可能な場合でも、チェックサムは値が数学的なルールを満たしているかを検査するだけです。配送業者がその番号を発行したことや、荷物がネットワークに入ったことは確認できません。
配送業者が不明な場合はどうすべきですか?
一般的な安全チェックを実行し、利用可能であれば配送業者検出を明示的にサポートするAPIワークフローを使用します。それ以外の場合は、配送業者を黙って推測するのではなく、情報補完または手動レビューのためにレコードを保持してください。
APIエラーはどのように処理すべきですか?
原因別に分類します。不正な入力やサポートされていない配送業者の値は修正し、一時的なネットワークエラーやプロバイダー障害は制限とバックオフを設けて再試行し、認証またはクォータのエラーは統合担当者に割り当てます。秘密情報を公開せず、診断に必要なレスポンスの詳細を保存してください。
出典
- 17TRACK APIドキュメント — 追跡API開発者向けのリクエストおよび統合に関するガイダンス。
- 17TRACK Tracking API — 公式製品情報とAPIの利用例。
- USPS Tracking — 公式配送業者追跡ページと利用者向けガイダンス。
- UPS Tracking — 公式配送業者追跡ページ。


