truto

Truto — 統合 API プラットフォーム

これは、Truto の主要な概念と API に関するリファレンスです。何かが何を意味するのか（統合 API とプロキシ API、カスタム API、統合アカウント、環境、Webhook、接続フロー）を説明する場合にも、ユーザーの製品の一部として動作する API 呼び出し、Webhook ハンドラー、接続 UI、データアクセス層を構築する場合にも参照してください。

概念に関する質問や方法に関する質問には、記憶に頼らず、このスキルとそのリファレンスに基づいて回答してください。以下の主要な概念の表は索引です。それぞれの概念から、その定義を記載したリファレンスに移動できます。

統合 API、プロキシ API、カスタム API の使用に、何かをインストールする必要はありません。接続済みの統合アカウントに対して HTTPS 経由で呼び出します（例：GET /unified/{model}/{resource}?integrated_account_id=…）。セットアップとはアカウントを接続することであり、API をインストールすることではありません。管理者向けのセットアップ、単発のデバッグ、ターミナルでのデータ調査については、Truto CLI スキルを参照してください。稼働中のワークスペースのデバッグについては、truto-operator スキルを参照してください。

重要： Truto API トークン（TRUTO_API_TOKEN）は、バックエンドでのみ使用してください。ブラウザーに公開したり、クライアント側のコードに含めたりしないでください。

使用する場面

• Truto の概念（統合 API／プロキシ API／カスタム API、統合アカウント、環境、テナント、同期ジョブ、Webhook、ワークフロー）や、その仕組みを説明する
• 上記のいずれかについて、「X を呼び出す／セットアップするにはどうすればよいか」という質問に回答する
• Truto 経由でデータを読み書きする API 呼び出しを記述する（統合 API、プロキシ API、カスタム API）
• Truto Link を使ったエンドユーザー向けの接続フローを構築する
• Truto からリアルタイムイベントを受信する Webhook ハンドラーを追加する
• Truto API 呼び出しのページネーション、エラー処理、リトライロジックを実装する
• ユースケースに合わせて、統合 API、プロキシ API、カスタム API のいずれを使うか選択する

Truto CLI をインストールする（推奨）

Truto CLI を使うと、アプリケーションに手を加えずに、インテグレーションでサポートされている機能を確認し、サンドボックスアカウントを接続して、統合 API の呼び出しを試すことができます。ターミナルから調査やテストをしたい場合は、利用を提案してください。このスキルの各ワークフロー（統合 API の呼び出し、マッピングのカスタマイズ、環境ごとのインテグレーションの上書き、Webhook のデバッグ）には、1 行で実行できる CLI のショートカットがあります。動作を確認したら、コードに移植できます。

# Linux / macOS
curl -fsSL https://cli.truto.one/install.sh | bash
truto login --token "$TRUTO_API_TOKEN"
truto whoami -o json

# Windows (PowerShell)
irm https://cli.truto.one/install.ps1 | iex
truto login --token $env:TRUTO_API_TOKEN
truto whoami -o json

コマンドの全一覧、出力形式、管理者向けワークフローについては、Truto CLI スキルを参照してください。このスキルのコードと CLI を組み合わせた、初日に取り組むためのガイド付きチュートリアルについては、はじめにを参照してください。

コアコンセプト

コンセプト	説明	リファレンス
環境	すべてのリソースをスコープとする分離されたワークスペースです。API トークンは1つの環境に紐付けられます。	コアリソース
インテグレーション	サードパーティ製ツールの定義です（例：Salesforce、Jira、Slack）。	コアリソース
環境インテグレーション	特定の環境にインストールされたインテグレーションで、任意の設定オーバーライドを適用できます。	コアリソース
連携アカウント	特定のテナント（エンドユーザー）に接続されたインテグレーションのインスタンスです。	コアリソース
テナント	連携アカウントを所有する、環境にスコープされた外部 ID（顧客／エンドユーザー）です。/tenant を介して管理され、明示的に作成するか、初回接続時に自動的に作成されます。	コアリソース
統合 API	共通スキーマを使用して、インテグレーション間で標準化された CRUD エンドポイントを提供します。	統合 API
プロキシ API	基盤となるツールのネイティブ API へのパススルーです。	プロキシ API とカスタム API
カスタム API	カスタムルーティングロジックを備えた、ユーザー定義の API エンドポイントです。	プロキシ API とカスタム API
同期ジョブ	連携アカウントからの、スケジュール実行またはオンデマンドのデータ同期です。	同期ジョブ
Webhook	リアルタイムのイベント通知を行う HTTP コールバックです。	Webhook と通知
データストア	同期ジョブの出力先となる外部ストレージ（MongoDB、GCS、S3、Qdrant）です。	データストア
ワークフロー	Truto のイベントによってトリガーされる、イベント駆動型の自動化です。	ワークフロー

呼び出す前に機能を確認する

/unified/...、/proxy/...、または /custom/... に対する fetch() を書く前に、必ず最初に機能エンドポイントを呼び出してください。 リソース名とメソッド名は連携先ごとに異なります（HubSpot では contacts／companies／deals、Bigcommerce では products／orders／customers など）。記憶を頼りにこれらをハードコードすることは、Truto の連携コードにおいて LLM が原因で発生する最も一般的なバグです。機能エンドポイントが唯一の信頼できる情報源です。

同じ形式のレスポンスを返す、同等のエンドポイントが 2 つあります。

GET https://api.truto.one/integrated-account/{integrated_account_id}/capabilities[?type=proxy|unified|all]
GET https://api.truto.one/integration/{integration_slug_or_id}/capabilities[?type=proxy|unified|all]

• 接続済みアカウントの UUID があり、そのアカウントで何ができるか（環境レベルの上書きを考慮したうえで）確認する場合は、integrated-account 版を使用してください。
• アカウントを接続する前に使用する場合（カタログの閲覧や、サポートする連携先の選定など）は、integration 版を使用してください。

type CapabilitiesResponse = {
  integration: { id: string; name: string; label: string; category: string };
  environment_id?: string;
  proxy: Array<{
    resource: string;
    methods: Array<{
      method: "list" | "get" | "create" | "update" | "delete" | string;
      name: string;
      description: string | null;
      has_description: boolean;
      has_query_schema: boolean;
      has_body_schema: boolean;
      has_response_schema: boolean;
      api_documentation_url: string | null;
    }>;
  }>;
  unified: Array<{
    model: string;
    model_label: string;
    resource: string;
    description: string | null;
    docs_url: string | null;
    methods: string[];
    env_overridden: boolean;
  }>;
  auth: {
    formats: string[];
    fields: Array<{ name: string; label: string; type: string; required: boolean }>;
    documentation_link?: string;
  };
  ai_readiness: { proxy_methods: number; proxy_methods_with_descriptions: number; ai_ready_score: number };
  account?: { id: string; status: string; authentication_method: string; is_blocked: boolean };
};

async function getCapabilities(accountId: string): Promise<CapabilitiesResponse> {
  const res = await fetch(
    `https://api.truto.one/integrated-account/${accountId}/capabilities?type=all`,
    { headers: { Authorization: `Bearer ${process.env.TRUTO_API_TOKEN}` } }
  );
  if (!res.ok) throw new Error(`Capabilities failed: ${res.status}`);
  return res.json();
}

const caps = await getCapabilities(accountId);
const proxyResources = caps.proxy.map(r => r.resource);
const unifiedRoutes = caps.unified.map(u => `${u.model}/${u.resource}`);

// Build calls only for routes the account actually exposes:
if (caps.unified.some(u => u.model === "crm" && u.resource === "contacts" && u.methods.includes("list"))) {
  const r = await fetch(
    `https://api.truto.one/unified/crm/contacts?integrated_account_id=${accountId}`,
    { headers: { Authorization: `Bearer ${process.env.TRUTO_API_TOKEN}` } }
  );
}

機能レスポンスは、連携先のバージョンごとに安価で安定しています。サーバー側で integration_id ごとにキャッシュしてください（クエリパラメーターのフィルター、キャッシュの指針、両方のエンドポイントのパターンを含む詳しいリファレンスについては、機能の確認をご覧ください）。対応する CLI コマンドは truto capabilities <slug-or-uuid> です。同じ形式の結果を返すので、コードに組み込む前にターミナルですぐに試せます。

はじめに

まず試してみますか？ 以下で説明する内容のほとんどは、コードに組み込む前に Truto CLI（上記のTruto CLI をインストールするを参照）から試すほうが簡単です。その後、同じ呼び出しをアプリケーションに移植できます。Day 1 の詳しい手順については、はじめにをご覧ください。以下の手順は、アプリケーションに移植する標準的なフローです。

1. API トークンを取得する

Truto Dashboardで API トークンを作成します。API トークンはダッシュボードからのみ作成でき、API や CLI からは作成できません。

サーバー側の環境変数（TRUTO_API_TOKEN）として保存してください。このトークンはバックエンドでのみ使用してください。ブラウザーに送信してはいけません。

2. リンクトークン用のバックエンドルートを作成する

Truto Link の接続フロー用にリンクトークンを生成するエンドポイントが、バックエンドに必要です。既存の接続に問題が発生した場合、ユーザーがアカウントを重複して作成してしまうのを防ぐため、このルートは最初から新規接続と再接続の両方に対応する必要があります。

app.post("/api/truto/link-token", async (req, res) => {
  const { tenantId, integratedAccountId } = req.body;

  // Reconnect an existing account, or create a new one
  const body = integratedAccountId
    ? { integrated_account_id: integratedAccountId, persist_previous_context: true }
    : { tenant_id: tenantId };

  const response = await fetch("https://api.truto.one/link-token", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.TRUTO_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  const { link_token } = await response.json();
  res.json({ linkToken: link_token });
});

どのフレームワークでも形式は同じです。API トークンを含めて POST /link-token にリクエストを送る、サーバー側の fetch です。はじめにでは、Next.js Route Handlers と Hono / Cloudflare Workers 向けに同じルートを記述しています。ご利用のスタックに合ったバリエーションを選び、スニペットを適宜調整してください。

再接続時は tenant_id の代わりに integrated_account_id を渡してください。既存アカウントの認証情報がその場で更新され、同じ integrated_account_id が保持されるため、すべての同期ジョブ、Webhook、参照がそのまま維持されます。persist_previous_context: true を設定すると、以前の接続からのカスタムコンテキストも保持されます。

3. フロントエンドに Truto Link を埋め込む

Truto Link SDKをインストールして、接続フローを UI に埋め込みます。

npm install @truto/truto-link-sdk

次に、フロントエンドで使用します。同じ authenticate() 呼び出しで、新規接続と再接続の両方に対応できます。違いは、バックエンドが生成するリンクトークンにあります。

import authenticate from "@truto/truto-link-sdk";

async function getLinkToken(body: Record<string, string>) {
  const res = await fetch("/api/truto/link-token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  const { linkToken } = await res.json();
  return linkToken;
}

async function openTrutoLink(linkToken: string) {
  try {
    const result = await authenticate(linkToken);
    console.log("Connected:", result.integrated_account_id);
    return result;
  } catch (err) {
    if (err === "closed") {
      console.log("User closed the connection dialog");
    } else {
      console.error("Connection failed:", err);
    }
    throw err;
  }
}

// New connection
const linkToken = await getLinkToken({ tenantId: "tenant-123" });
await openTrutoLink(linkToken);

// Reconnect an existing account (e.g., expired OAuth token)
const reconnectToken = await getLinkToken({ integratedAccountId: "existing-account-id" });
await openTrutoLink(reconnectToken);

ポップアップモード、同一ウィンドウでのリダイレクト、RapidForm、ファイルピッカー、エラー処理など、SDK の詳しいリファレンスについては、Truto Link SDK スキルをご覧ください。

4. アカウントが有効になるまで待機する

ユーザーが接続すると、アカウントは利用可能になる前に、インストール後の手順と検証を経ます。webhookを設定してintegrated_account:activeイベントを監視します。このイベントは、アカウントが接続され、API 呼び出しの準備が整ったことを知らせます。ライフサイクルとすべてのイベントについては、接続フローをご覧ください。

// Backend webhook handler
app.post("/webhooks/truto", async (req, res) => {
  const event = req.body;

  switch (event.event) {
    case "integrated_account:active":
      // Account is ready — store the integrated_account_id,
      // start syncing data, enable features for this tenant
      await onAccountReady(event.payload);
      break;

    case "integrated_account:post_install_error":
    case "integrated_account:validation_error":
      // Connection failed — notify the user or retry
      await onAccountError(event.payload);
      break;
  }

  res.sendStatus(200);
});

Truto Workflowsを使用して、アカウントが有効になったときにアクション（同期ジョブの開始など）を自動的に実行することもできます。詳しくはワークフローをご覧ください。

開発時のヒント。 動作するintegrated_account_idを取得するために、webhook を待つ必要はありません。CLI でtruto accounts list -o jsonを実行して接続済みアカウントを一覧表示するか（サンドボックスに絞り込むには--is_sandbox trueを指定）、その中から ID をコピーします。webhook の設定が完了する前に、その ID を使って以下の統合 API の手順をテストできます。

5. 統合 API でデータを読み取る

アカウントが有効になったら、正規化されたデータを取得します。

const accountId = "<integrated_account_id>";

const response = await fetch(
  `https://api.truto.one/unified/crm/contacts?integrated_account_id=${accountId}`,
  {
    headers: {
      "Authorization": `Bearer ${process.env.TRUTO_API_TOKEN}`,
    },
  }
);

const { result, next_cursor } = await response.json();

6. データを書き込む

const response = await fetch(
  `https://api.truto.one/unified/crm/contacts?integrated_account_id=${accountId}`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.TRUTO_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      first_name: "Jane",
      last_name: "Doe",
      email: "[email protected]",
    }),
  }
);

7. ネイティブアクセスにはプロキシ API を使用する

統合スキーマに含まれていない、連携先固有のフィールドが必要な場合：

const response = await fetch(
  `https://api.truto.one/proxy/contacts?integrated_account_id=${accountId}`,
  {
    headers: {
      "Authorization": `Bearer ${process.env.TRUTO_API_TOKEN}`,
    },
  }
);

統合 API、プロキシ API、カスタム API の使い分け

ユースケース	API	理由
連携先をまたいだ標準化された CRUD	Unified	基盤となるツールにかかわらず、リクエストとレスポンスのスキーマが同じです
統合スキーマに含まれないネイティブ API 機能へのアクセス	Proxy	ツールのネイティブエンドポイントにフルアクセスできます
カスタムのビジネスロジックや変換	Custom	カスタムルーティングで独自のエンドポイントを定義できます
依存関係のある一括データ操作	Batch Request	依存関係グラフを使って、1 回のリクエストで複数の API 呼び出しを実行できます

認証

すべての API リクエストでは、Bearer トークン認証を使用します。API トークンはサーバー側でのみ使用してください。API トークン、リンクトークン、統合アカウントトークンについて詳しくは、認証をご覧ください。

リファレンス

まずはこちら

ドキュメント	トピック
はじめに	初日のチュートリアル：CLI のインストール → ログイン → サンドボックスへの接続 → リンクトークンのルート作成 → 最初の統合 API 呼び出し → 同じ呼び出しをコードに移植

カスタマイズ（プラットフォームを拡張するために最もよく使われる機能）

ドキュメント	トピック
インテグレーションの作成	新しいインテグレーション定義をゼロから作成します。integration.config の完全なスキーマ、5種類すべての認証情報形式、リソース／メソッド、ページネーション、レート制限、受信 Webhook レシーバー、ライフサイクルアクションに加え、truto integrations init/validate/create ワークフローと Acme CRM を使った実例を説明します
インテグレーションのカスタマイズ	環境ごとの HTTP レイヤーのオーバーライド：認証、ページネーション、レート制限、Webhook、override.resources。API と CLI の update は override 全体を置き換えるため、常にオブジェクト全体を送信してください。override-* ヘルパーを使うと、1つの項目を取得してマージできます
Unified API のカスタマイズ	環境ごとの既存 Unified API マッピングの変更、アカウントごとのオーバーライド、独自のカスタム統合モデルの作成

コア API

ドキュメント	トピック
機能の確認	データアクセスコードを書く際は、まずここをお読みください。 /integration/<slug>/capabilities および /integrated-account/<id>/capabilities エンドポイント、レスポンスの TypeScript 型、クエリパラメータによるフィルタリング、キャッシュに関するガイダンス、一般的なパターン（ルートガード、動的 UI、「このアカウントで何ができるか」）
Unified API	統合 CRUD、メタエンドポイント、ページネーション、SuperQuery
プロキシとカスタム API	プロキシのパススルー、カスタムエンドポイント、カスタム API ハンドラーの作成、バッチリクエスト
認証	API トークン、リンクトークン、統合アカウントトークン、認証パターン
MCP トークン	MCP プロトコルトークン、メソッド／タグフィルター、tool_exposure: discovery、メソッドレベルの tool_tags、body 内の配列ボディ
接続フロー	接続のライフサイクル、アカウントの再接続、Webhook イベント、接続後の自動化
コアリソース	環境、インテグレーション、統合アカウント、テナント、チーム
統合アカウントのコンテキスト	コンテキストフィールドのライフサイクル、認証情報、インスタンス設定、API／同期／ワークフローでの使用

自動化とデータ移動

ドキュメント	トピック
同期ジョブ	同期ジョブ、実行、cron トリガー、テンプレート、実行状態
Webhook と通知	Webhook、通知先、インバウンド Webhook
データストア	同期ジョブの出力先となる外部ストレージ（MongoDB、GCS、S3、Qdrant）
ワークフロー	Truto のイベントによってトリガーされるイベント駆動型の自動化
デーモンジョブ	バックグラウンド処理タスクと実行

運用

ドキュメント	トピック
ファイルとログ	ファイルのアップロードと API／操作ログのクエリ
静的ゲート	アカウントの送信 API 呼び出し向け静的 IP エグレスプロキシ

関連スキル

• Truto CLI — セットアップタスク（インテグレーションの作成、テストアカウントの接続、リソースの調査、API 呼び出しのデバッグ）向けです。CLI はターミナルで実行する管理・デバッグツールです。このスキルは、アプリケーション内で使用するインテグレーションコード向けです。
• Truto Link SDK — @truto/truto-link-sdk（ポップアップモード、RapidForm、ファイルピッカー、エラー処理）を使用して、フロントエンドアプリケーションに Truto の接続 UI を埋め込むためのものです。
• truto-jsonata — Truto の設定内で JSONata 式を記述するためのものです。対象には、統合 API マッピングのオーバーライド（response_mapping、query_mapping、request_body_mapping、error_mapping など）、カスタム統合モデル定義、アカウントごとのオーバーライド、環境インテグレーションのオーバーライド（認証／ページネーション／レート制限／Webhook）、同期ジョブテンプレート、ワークフロー、デーモンジョブ、スケジュールされたアクションが含まれます。標準の JSONata に加えて @truto/truto-jsonata が追加するカスタム $ 関数について説明します。統合マッピングを変更する場合は、統合 API のカスタマイズと併用してください。式は truto jsonata eval を使ってローカルでテストできます（ローカルで反復するを参照）。