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”问题
• 编写 API 调用，通过 Truto 读取或写入数据（统一 API、代理 API 或自定义 API）
• 使用 Truto Link 为最终用户构建连接流程
• 添加 Webhook 处理程序，以接收来自 Truto 的实时事件
• 为 Truto API 调用实现分页、错误处理或重试逻辑
• 根据具体使用场景，在统一 API、代理 API 和自定义 API 之间进行选择

安装 Truto CLI（推荐）

Truto CLI 是探索集成支持的功能、连接沙盒账户，以及在不触碰应用程序的情况下尝试统一 API 调用的最快方式。当用户想要在终端中探索或测试时，建议使用它。本技能中的每种工作流（调用统一 API、自定义映射、按环境覆盖集成、调试 Webhook）都有对应的 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 和本技能代码的引导式 Day-1 演练，请参阅快速入门。

核心概念

概念	描述	参考
环境	用于限定所有资源范围的隔离工作区。API 令牌与单个环境绑定。	核心资源
集成	第三方工具定义（例如 Salesforce、Jira、Slack）。	核心资源
环境集成	安装到特定环境中的集成，可选择覆盖配置。	核心资源
已集成账户	为特定租户（最终用户）连接的集成实例。	核心资源
租户	由环境限定范围的外部身份（你的客户 / 最终用户），拥有已集成账户。通过 /tenant 管理——可显式创建，也可在首次连接时自动创建。	核心资源
统一 API	使用通用架构，为各类集成提供标准化 CRUD 端点。	统一 API
代理 API	直通底层工具的原生 API。	代理与自定义 API
自定义 API	用户定义的 API 端点，带有自定义路由逻辑。	代理与自定义 API
同步任务	从已集成账户定时或按需同步数据。	同步任务
Webhook	用于实时事件通知的 HTTP 回调。	Webhook 与通知
数据存储	用于存储同步任务输出的外部存储目标（MongoDB、GCS、S3、Qdrant）。	数据存储
工作流	由 Truto 事件触发的事件驱动型自动化。	工作流

调用前发现功能

每当你准备对 /unified/...、/proxy/... 或 /custom/... 发起 fetch() 时，先调用 capabilities 端点。 资源和方法名称因集成而异（HubSpot 有 contacts/companies/deals，Bigcommerce 有 products/orders/customers 等）。凭记忆硬编码这些名称，是 Truto 集成代码中最常见的 LLM 引入的错误；capabilities 是唯一可信来源。

有两个等效端点，返回相同结构：

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}` } }
  );
}

capabilities 响应开销低，且在每个集成版本内保持稳定。在服务端按 integration_id 缓存（完整参考、查询参数过滤器、缓存指南以及两个端点的使用模式，请参阅发现功能）。配套的 CLI 命令是 truto capabilities <slug-or-uuid>——返回相同结构，可先在终端中即时试用，再移植到代码中。

开始使用

想先试用？ 将下文所述内容接入代码之前，通过 Truto CLI（参阅上文的安装 Truto CLI）试用大多数功能会更快，然后将相同的调用移植到应用中。完整的 Day-1 演练请参阅开始使用；下列步骤是移植到应用中的标准流程。

1. 获取 API 令牌

在 Truto Dashboard 中创建 API 令牌。API 令牌只能通过 Dashboard 创建，不能通过 API 或 CLI 创建。

将其存储为服务端环境变量（TRUTO_API_TOKEN）。此令牌只能在后端使用，切勿发送给浏览器。

2. 创建用于 Link 令牌的后端路由

你的后端需要一个端点，用于为 Truto Link 连接流程生成 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 });
});

所有框架中的结构都相同——在服务端执行 fetch，向 POST /link-token 发送 API 令牌。开始使用提供了适用于 Next.js Route Handlers 和 Hono / Cloudflare Workers 的相同路由；选择与你的技术栈匹配的变体，并调整代码片段。

重新连接时，传递 integrated_account_id，而不是 tenant_id。这会原地更新现有账户的凭据，并保留相同的 integrated_account_id，因此所有同步作业、Webhook 和引用都会保持不变。设置 persist_previous_context: true 可保留之前连接中的自定义上下文。

3. 在前端嵌入 Truto Link

安装 Truto Link SDK，将连接流程嵌入 UI：

npm install @truto/truto-link-sdk

然后在前端使用它。新建连接和重新连接都使用相同的 authenticate() 调用，区别在于后端生成的 Link 令牌：

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);

完整 SDK 参考请参阅 Truto Link SDK skill，其中包括弹出窗口模式、同窗口重定向、RapidForm、文件选择器和错误处理。

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，在账户变为活跃状态时自动触发操作（例如启动同步任务）。详情请参阅工作流。

开发期间的提示。 你无需等待 webhook 就能获取可用的 integrated_account_id——使用 CLI 运行 truto accounts list -o json 列出已连接的账户（或使用 --is_sandbox true 筛选沙盒账户），然后复制一个 ID。使用该 ID，在 webhook 配置就绪之前测试下方的统一 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	统一 API	无论底层工具是什么，请求和响应架构都相同
访问统一架构中没有的原生 API 功能	代理 API	可完整访问工具的原生端点
自定义业务逻辑或转换	自定义 API	使用自定义路由定义自己的端点
处理带依赖关系的批量数据操作	批量请求	在一个请求中，按依赖关系图执行多个 API 调用

身份验证

所有 API 请求均使用 Bearer 令牌身份验证。API 令牌只能在服务端使用。有关 API 令牌、链接令牌和集成账户令牌的详情，请参阅身份验证。

参考资料

从这里开始

文档	主题
入门指南	第一天教程：安装 CLI → 登录 → 连接沙盒 → 编写链接令牌路由 → 首次统一 API 调用 → 将同一调用移植到代码中

自定义（最常用的“扩展平台”入口）

文档	主题
编写集成	从头编写全新的集成定义：完整的 integration.config 架构、全部五种凭据格式、资源/方法、分页、速率限制、入站 Webhook 接收器、生命周期操作，以及 truto integrations init/validate/create 工作流和 Acme CRM 完整示例
自定义集成	按环境覆盖 HTTP 层：身份验证、分页、速率限制、Webhook 和 override.resources。API 和 CLI 的 update 会整体替换 override——请始终发送完整对象；override-* 助手会为你获取并合并一个槽位
统一 API 自定义	按环境修改现有的统一 API 映射、按账户覆盖，以及创建自己的自定义统一模型

核心 API 入口

文档	主题
发现功能	编写数据访问代码时请先阅读。 /integration/<slug>/capabilities 和 /integrated-account/<id>/capabilities 端点、响应 TypeScript 类型、查询参数筛选、缓存指南、常见模式（路由守卫、动态 UI、“此账户能做什么？”）
统一 API	统一 CRUD、元端点、分页、SuperQuery
代理与自定义 API	代理透传、自定义端点、编写自定义 API 处理程序、批量请求
身份验证	API 令牌、链接令牌、集成账户令牌、身份验证模式
MCP 令牌	MCP 协议令牌；方法/标签筛选；tool_exposure: discovery；方法级 tool_tags；body 下的数组请求体
连接流程	连接生命周期、重新连接账户、Webhook 事件、连接后的自动化
核心资源	环境、集成、集成账户、租户、团队
集成账户上下文	上下文字段生命周期、凭据、实例配置，以及在 API/同步/工作流中的用法

自动化与数据传输

文档	主题
同步任务	同步任务、运行、Cron 触发器、模板、运行状态
Webhooks 与通知	Webhooks、通知目标、入站 Webhooks
数据存储	用于存储同步任务输出的外部存储目标（MongoDB、GCS、S3、Qdrant）
工作流	由 Truto 事件触发的事件驱动自动化
守护进程任务	后台处理任务与运行

运维

文档	主题
文件与日志	文件上传以及 API／操作日志查询
静态网关	用于账户出站 API 调用的静态 IP 出口代理

配套技能

• Truto CLI — 用于设置任务（创建集成、连接测试账户、探索资源、调试 API 调用）。CLI 是你在终端中运行的管理和调试工具；此技能则用于位于应用程序中的集成代码。
• Truto Link SDK — 用于在前端应用程序中嵌入 Truto 连接界面，使用 @truto/truto-link-sdk（弹出模式、RapidForm、文件选择器、错误处理）。
• truto-jsonata — 用于在 Truto 配置中编写 JSONata 表达式：统一 API 映射覆盖项（response_mapping、query_mapping、request_body_mapping、error_mapping 等）、自定义统一模型定义、按账户覆盖项、环境集成覆盖项（身份验证／分页／速率限制／webhooks）、同步任务模板、工作流、守护进程任务和计划操作。介绍 @truto/truto-jsonata 在标准 JSONata 基础上添加的自定义 $ 函数。修改统一映射时，请配合使用统一 API 自定义——使用 truto jsonata eval 在本地测试任何表达式（参见在本地迭代）。