ユーザーマニュアル

ヘルプセンター/ユーザーマニュアル/Terminal49 接続：コンテナ番号・船荷証券番号・予約番号でコンテナを追跡

Terminal49 接続：コンテナ番号・船荷証券番号・予約番号でコンテナを追跡

最終更新 2026-11-01

app.terminal49.com/developers/api-keys で無料の Developer Key を自分で取得し、Integration の唯一のフィールド api_key に貼り付け、テスト・マッピング・有効化を行います。

Terminal49 コネクタの仕事は 1 つだけです：ドレージ向けのコンテナ追跡です。コンテナ番号、船荷証券番号、予約番号のいずれかで追跡を開始すると、コネクタはマイルストーン、船舶スケジュール、ターミナルの空き状況を返します。ターミナルが報告する Last Free Day、保留（holds）、料金も含まれます。範囲はこれだけです：注文は取り込まず、出荷や配車は作成せず、ターミナルの予約は行わず、Terminal49 へは何も書き戻しません。1 接続は 1 つの Terminal49 API Key で動作します。

Terminal49 接続手順：キーを自分で取得し、1 フィールドだけ入力し、読み取り専用テストを実行して、Mapping と有効化を行います。

前提条件#

app.terminal49.com にログインできる Terminal49 アカウントがあり、開発者向け API キーのページを自分で開けること。キーはセルフサービスです。開始にあたり営業への連絡や承認待ちは不要です。
実際に追跡したいコンテナ番号、船荷証券番号、予約番号が少なくとも 1 つあること。最初の結果を、内容の分かる貨物と照合できます。
無料キーに頼る前に追跡量を把握してください。無料の Developer Key で追跡できるのは最大 100 コンテナまでです。接続の評価には十分ですが、本番で使うキーは、同時に追跡するコンテナ数に合わせて計画してください。

認証情報の取得#

app.terminal49.com にログインし、開発者向け API キーのページ app.terminal49.com/developers/api-keys を開きます。
そのページでキーを作成します。無料の Developer Key で接続と評価には十分です。最大 100 コンテナまで追跡できます。
API Key 全体を一度にコピーし、貼り付けられるよう用意します。短くしたり、前置文字列を付けたりしないでください。キー自体が認証情報のすべてです。
認証情報はこれ 1 つだけです。別途ユーザー名、パスワード、サンドボックス用キー、2 つ目のキーを集める必要はなく、テストと本番は同じ Terminal49 のアドレスを使います。テストに使うキーが、そのまま本番で使うキーです。

Terminal49 がこのシステムと通信する際、キーは「Authorization: Token <API_KEY>」という形式のヘッダーで送信されます。これはシステム側で処理されるため、ヘッダーをどこかに入力する必要はありません。トラブル対応の際は形式だけ覚えておいてください。Terminal49 ではここで Bearer ではなく Token を使うため、Bearer 形式で Terminal49 API を確認すると、正しいキーでも失敗します。

Integration への入力#

Integration → コネクタマーケットプレイス → Terminal49 → 新規接続を開きます。
api_key、必須、Terminal49 API Key：app.terminal49.com/developers/api-keys でコピーしたキー全体を貼り付けます。この接続で唯一のフィールドです。パスワード型のフィールドで、秘密情報として保存されます。前置として「Token」や「Bearer」という語は付けず、キーだけを貼り付けてください。ヘッダー形式はシステムが自動で付けます。
接続を保存し、他の設定を変える前にテストを実行してください。フィールドが 1 つだけなので、テストが失敗した場合はそのキーの問題であり、多数のフィールドの中から間違いを探す必要はありません。

接続テスト#

接続テストをクリックします。キーが入力されている場合、テストは実際の読み取り専用リクエストを 1 回送信します：GET https://api.terminal49.com/v2/tracking_requests?page[size]=1、キーは「Authorization: Token <API_KEY>」として送信され、タイムアウトは 12 秒です。既存の追跡リクエストの最初のページを読むだけなので、Terminal49 の内容は変更されません。合格した応答は「Terminal49 authentication passed」として返ります。キーが拒否された場合、テストは HTTP_401 を報告します。api_key が空の場合、MISSING_CREDENTIALS で止まります。完了できないリクエストは CONNECTION_FAILED を報告します。結果が示す原因を直して再テストしてください。

Mapping / テンプレート選択#

Terminal49 標準の Mapping を選択します。Terminal49 が返す各追跡結果（マイルストーン、船舶スケジュール、Last Free Day・保留・料金などのターミナル空き状況）を、ここでドレージ追跡で確認するコンテナ記録と揃えます。テスト合格後、内容の分かるコンテナ、船荷証券、予約のいずれかで追跡を開始し、マイルストーンとターミナルの日付を、同じ貨物について Terminal49 が表示する内容と並べて比較してください。一致すれば Mapping は正しく、有効化できます。

Terminal49 のデータフロー：1 つの識別子で追跡を開始し、マイルストーンとターミナルデータがドレージ追跡に戻ります。

有効化#

有効化後、コンテナ番号、船荷証券番号、予約番号のいずれかで追跡を開始できます。3 つのうち 1 つを指定し、分かれば運送会社の SCAC も併せて指定してください。接続はそれらのコンテナのマイルストーン、船舶スケジュール、ターミナルの空き状況をここで更新し続けます。追跡リクエストは Terminal49 側で 1 分あたり 100 件に制限されているため、大量の一括開始は一度に全部送らず分散されます。最初は Runs / Logs で追跡結果を確認し、数件のコンテナを Terminal49 と照合してから無人運用に移してください。

この接続が行わないこと：他のシステムから注文や貨物を取り込まず、配車や積載を作成せず、ターミナルの予約や変更は行わず、追跡データを Terminal49 に送信しません。また、追跡対象は追跡を開始したコンテナだけです。Terminal49 の出荷履歴全体を自動で見つけて取り込むことはありません。

よくある質問#

テストが HTTP_401 で失敗する

Terminal49 が送信されたキーを拒否しました。よくある原因は、コピー時にキーが切り取られたこと、前に余分な語が貼り付いたこと、またはコピー後に Terminal49 アカウントでキーが削除・置換されたことです。アドレスと接続は問題ありません。このコードはキー自体に関するものです。

app.terminal49.com/developers/api-keys を開き、新しいキーを作成し、前に何も付けず全文をコピーして api_key フィールドに貼り付け、保存して再テストしてください。API を手動で確認している場合は、ヘッダー形式が「Authorization: Token <API_KEY>」であることを覚えておいてください。Bearer 形式の確認は、正しいキーでも失敗します。

テストが MISSING_CREDENTIALS で止まる

api_key フィールドが空のため、送信するキーがなく、テストは何も確認できません。この接続のフィールドは 1 つだけなので、認証情報が別の場所に隠れていることはありません。

app.terminal49.com/developers/api-keys でコピーしたキー全体を api_key に貼り付け、接続を保存して再テストしてください。

テストが CONNECTION_FAILED で失敗する、または 12 秒でタイムアウトする

Terminal49 API への読み取り専用リクエストが時間内に完了しませんでした。これは api.terminal49.com への到達性の問題か、Terminal49 の一時的な遅延です。キーが間違っている証拠ではありません。キーは API が実際に応答した時点で初めて判定されます。

少し待って、キーを変えずに再テストしてください。失敗が続く場合は、サポートを求める際に Runs / Logs の失敗時刻を控えてください。Terminal49 側と時間帯を照合できます。

追跡の開始が INVALID_REQUEST で失敗する

追跡リクエストに識別子が指定されていません。Terminal49 は 1 つの識別子（コンテナ番号、船荷証券番号、予約番号のいずれか）から追跡を開始するため、3 つともなければ開始できるものがありません。

その貨物の 3 つの番号のいずれかで追跡を再開し、分かれば運送会社の SCAC も追加してください。Terminal49 がリクエストを正しい運送会社に対応付ける助けになります。

多数のコンテナを一度に開始すると HTTP_429 で失敗する

Terminal49 のレート制限に達しました。追跡リクエストの上限は 1 分あたり 100 件です。キーにも、失敗したコンテナにも問題はありません。Terminal49 が受け付ける速度より速く送信されただけです。

失敗したコンテナは、より小さなバッチに分け、1 分以上に分散して再開してください。全体を一度に再試行しないでください。すでに開始済みのものは通常どおり追跡が続きます。

約 100 コンテナを超えると新しいコンテナが追跡されなくなる

無料の Developer Key を使用しています。追跡できるのは最大 100 コンテナまでです。接続とキーは機能しています（最初の 100 件がその証拠です）が、無料キーではそれ以上のコンテナを同時に収容できません。

接続を、実際の業務量に合ったコンテナ枠を持つ Terminal49 キーに切り替えてください。Terminal49 アカウントでそのキーを作成または取得し、api_key に貼り付けて無料キーと置き換え、保存してテストします。無料キーで開始済みの追跡はこのシステムの設定ではありません。業務量が増えたら、まずキーの枠を確認してください。