Vizion 接続：営業発行の API Key でコンテナのマイルストーンを追跡
Vizion API Key はアカウント開設時に Vizion の営業が発行します。セルフサービスの登録はありません。キーを Integration の唯一のフィールド api_key に貼り付け、テスト・マッピング・有効化を行います。
Vizion コネクタの仕事は 1 つだけです：ドレージ向けのコンテナ追跡です。コンテナ番号、船荷証券番号、予約番号のいずれかで追跡（リファレンス）を開始すると、コネクタはその貨物のマイルストーン更新を返します。各マイルストーンには計画時刻（見積もり、ETA）または実績時刻（ATA）が付くため、予定と実際の両方を確認できます。範囲はこれだけです：注文は取り込まず、出荷や配車は作成せず、ターミナルの予約は行わず、Vizion へは何も書き戻しません。1 接続は 1 つの Vizion API Key で動作します。
前提条件#
- Vizion の営業を通じて開設した Vizion アカウントがあり、API アクセスが含まれていること。API Key はアカウント開設時に Vizion の営業が発行します。セルフサービスの登録ページはないため、キーをまだ持っていない場合は、Vizion の営業からキーを取得することが、このシステムでの作業に先立つステップゼロです。
- Vizion の営業が発行した API Key そのもの。届いた元のメッセージや文書を保管してください。キーを紛失したり拒否されたりした場合、再発行できるのは Vizion の営業だけです。設定ページで照会したり再生成したりすることはできません。
- 実際に追跡したいコンテナ番号、船荷証券番号、予約番号が少なくとも 1 つあること。最初のマイルストーンを、内容の分かる貨物と照合できます。その貨物の運送会社コード（SCAC）があれば併せて用意してください。Vizion は運送会社を自動で特定できますが、公式の案内では、可能な場合は運送会社コードを提供するよう推奨されています。
認証情報の取得#
- まだの場合は、Vizion の営業に連絡し、API アクセス付きの Vizion アカウントを開設します。API Key はアカウント開設の一環として Vizion の営業が発行します。
- Vizion の営業から API Key を受け取ります。セルフサービスの登録も、自分で作成できる開発者ページもありません。アカウント開設プロセスの外で Vizion キーを「登録」すると申し出るページや人物があっても、それはこのキーの発行方法ではありません。
- 発行されたとおりにキー全体を一度にコピーします。この接続のキーは vizion_ で始まります。貼り付けられるよう用意してください。短くしたり、前置文字列を付けたりしないでください。
- 認証情報はこれ 1 つだけであり、覚える Vizion のアドレスも 1 つだけです：https://prod.vizionapi.com。別途設定するサンドボックス用アドレスはありません。発行されたキーは同じアドレスでテストされ、本番でも使われます。
Integration への入力#
- Integration → コネクタマーケットプレイス → Vizion → 新規接続 を開きます。
- api_key、必須、Vizion API Key：Vizion の営業が発行したキー全体を貼り付けます。vizion_ で始まります。この接続で唯一のフィールドです。パスワード型のフィールドで、秘密情報として保存されます。発行されたとおりにキーだけを貼り付けてください。X-API-Key ヘッダーはシステムが自動で付けます。
- 接続を保存し、他の設定を変える前にテストを実行してください。フィールドが 1 つだけなので、テストが失敗した場合はそのキー、またはその背後にあるアカウントが有効かどうかが問題であり、多数のフィールドの中から間違いを探す必要はありません。
接続テスト#
接続テストをクリックします。キーが入力されている場合、テストは実際の読み取り専用リクエストを 1 回送信します：GET https://prod.vizionapi.com/references?limit=1、キーは X-API-Key ヘッダーとして送信され、タイムアウトは 12 秒です。有効なリファレンスを 1 件だけ取得するだけなので、Vizion の内容は変更されません。合格した応答は「Vizion authentication passed」として返ります。キーが拒否された場合、テストは HTTP_401 を報告します。api_key が空の場合、MISSING_CREDENTIALS で止まります。完了できないリクエストは CONNECTION_FAILED を報告します。結果が示す原因を直して再テストしてください。
Mapping / テンプレート選択#
Vizion 標準の Mapping を選択します。Vizion がリファレンスについて返す各マイルストーン更新を、ここでドレージ追跡で確認するコンテナ記録と揃え、Vizion 自身の区別を保持します。planned とマークされたマイルストーンは推定時刻（ETA）を、そうでないものは実績時刻（ATA）を保持します。テスト合格後、内容の分かるコンテナ、船荷証券、予約のいずれかで追跡を開始し、最初のマイルストーン（イベント、場所、各時刻が計画か実績か）を、同じ貨物について Vizion が表示する内容と比較してください。一致すれば Mapping は正しく、有効化できます。
有効化#
有効化後、コンテナ番号、船荷証券番号、予約番号のいずれかで追跡を開始でき、接続はそれらのリファレンスのマイルストーン更新をここのドレージ追跡に届け続けます。リファレンス開始時には Vizion の 2 つのルールが適用されます。船荷証券番号か予約番号のどちらか一方を指定し、両方を同時に指定しないでください。両方を含むリクエストは拒否されます。また、運送会社コード（SCAC）がある場合は常に追加してください。運送会社の自動特定は代替手段であり、推奨される方法ではありません。リファレンスの更新は、取得した更新と同じ形式でプッシュ通知としても届くため、どちらの場合でもここで見る内容は一貫します。最初は Runs / Logs でリファレンスを確認し、数件の貨物を Vizion と照合してから無人運用に移してください。
この接続が行わないこと：他のシステムから注文や貨物を取り込まず、配車や積載を作成せず、ターミナルの予約や変更は行わず、追跡データを Vizion に送信しません。また、追跡対象は開始したリファレンスだけです。他所で蓄積した出荷履歴を取り込むことはありません。
よくある質問#
テストが HTTP_401 で失敗する
Vizion が送信されたキーを拒否しました。よくある原因は、コピー時にキーが切り取られたこと、発行された原本と文字が異なること、または Vizion がすでにキーを置換したか、アカウントでまだ有効化していないことです。この接続は公式ドキュメントの指定どおり、キーを X-API-Key ヘッダーとして送信するため、送信形式は変数ではありません。問題はキーの値です。
貼り付けたキーを、Vizion の営業が発行した原本と 1 文字ずつ比較し、相違があれば直して保存し、再テストしてください。貼り付けたキーが原本と完全に一致しているのにテストが HTTP_401 を報告し続ける場合は、Vizion の営業に連絡し、キーがアカウントで有効か確認するか、再発行を依頼してください。これができるのは Vizion の営業だけで、自分でリセットできるページはありません。
テストが MISSING_CREDENTIALS で止まる
api_key フィールドが空のため、送信するキーがなく、テストは何も確認できません。この接続のフィールドは 1 つだけなので、認証情報が別の場所に隠れていることはありません。
Vizion の営業が発行したキー全体を api_key に貼り付け、接続を保存して再テストしてください。キーをまだ持っていない場合は、まず Vizion の営業から取得してください。自分で作成できる登録ページはありません。
登録ページがない — Vizion API Key はどこで入手するのか
これは Vizion 側の設計です。API Key はセルフサービスではありません。キーは Vizion アカウントの開設時に Vizion の営業が発行するため、キーを作成できる公開ページは意図的に存在せず、このシステムが代わりに生成することもできません。
Vizion の営業に連絡し、API アクセス付きのアカウントを開設して、キーを受け取ってください。その後、この接続に戻り、キーを api_key に貼り付けて保存し、テストします。会社ですでに Vizion アカウントがある場合は、2 つ目のアカウントを開設する前に、開設した同僚に発行済みキーの保管場所を確認してください。
追跡の開始が INVALID_REQUEST で失敗する — 船荷証券番号と予約番号を両方指定した
Vizion は 2 つの番号を二者択一として検証します。追跡リクエストには船荷証券番号か予約番号のどちらか一方は指定できますが、両方を同時に指定したリクエストはこの検証で拒否されます。これは Vizion 側のルールであり、どちらの番号が間違っているわけでもありません。単独であればどちらでも問題ありません。
2 つの番号のうち 1 つだけを指定して追跡を再開してください。船荷証券番号か予約番号を残し、もう一方を削除します。代わりにコンテナ番号を識別子として指定することもできます。分かれば運送会社コード（SCAC）も追加してください。
追跡の開始が INVALID_REQUEST で失敗する — 識別子が指定されていない
リファレンスに識別子が指定されていません。Vizion は 1 つの識別子（コンテナ番号（container_id）、船荷証券番号、予約番号のいずれか）から追跡を開始するため、3 つともなければリファレンスを作成する対象がありません。
その貨物の 3 つの番号のいずれかで追跡を再開してください。組み合わせのルールも覚えておいてください。船荷証券番号を使う場合は、予約番号を追加しないでください。運送会社コード（SCAC）があれば追加し、Vizion が運送会社を自動特定しなくて済むようにしてください。
テストが CONNECTION_FAILED で失敗する、または 12 秒でタイムアウトする
prod.vizionapi.com への読み取り専用リクエストが時間内に完了しませんでした。これは Vizion API への到達性の問題か、Vizion の一時的な遅延です。キーが間違っている証拠ではありません。キーは API が実際に応答した時点で初めて判定されます。
少し待って、キーを変えずに再テストしてください。失敗が続く場合は、サポートを求める際に Runs / Logs の失敗時刻を控え、リクエストが https://prod.vizionapi.com 宛てで、キーが X-API-Key ヘッダーに入っていることを Vizion サポートに伝えてください。同じ時間帯を先方でも確認できます。
マイルストーンの時刻がおかしい — 未来になっている、または変わった
そのマイルストーンはおそらく計画型です。Vizion のデータでは、planned=true とマークされたマイルストーンは推定時刻（ETA）を保持します。これは性質上未来にあり、貨物の進捗に応じて改訂されます。planned=false のマイルストーンは実績時刻（ATA）を保持し、発生後は固定されます。見積もりが変わるのは、データが意図どおり機能している証拠であり、追跡が間違っているわけではありません。
時刻に基づいて行動する前に、マイルストーンの planned フラグを確認してください。計画は計画時刻（ETA）を中心に立て、実績時刻（ATA）だけを履歴として扱います。実績とマークされた時刻が、同じイベントについて運送会社やターミナルが表示する内容と異なる場合は、リファレンスとイベントを控えたうえで Vizion サポートに確認を依頼してください。