terra-vantage

Terra API Vantage

Vantage API は、血液検査や DNA 診断製品を管理し、注文を処理して、検査結果を提供するためのプラットフォームです。医療提供者、検査機関、パートナーは、診断検査を自社アプリケーションに直接組み込めます。Terra API が、検査キットのサプライヤーとの連携（最低注文数の要件なし）、物流と配送、コンプライアンス、結果の FHIR 形式への標準化といった運用上の複雑さを処理します。

利用可能な地域とオンボーディング。 Vantage は英国と米国で利用でき、ドイツ、スペイン、フランスでは近日提供予定です。オンボーディングは手動で行われ、セルフサービスではありません。認証情報を有効にするには Terra API にお問い合わせください（アカウントのセットアップを参照）。まずサンドボックス環境にアクセスし、本番環境は運用開始時に別途有効化されます。

サンプルアプリから始める

新しいアプリの場合は、診断製品のストアフロントと運用コンソールの公開サンプルから始め、ユーザーの要件に合わせて調整します。terra version を実行し、CLI が見つからない場合はインストールを提案します（以下を参照）。次に、現在のカタログを一覧表示し、最も適したものをクローンします。

terra examples list --select name,title,description
terra examples clone vantage-web-app my-app

どちらもログインは不要です。ダウンロードした README と AGENTS.md を読み、next_steps に従って、依存関係のインストール、設定、実行を済ませてから、その上に構築してください。クローンでダウンロードされるのはファイルだけです。既存のアプリの場合は、サンプルを参考にし、関連する部分をその場で調整してください。CLI を実行できないチャットアシスタントでは、ユーザーが自分のターミナルで実行できるようにこれらのコマンドを提示するか、ソースへのリンク https://github.com/tryterra/terra-examples/tree/main/examples/vantage-web-app を案内してください。

アカウントツール：CLI または MCP

アカウントツールは、Vantage の注文、製品、結果のエンドポイントを呼び出しません。これらは引き続き独自のクライアントで扱います。また、terra data-api に Vantage のパスはありません。アカウントツールが行うのは、Vantage の認証情報を提供し、環境の Vantage API バージョンを設定することです。

認証情報。 Vantage の認証には、ほかのすべての Terra API 製品と同じ dev-id と API キーを使用します。

terra environments list                                # which dev-ids exist
terra environments retrieve-api-key --env <dev-id>     # dev-id and API key for Basic auth

これらは、以下の Authorization: Basic base64(DEV_ID:API_KEY) の DEV_ID と API_KEY です。そのため、エージェントはダッシュボードからコピーしてもらうのではなく、これらを取得できます。Sandbox と production は Vantage のホストが異なりますが、アカウントの認証情報は同じです。

retrieve-api-key はキーを出力しますが、このコマンドは値を出力すること自体を目的としているため、値を使用する処理の直前にのみ実行してください。Webhook の署名シークレットも返します。CI ではジョブログに出力されないよう、コンシューマーにパイプで渡し、必要なフィールドだけを取得するには --select を使用してください。MCP 経由では、method: "retrieve_api_key" を指定した environments_read が同じペアを会話に返すため、値をファイルに渡すだけでよい場合は CLI を使用してください。

API バージョン。 Vantage のレスポンス形式には日付ベースのバージョンがあり、環境に固定されたバージョンによって、X-Terra-Version ヘッダーを送信しないすべてのリクエストと、すべての Webhook 配信（このヘッダーは Webhook には適用されません）の形式が決まります。

terra vantage api-version retrieve --env <dev-id>                          # pinned, latest, and every version you can move to
terra vantage api-version update --env <dev-id> --version <date> --dry-run # preview the change

更新すると、現在固定されているバージョンより古くても新しくても、環境の次の Vantage リクエストから有効になります。また、固定を解除することはできません。Webhook ハンドラーが受け取る形式が変わるため、ハンドラーが両方の形式に対応し、各配信に付く X-Terra-Version ヘッダーで形式を判別できるようになってから、バージョンを変更してください。各バージョンで何が変わるかについては、バージョン管理をお読みください。

コーディングエージェント（Claude Code、Codex、Cursor など。ユーザーのマシン上でもクラウド上でも）では CLI を使用し、インストールされていない場合はインストールを提案してください。macOS と Linux では curl -fsSL https://cli.tryterra.co/install.sh | sh、Windows PowerShell では irm "https://cli.tryterra.co/install.ps1" | iex、またはユーザーがすでに利用している場合は Homebrew か npm を使用します。チャットアシスタント（claude.ai、Claude Desktop、ChatGPT）では、コードを実行できる場合でも Terra API admin MCP サーバーを使用してください。サンドボックスでは CLI をインストールしたり、サインインしたりできません。各管理コマンドは、その名前と method で表されるツールです（terra users list は method: "list" を指定した users_read です）。terra data-api、terra admin-api、terra examples が使えるのは CLI のみで、--select と --jq に MCP の同等機能はありません。terra-cli と terra-mcp のスキルには、安全策（変更の確認、認証情報をトランスクリプトに残さないこと）、エラー、タスクごとの手順が含まれています。これらは連携を管理するものであり、このスキルで説明する API 呼び出しの代わりにはなりません。

認証

Vantage では、標準の Terra API 認証情報（Terra API ダッシュボードにある dev-id と API キー。ほかのすべての Terra API 製品と同じペア）を使用し、認証が必要なすべてのエンドポイントに次のいずれかの方法で提示します。

1. HTTP Basic（ドキュメントで示されている方法）：ユーザー名 = dev-id、パスワード = API キー、すなわち Authorization: Basic base64(DEV_ID:API_KEY) です。以前のドキュメントでは、これらを CLIENT_ID／CLIENT_SECRET と呼んでいましたが、値は同じです。
2. ヘッダーのペア：dev-id: <id> + x-api-key: <key>。

401 = 認証情報が誤っているか、不明です。403 = アカウントが停止されている、Vantage へのアクセス権がない、カタログで無効になっている製品を注文している、または production で simulate エンドポイントを呼び出している状態です。

ベース URL（以下のすべての API パスは /api/v1 以下です）：

環境	ベース URL
Production	https://vantage.tryterra.co
Sandbox	https://vantage-sandbox.tryterra.co

注文から結果確認までのワークフロー

この連携では、カタログから結果の確認まで、テストの一連の流れを実行します。製品は3階層のカタログで構成され（製品タイプに製品が含まれ、製品にバリアントが含まれます）、バリアントは受取人が実際に受け取る対象です。

1  GET  /api/v1/products                       -> list product types (e.g. Blood Test)
2  GET  /api/v1/products/{product_type_id}     -> products within a type
3  GET  /api/v1/products/{product_id}/variants -> variants of a product
4  POST /api/v1/orders                         -> place order (variant_id + quantity + recipient)
5  (webhooks)                                  -> fulfillment + results status changes
6  GET  /api/v1/results/{order_item_id}?test_taker_id= -> presigned FHIR download URL
7  POST /api/v1/results/{order_item_id}/acknowledge?test_taker_id= -> MANDATORY, user-triggered

注文を行うと、order_id、recipient_id、および各項目につき1つのorder_item_idを含む201が返されます。新しい注文はorder_status: "order.payment_processing"から始まり（order.processingは後の状態で、支払いの完了後にのみ移行します）、各項目はresults_status: "results.awaiting_sample"から始まります。結果、キットの有効化、確認はすべて項目単位で行われるため、以降の処理ではすべてorder_item_idで追跡してください。

references/api-reference.mdでは、各目的に対応するエンドポイント（注文／結果のインデックス、検査機関の検索、カタログのキュレーション、監視用エンドポイントを含む）と、現在のリクエスト／レスポンスのスキーマが記載されたライブドキュメントページを確認できます。エンドポイント呼び出しを実装する前に参照し、リクエストボディを作成する際はリンク先の.mdページを取得してください。

検体採取方法

各注文では、検体の採取方法と適用される住所フィールドを決定するcollection_typeを指定します。

collection_type	意味	住所フィールド
AT_HOME	キットを受取人に発送します。受取人が自分で検体を採取し、キットの説明書に従います	shipping_address
GO_TO_LAB	検査機関の採取施設（Patient Service Center）で検体を採取します	requested_lab_address

GO_TO_LABでは、指定された検査機関の住所を使って、利用可能な最寄りの検査機関に注文を割り当てます。また、事前にユーザーに提示する近隣の採取施設（米国）は、GET /api/v1/labs?zip_code=で一覧表示できます。注文をユーザーが選択した施設に紐付けるには、その行のcodeとaddress.postal_codeをPOST /ordersのrequested_labとして渡します。すると、レスポンスに施設の詳細情報を含むconfirmed_labが返されます。不明なコードの場合は、invalid_fieldsタグunknown_lab_codeを含む400エラーが返されます（/labsを再取得して選び直してください）。一時的な検索障害が発生した場合、注文は施設に紐付けられないまま受け付けられます（confirmed_labはnullで、requested_labはGETのレスポンスにそのまま返されます）。レスポンスのconfirmed_lab_addressは、指定住所に最も近い採取施設を示します（ベストエフォートであり、nullの場合もあります。参考情報であり、施設の予約を確定するものではありません）。バリアントのavailable_collection_types（文字列"AT_HOME"／"GO_TO_LAB"の配列）には対応する採取方法が、supported_ship_to_countriesには注文可能な国（ISO-3166 alpha-2）が示されます。後者は、AT_HOMEでは発送先の国、GO_TO_LABでは指定検査機関の国を表します。注文前に、両方の値に基づいて採取方法と住所フォームを制限してください。

キットの有効化

一部のサプライヤーでは、検査機関が処理する前に、エンドユーザー自身がキットを有効化する必要があります（たとえば、パッケージのQRコードをスキャンします）。QRコードにはGET /api/v1/orders/activate?kit_id={supplier_item_id}が埋め込まれており、HTML形式の有効化フォームが表示されます。このフォームはPOST /api/v1/orders/activateに送信されます（JSONボディ。独自のUIを用意している場合はプログラムで構築できます）。どちらの有効化ルートも認証不要です。有効化が成功すると、新たに割り当てられた**test_taker_idを含む**results.kit_activatedウェブフックが送信されます。すべての結果取得リクエストで必要になるため、このIDを取得してください。

結果の確認（必須）

結果の確認は任意ではありません。臨床的なエスカレーションの度合いが低いものから高いものまで、すべての結果について、患者がアクセスできるようになる前に明示的に確認する必要があります。また、確認の呼び出しは、閲覧後にボタンやチェックボックスを押すなど、エンドユーザーの明示的な操作によって実行する必要があります。取得時にバックエンドが自動的に実行してはいけません。

POST /api/v1/results/{order_item_id}/acknowledge?test_taker_id={id}

結果を未確認のままにした場合に生じる影響として、次の2点が挙げられています。

• 責任はあなたに移ります。 確認を怠ると「責任の連鎖が始まり、責任があなたに直接移転」し、結果の遅延や未確認に起因する有害な結果について、あなたの組織が全面的な責任を負います。
• サプライヤーが患者に直接連絡する場合があります。 エスカレーションされた結果にはacknowledgment_due_byの期限が設定されます。結果が未確認のままの場合、検査サプライヤーおよび医療チームは患者に直接連絡する権限を持ちます。

FHIR の結果の構造と、取得／確認エンドポイントの詳細はreferences/results.mdに記載されています。結果の取得や確認ステップを実装する際にお読みください。

Webhook

Terra API は、環境ごとに登録された HTTPS webhook URL に、注文と結果の進捗を配信します（PATCH /api/v1/clients/webhook-url。登録内容はGETで読み戻せます）。event_typeには、注文の進捗を示すorder.status_changedと、項目ごとの結果の進捗を示すorder_item.results_status_changeの2つのファミリーがあります。Webhook はX-Terra-Signatureヘッダーを使って HMAC-SHA256 で署名されます。信頼する前に、すべてのリクエストを検証してください。配信は少なくとも1回行われ、再試行もあります。event_idで重複を排除し、速やかに2xxを返してください。

各イベントタイプの詳細、完全なペイロード、ステータスの列挙値、署名の検証、再試行とデバッグの仕様については、references/webhooks.mdを参照してください。Webhook ハンドラーの実装や検証、または配信が見当たらない場合にお読みください。

サンドボックスの使用

サンドボックスの注文をライフサイクルに沿って進める方法は2つあります。

• シミュレーションエンドポイント（テストに推奨）。 {"event": "...", "order_item_id": "..."}を指定してPOST /api/v1/orders/{orderID}/simulateを実行すると、サプライヤーからの更新と同じように、1つのライフサイクルイベントが適用されます。ステータス履歴が記録され、署名付きWebhookも配信されます。イベント：payment_complete、payment_failed、processing、delayed、cancelled、delivery_fulfilled、completed、kit_activated、sample_processing_in_lab、sample_rejected、partial_results_ready、results_ready、lab_processing_error、escalation_raised。有効な前方遷移のみが受け付けられます（それ以外は422）。results_readyではサンプル結果も保存されるため、ダウンロードから確認まで一連の動作をテストできます。本番環境では403を返します。
• シミュレートされたサプライヤーフロー。 サンドボックスのサプライヤーは、タイマーに沿って注文を進めます。出荷のWebhookは通常1分以内に届き、キットの有効化後は1～2分間隔で結果のWebhookが届きます。有効化はブラウザーフローです。https://vantage-sandbox.tryterra.co/api/v1/orders/activate?kit_id={supplier_item_id}を開き（supplier_item_idはサンドボックスのWebhookで届きます）、フォームに入力してください。正常なフローでは常にresults_readyになります。却下をテストするには、simulateを使用してください。

サンドボックスのWebhookでは、order.status_changedペイロードにsupplier_item_idが追加されます。本番のペイロードには含まれません（GET /api/v1/orders/{orderID}のitems[].supplier_item_idから取得してください）。

注意点

• ID は JSON 文字列です。 注文レスポンスと Webhook の order_id、order_item_id、recipient_id、test_taker_id、variant_id、event_id は、文字列としてシリアライズされた 64 ビットのスノーフレーク ID です。数値として解析しないでください（JavaScript では値が破損します）。カタログの読み取り（/products*）では引き続き数値の id フィールドが返されます。注文リクエストでは variant_id を文字列として指定します。
• どちらのインターフェースでも語彙は共通です。 REST の読み取りと Webhook ペイロードでは、同じ order.* のフルフィルメントステータス（支払い失敗は order.payment_failed）と、同じ results.* のステータスが使われます。Webhook のステータスは REST の読み取りと完全に一致します。（以前は Webhook で fulfillment.*、REST で order.failed とされていましたが、どちらも廃止されています。）
• 署名タイムスタンプの単位は Unix 秒です。 X-Terra-Signature: t=<unix_seconds>,v1=<hex>。t をミリ秒として扱うと、すべての検証が失敗します。署名は生のボディに対して検証してください。
• 結果の読み取りまたは確認には test_taker_id が必須です。 どちらのエンドポイントでもクエリパラメーターとして指定します。これは results.kit_activated Webhook で初めて通知されます。
• 注文を作成するときは Idempotency-Key ヘッダーを送信してください（試行ごとに一意の値）。同じキーとボディで再試行すると、注文が重複する代わりに元の結果が再生されます。同じキーで異なるボディを送ると 409 が返されます。このヘッダーがない場合、サーバー側での重複排除は行われません（client_order_reference_id は照合専用です）。失敗したかどうかが不明な場合は、直近の注文を一覧表示し、再試行する前に参照 ID と照合してください。
• 結果の署名付き URL は 15 分で期限切れになります。 URL をキャッシュするのではなく、再取得して新しい URL を生成してください。
• カタログの選定内容によって注文がブロックされます。 PUT /api/v1/products/selection は全件を置き換える書き込みです。選定対象から外された商品は読み取り結果から消え、それを注文すると 403 が返されます。
• サンドボックスと本番環境では Webhook URL が別々で、アクセスは環境ごとに有効化されます（まずサンドボックスから始めます）。
• 固定された API バージョンによって Webhook の形式が決まり、リクエストヘッダーでそれを上書きすることはできません。 リクエストの X-Terra-Version は、そのレスポンスにのみ適用されます。Webhook の配信では常に環境の固定バージョンが使われます。パーサーを作成する前に terra vantage api-version retrieve で確認し、各配信の X-Terra-Version ヘッダーをボディとともに保存してください。

最新のドキュメント

references/api-reference.md では、各エンドポイントに対応するリファレンスページを案内しています。全文を読む価値のあるガイド：

• Vantage API とは？
• アカウントの設定と認証
• バージョン管理
• サンドボックスの利用
• 結果の確認
• ベストプラクティス
• 本番環境への移行

ページを取得する前に terra docs ask（または MCP 経由の docs_ask）を実行してください。ドキュメントに基づいて回答し、出典を示します。ドキュメントの URL の末尾に .md を追加すると、Markdown 形式で取得できます。