terra-unified-api

Terra API のベストプラクティス

影響度の高い順に優先順位を付けた、5 つのカテゴリにわたる Terra API の本番環境で実証済みのガイドラインです。

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

新しいアプリを作成する場合は、ウェアラブルデバイスとの接続、Webhook の取り込み、ヘルスダッシュボード向けに公開されているサンプルから始め、ユーザーの要件に合わせて調整してください。terra version を実行し、CLI が見つからない場合はインストールを提案してください（下記を参照）。次に、現在のカタログを一覧表示し、最も近いものをクローンします。

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

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

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

以下のルールにおいて、アカウントツールは、期待した結果ではなく、Terra API が実際に行った処理に照らして作業を確認するためのものです。

terra unified-api destinations list --env <dev-id>        # where webhooks go, and whether they are active
terra events list --env <dev-id> --outcome failed         # deliveries your endpoint rejected
terra events retrieve-payload <event_id> --env <dev-id>   # the exact body that was sent
terra users list --env <dev-id> --reference-id <ref>      # connection state, one row per provider
terra unified-api data scopes list --env <dev-id>         # which fields a payload will carry

このうち 2 つのツールはテスト方法を変えます。terra events retrieve-payload は、「ペイロードにフィールドがなかった」という場合の真実を確認する手段です。そこにも存在しない場合、原因はハンドラーではなく、環境のデータスコープにあります。また、terra events resend --event-id <id> --event-type sleep --user-id <uuid> は、保存済みの実際のイベントをエンドポイントに再送するため、デバイスもプロバイダーの同期を待つ時間もなく、実際のペイロードを使ってハンドラーを実行できます。再送イベントは 2 回届く場合があるため、ハンドラーではあらかじめ重複排除を実装しておく必要があります（rules/webhooks-dedupe-terra-reference.md）。

これらのルールで検証する署名シークレットは、terra unified-api destinations create の作成時に一度だけ返されます。

MCP では、これらのうち 2 つの動作が異なります。events_read の method: "retrieve_payload" には MCP のアクセスレベルが必要です（読み取り専用ではペイロード本文を読み取れません）。また、ユーザーの健康データであるペイロードが会話に入ります。unified_api_destinations_write の create から返される signing_secret も会話に入るため、シークレットをハンドラーのシークレットストアに直接渡せるよう、ここでは CLI を使用してください。

コーディングエージェント（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 管理 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 呼び出しの代わりにはなりません。

優先順位別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	Webhook の処理	CRITICAL	webhooks-
2	データの処理と冪等性	CRITICAL	data-
3	認証と接続のライフサイクル	HIGH	auth-
4	複数デバイスのデータ	MEDIUM	devices-
5	テスト	LOW-MEDIUM	testing-

クイックリファレンス

1. Webhook の処理（重大）

• webhooks-verify-raw-body – JSON を解析する前に、変更されていない生のボディに対して署名ヘッダーの HMAC（terra-signature / X-Terra-Signature、大文字と小文字を区別せずに読み取る）を検証します
• webhooks-ack-within-timeout – タイムアウト（デフォルトは 8s）以内に 200 を返し、非同期で処理します
• webhooks-dedupe-terra-reference – X-Terra-Trace-Id で配信を重複排除します。terra-reference は大きなリクエストのすべてのチャンクで共有されます
• webhooks-archive-raw-payloads – 生のペイロードをオブジェクトストレージにアーカイブし、payload key を使って行と関連付けます
• webhooks-handle-informational-events – データ以外のイベントを明示的に振り分け、s3_payload の配信をラップ解除し、未知のタイプでもクラッシュしないようにします

2. データ処理と冪等性（重大）

• data-natural-keys – アクティビティ／睡眠は summary_id、日次タイプのデータは (connection, date)、ホルモンは timestamp をキーにします
• data-date-part-only – タイムゾーン変換を行う前に、ISO 文字列から日付部分を切り出します
• data-superset-overwrite – 標準フィールドは superset 保証に従い、X-Terra-Ordering-Timestamp が新しいか同じ場合は上書きします
• data-coalesce-enrichment-scores – エンリッチメントスコアは superset 保証の対象外となるため、COALESCE を使い、null で上書きされないようにします
• data-columns-over-blobs – メトリクスを型付きカラムに抽出し、生のペイロードはオブジェクトストレージに保持します
• data-timestamp-localization – timestamp_localization フラグに従い、保存ポリシーを意図的に選択します

3. 認証と接続のライフサイクル（高）

• auth-reference-id – ユーザー ID を reference_id として渡します。これはすべての webhook で使われる結合キーです
• auth-handle-all-events – 7 種類すべての認証イベントを冪等な upsert で処理します
• auth-reauth-id-swap – user_reauth は新しい Terra API ユーザー ID を発行するため、古い ID を新しい ID に置き換えます
• auth-parse-scopes – カンマ区切りのスコープ文字列を解析し、permission_change では scopes_added／scopes_removed を適用します
• auth-reconcile-connections – ページのマウント時、認証リダイレクト時、定期実行時に、Terra API の状態と照合します
• auth-integrations-endpoint-headers – 公開 integrations カタログに dev-id を送信します。送信しない場合、有効化したプロバイダーではなく、すべてのプロバイダーが返されます

4. 複数デバイスのデータ（中）

• devices-expect-cross-device-duplicates – 同じセッションが、異なる summary_ids を持ってデバイスごとに 1 回ずつ届きます。マージポリシーはアプリ側で管理します
• devices-enrichment-provider-agnostic – エンリッチメントスコアはプロバイダーに依存せず比較可能ですが、スコアの重み付けが有効な場合にのみ存在します

5. テスト（低～中）

• testing-mock-boundaries – SDK、データベース、バックグラウンドタスクをモックし、非同期処理を即時実行にします
• testing-cover-event-edge-cases – 再配信、空のデータ配列、未知のユーザー、type 0、エンリッチメントの null、再認証による ID の置き換えをテストします

使用方法

該当する領域に取り組む際は、rules/ 内の個別のルールファイルを読んでください。たとえば、webhook エンドポイントを作成する前に rules/webhooks-verify-raw-body.md と関連ファイルを読んでください。各ルールには、誤ったコードと正しいコードの例、および関連する docs.tryterra.co ページへのリンクがあります。ページを取得する前に terra docs ask（または MCP 経由で docs_ask）を使ってください。ドキュメントの内容をもとに回答し、情報源を示します。ドキュメントの URL の末尾に .md を追加すると、Markdown 形式になります。

関連スキル

このスキルでは Unified API の中核となる連携を扱います。その他の Terra API 製品には、それぞれ専用のスキルがあります。terra-mobile-sdk（Apple Health、Samsung Health、Health Connect）、terra-streaming（websocket 経由のリアルタイムデータ）、terra-planned-workouts と terra-routes（デバイスへの書き込み）、terra-lab-reports、terra-vantage（診断検査の注文）、terra-models です。アカウント関連の作業には、terra-cli または terra-mcp を使ってください。AI Interface は別のもので、アプリ独自のエージェントが連携済みユーザーの健康データを読み取れるようにする MCP サーバーです。上記の管理用 MCP サーバーはアカウントを管理します。