truto

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Truto — Unified API Platform

Truto — 统一API平台

Use this skill when writing code in the user's application that calls the Truto API. This skill helps you build integration features — API calls, webhook handlers, connection UIs, and data-access layers — that run as part of the user's product.

This skill is about code that lives in the user's codebase. For admin setup, one-time debugging, and data exploration in the terminal, see the Truto CLI skill instead.

Important: The Truto API token (

TRUTO_API_TOKEN

) must only be used on the backend. Never expose it to the browser or include it in client-side code.

当你在用户应用中编写调用Truto API的代码时，可以使用此技能。该技能可帮助你构建作为用户产品一部分运行的集成功能——包括API调用、Webhook处理器、连接UI和数据访问层。

本技能聚焦于用户代码库中的代码。如需进行管理员设置、一次性调试或终端中的数据探索，请查看Truto CLI技能。

重要提示：Truto API令牌（

TRUTO_API_TOKEN

）只能在后端使用。绝不能将其暴露给浏览器或包含在客户端代码中。

When to Use

使用场景

Writing API calls to read or write data through Truto (unified, proxy, or custom APIs)
Building a connection flow for end-users using Truto Link
Adding webhook handlers to receive real-time events from Truto
Implementing pagination, error handling, or retry logic for Truto API calls
Choosing between unified, proxy, and custom APIs for a use case

编写通过Truto读取或写入数据的API调用（统一API、代理API或自定义API）
使用Truto Link为终端用户构建连接流程
添加Webhook处理器以接收来自Truto的实时事件
为Truto API调用实现分页、错误处理或重试逻辑
根据使用场景选择统一API、代理API或自定义API

Install the Truto CLI (recommended)

安装Truto CLI（推荐）

Before writing any code, install the Truto CLI — it's the fastest way to discover what an integration supports, connect a sandbox account, and try a unified API call without touching your application. Every workflow in this skill (calling the unified API, customizing mappings, overriding integrations per environment, debugging webhooks) has a CLI shortcut you can run in a single line, then port into code once it works.

bash

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

For the full command surface, output formats, and admin workflows, see the Truto CLI skill. For a guided Day-1 walkthrough that combines the CLI with the code in this skill, see Getting Started.

在编写任何代码之前，请安装Truto CLI——这是快速了解集成支持内容、连接沙箱账户并在不修改应用的情况下尝试统一API调用的最快方式。本技能中的每个工作流（调用统一API、自定义映射、按环境覆盖集成、调试Webhook）都有一个可通过单行命令运行的CLI快捷方式，待验证可用后再移植到代码中。

bash

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

如需完整的命令列表、输出格式和管理员工作流，请查看Truto CLI技能。如需结合CLI与本技能代码的入门引导，请查看快速开始。

Core Concepts

核心概念

Concept	Description	Reference
Environment	Isolated workspace scoping all resources. API tokens are tied to one environment.	Core Resources
Integration	A third-party tool definition (e.g., Salesforce, Jira, Slack).	Core Resources
Environment Integration	An integration installed into a specific environment with optional config overrides.	Core Resources
Integrated Account	A connected instance of an integration for a specific tenant (end-user).	Core Resources
Tenant	Your end-user or customer, identified by `tenant_id` on integrated accounts.	Core Resources
Unified API	Standardized CRUD endpoints across integrations using a common schema.	Unified API
Proxy API	Pass-through to the native API of the underlying tool.	Proxy & Custom API
Custom API	User-defined API endpoints with custom routing logic.	Proxy & Custom API
Sync Job	Scheduled or on-demand data synchronization from integrated accounts.	Sync Jobs
Webhook	HTTP callbacks for real-time event notifications.	Webhooks & Notifications
Datastore	External storage destinations (MongoDB, GCS, S3, Qdrant) for sync job output.	Datastores
Workflow	Event-driven automation triggered by Truto events.	Workflows

概念	描述	参考链接
Environment（环境）	隔离的工作区，用于限定所有资源的作用范围。API令牌与单个环境绑定。	核心资源
Integration（集成）	第三方工具的定义（例如Salesforce、Jira、Slack）。	核心资源
Environment Integration（环境集成）	安装到特定环境中的集成，可选择配置覆盖。	核心资源
Integrated Account（集成账户）	针对特定租户（终端用户）的已连接集成实例。	核心资源
Tenant（租户）	你的终端用户或客户，通过集成账户上的 `tenant_id` 标识。	核心资源
Unified API（统一API）	跨集成的标准化CRUD端点，使用通用 schema。	统一API
Proxy API（代理API）	直通底层工具的原生API。	代理与自定义API
Custom API（自定义API）	带有自定义路由逻辑的用户定义API端点。	代理与自定义API
Sync Job（同步任务）	针对集成账户的定时或按需数据同步。	同步任务
Webhook	用于实时事件通知的HTTP回调。	Webhook与通知
Datastore（数据存储）	同步任务输出的外部存储目标（MongoDB、GCS、S3、Qdrant）。	数据存储
Workflow（工作流）	由Truto事件触发的事件驱动自动化。	工作流

Getting Started

快速开始

Day 0 — install the CLI first (see Install the Truto CLI above). Most of what's described below is faster to try through the Truto CLI before wiring it into code, then port the same call into your application. The full Day-1 walkthrough lives at Getting Started; the steps below are the canonical flow you'll port into your application.

第0天 — 先安装CLI（见上方安装Truto CLI）。下面描述的大部分操作通过Truto CLI尝试会比直接编写代码更快，验证可用后再移植到应用中。完整的入门引导请查看快速开始；以下是你将移植到应用中的标准流程。

1. Get an API Token

1. 获取API令牌

Create an API token in the Truto Dashboard. API tokens can only be created through the dashboard — not via the API or CLI.

Store it as a server-side environment variable (

TRUTO_API_TOKEN

). This token must only be used on the backend — never send it to the browser.

在Truto控制台中创建API令牌。API令牌只能通过控制台创建——无法通过API或CLI创建。

将其存储为服务端环境变量（

TRUTO_API_TOKEN

）。此令牌只能在后端使用——绝不能发送到浏览器。

2. Create a Backend Route for Link Tokens

2. 创建用于生成Link Token的后端路由

Your backend needs an endpoint that generates link tokens for the Truto Link connection flow. This route should handle both new connections and reconnections from the start — this prevents users from creating duplicate accounts when an existing connection fails.

typescript

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

The shape is the same in every framework — a server-side

fetch

POST /link-token

carrying the API token. Getting Started has the same route written for Next.js Route Handlers and Hono / Cloudflare Workers; pick the variant that matches your stack and adapt the snippet.

When reconnecting, pass

integrated_account_id

instead of

tenant_id

. This updates the existing account's credentials in place — the same

integrated_account_id

is preserved, so all sync jobs, webhooks, and references remain intact. Setting

persist_previous_context: true

keeps any custom context from the previous connection.

你的后端需要一个端点，为Truto Link连接流程生成链接令牌。该路由应同时处理新连接和重新连接——这样可以避免现有连接失败时用户创建重复账户。

typescript

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

  // 重新连接现有账户，或创建新账户
  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路由处理器和Hono / Cloudflare Workers的相同路由代码；选择与你的技术栈匹配的变体并调整代码片段。

重新连接时，传递

integrated_account_id

而非

tenant_id

。这会就地更新现有账户的凭据——保留相同的

integrated_account_id

，因此所有同步任务、Webhook和引用都保持不变。设置

persist_previous_context: true

可保留之前连接中的所有自定义上下文。

3. Embed Truto Link in Your Frontend

3. 在前端嵌入Truto Link

Install the Truto Link SDK to embed the connection flow in your UI:

bash

npm install @truto/truto-link-sdk

Then use it in your frontend. The same

authenticate()

call works for both new connections and reconnections — the difference is in the link token your backend generates:

typescript

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

See the Truto Link SDK skill for the full SDK reference, including popup mode, same-window redirects, RapidForm, file pickers, and error handling.

安装Truto Link SDK以在UI中嵌入连接流程：

bash

npm install @truto/truto-link-sdk

然后在前端中使用它。相同的

authenticate()

调用适用于新连接和重新连接——区别在于后端生成的链接令牌：

typescript

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("已连接:", result.integrated_account_id);
    return result;
  } catch (err) {
    if (err === "closed") {
      console.log("用户关闭了连接对话框");
    } else {
      console.error("连接失败:", err);
    }
    throw err;
  }
}

// 新连接
const linkToken = await getLinkToken({ tenantId: "tenant-123" });
await openTrutoLink(linkToken);

// 重新连接现有账户（例如OAuth令牌过期）
const reconnectToken = await getLinkToken({ integratedAccountId: "existing-account-id" });
await openTrutoLink(reconnectToken);

如需完整的SDK参考（包括弹窗模式、同窗口重定向、RapidForm、文件选择器和错误处理），请查看Truto Link SDK技能。

4. Listen for the Account to Become Active

4. 监听账户变为活跃状态

After a user connects, the account goes through post-install and validation steps before it's ready. Set up a webhook to listen for the

integrated_account:active

event — this tells you the account is connected and ready for API calls. See Connection Flow for the full lifecycle and all events.

typescript

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

  switch (event.event_type) {
    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);
});

You can also use Truto Workflows to automatically trigger actions (like starting a sync job) when an account becomes active. See Workflows for details.

Tip while developing. You don't need to wait for the webhook to grab a working
integrated_account_id
— list connected accounts from the CLI with
truto accounts list -o json
(or filter to sandboxes with
--is_sandbox true
) and copy one out. Use that ID to test the unified-API steps below before the webhook plumbing is in place.

用户连接后，账户需要完成安装后步骤和验证才能就绪。设置Webhook以监听

integrated_account:active

事件——这表示账户已连接并可进行API调用。如需完整的生命周期和所有事件，请查看连接流程。

typescript

// 后端Webhook处理器
app.post("/webhooks/truto", async (req, res) => {
  const event = req.body;

  switch (event.event_type) {
    case "integrated_account:active":
      // 账户已就绪 — 存储integrated_account_id，
      // 开始同步数据，为该租户启用功能
      await onAccountReady(event.payload);
      break;

    case "integrated_account:post_install_error":
    case "integrated_account:validation_error":
      // 连接失败 — 通知用户或重试
      await onAccountError(event.payload);
      break;
  }

  res.sendStatus(200);
});

你也可以使用Truto工作流在账户变为活跃时自动触发操作（例如启动同步任务）。详情请查看工作流。

开发提示：你无需等待Webhook即可获取可用的
integrated_account_id
——通过CLI运行
truto accounts list -o json
列出已连接账户（或使用
--is_sandbox true
筛选沙箱账户）并复制一个ID。在完成Webhook配置之前，使用该ID测试下面的统一API步骤。

5. Read Data via the Unified API

5. 通过统一API读取数据

Once an account is active, fetch normalized data:

typescript

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

账户活跃后，获取标准化数据：

typescript

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. Write Data

6. 写入数据

typescript

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: "jane@example.com",
    }),
  }
);

typescript

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: "jane@example.com",
    }),
  }
);

7. Use the Proxy API for Native Access

7. 使用代理API进行原生访问

When you need integration-specific fields not in the unified schema:

typescript

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

当你需要统一schema中未包含的集成特定字段时：

typescript

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

When to Use Unified vs Proxy vs Custom API

统一API、代理API与自定义API的使用场景对比

Use Case	API	Why
Standardized CRUD across integrations	Unified	Same request/response schema regardless of the underlying tool
Access native API features not in unified schema	Proxy	Full access to the tool's native endpoints
Custom business logic or transformations	Custom	Define your own endpoints with custom routing
Bulk data operations with dependencies	Batch Request	Execute multiple API calls with dependency graph in one request

使用场景	API类型	原因
跨集成的标准化CRUD操作	统一API	无论底层工具是什么，请求/响应schema保持一致
访问统一schema中未包含的原生API特性	代理API	完全访问工具的原生端点
自定义业务逻辑或转换	自定义API	定义带有自定义路由的自有端点
带有依赖关系的批量数据操作	批量请求	在一个请求中执行多个带有依赖关系的API调用

Authentication

认证

All API requests use Bearer token authentication. The API token must only be used server-side. See Authentication for details on API tokens, link tokens, and integrated account tokens.

所有API请求使用Bearer令牌认证。API令牌只能在服务端使用。如需了解API令牌、链接令牌和集成账户令牌的详情，请查看认证。

References

参考文档

Start here

入门首选

Document	Topics
Getting Started	Day-1 tutorial: CLI install → login → connect a sandbox → write the link-token route → first unified API call → port the same call into code

文档	主题
快速开始	入门教程：CLI安装 → 登录 → 连接沙箱 → 编写链接令牌路由 → 首次统一API调用 → 将调用移植到代码中

Customization (the most-used "extend the platform" surfaces)

自定义扩展（最常用的平台扩展方式）

Document	Topics
Authoring Integrations	Author a brand-new integration definition from scratch: full `integration.config` schema, all five credential formats, resources/methods, pagination, rate-limit, inbound webhook receiver, lifecycle actions, plus `truto integrations init/validate/create` workflow and an Acme CRM worked example
Customizing Integrations	Per-environment HTTP-layer overrides on an existing integration: auth header, pagination, rate-limit detection, inbound webhook verification/transform
Unified API Customization	Modifying existing unified API mappings per environment, per-account overrides, creating your own custom unified models

文档	主题
编写集成	从头编写全新的集成定义：完整的 `integration.config` schema、五种凭证格式、资源/方法、分页、速率限制、入站Webhook接收器、生命周期操作，以及 `truto integrations init/validate/create` 工作流和Acme CRM示例
自定义集成	对现有集成进行按环境的HTTP层覆盖：认证头、分页、速率限制检测、入站Webhook验证/转换
统一API自定义	按环境、按账户修改现有统一API映射，创建自有自定义统一模型

Core API surface

核心API接口

Document	Topics
Unified API	Unified CRUD, meta endpoints, pagination, SuperQuery
Proxy & Custom API	Proxy pass-through, custom endpoints, authoring custom-API handlers, batch requests
Authentication	API tokens, link tokens, integrated account tokens, auth patterns
MCP Tokens	MCP protocol tokens for AI agents, tool filtering, expiration
Connection Flow	Connection lifecycle, reconnecting accounts, webhook events, post-connection automation
Core Resources	Environments, integrations, integrated accounts, teams
Integrated Account Context	Context field lifecycle, credentials, instance config, usage in APIs/sync/workflows

文档	主题
统一API	统一CRUD、元端点、分页、SuperQuery
代理与自定义API	代理直通、自定义端点、编写自定义API处理器、批量请求
认证	API令牌、链接令牌、集成账户令牌、认证模式
MCP令牌	用于AI Agent的MCP协议令牌、工具筛选、过期
连接流程	连接生命周期、账户重新连接、Webhook事件、连接后自动化
核心资源	环境、集成、集成账户、团队
集成账户上下文	上下文字段生命周期、凭证、实例配置、在API/同步/工作流中的使用

Automation & data movement

自动化与数据流转

Document	Topics
Sync Jobs	Sync jobs, runs, cron triggers, templates, run state
Webhooks & Notifications	Webhooks, notification destinations, inbound webhooks
Datastores	External storage destinations (MongoDB, GCS, S3, Qdrant) for sync job output
Workflows	Event-driven automations triggered by Truto events
Daemon Jobs	Background processing tasks and runs

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

Operational

运维相关

Document	Topics
Files & Logs	File uploads and API/operation log queries
Static Gates	Embeddable connection entry points

文档	主题
文件与日志	文件上传与API/操作日志查询
静态入口	可嵌入的连接入口点

Companion Skills

配套技能

Truto CLI — for setup tasks (creating integrations, connecting test accounts, exploring resources, debugging API calls). The CLI is an admin and debugging tool you run in the terminal; this skill is for the integration code that lives in your application.
Truto Link SDK — for embedding the Truto connection UI in a frontend application using
```
@truto/truto-link-sdk
```
(popup mode, RapidForm, file pickers, error handling).
truto-jsonata — for writing JSONata expressions inside Truto config: unified API mapping overrides (
```
response_mapping
```
,
```
query_mapping
```
,
```
request_body_mapping
```
,
```
error_mapping
```
, etc.), custom unified model definitions, per-account overrides, environment integration overrides (auth/pagination/rate-limit/webhooks), sync job templates, workflows, daemon jobs, and scheduled actions. Documents the custom
```
$
```
functions added by
```
@truto/truto-jsonata
```
on top of standard JSONata. Pair with Unified API Customization when modifying unified mappings.

Truto CLI — 用于设置任务（创建集成、连接测试账户、探索资源、调试API调用）。CLI是你在终端中运行的管理员和调试工具；本技能聚焦于应用中的集成代码。
Truto Link SDK — 使用
```
@truto/truto-link-sdk
```
在前端应用中嵌入Truto连接UI（弹窗模式、RapidForm、文件选择器、错误处理）。
truto-jsonata — 用于在Truto配置中编写JSONata表达式：统一API映射覆盖（
```
response_mapping
```
、
```
query_mapping
```
、
```
request_body_mapping
```
、
```
error_mapping
```
等）、自定义统一模型定义、按账户覆盖、环境集成覆盖（认证/分页/速率限制/Webhook）、同步任务模板、工作流、守护任务和定时操作。记录了
```
@truto/truto-jsonata
```
在标准JSONata基础上添加的自定义
```
$
```
函数。修改统一映射时，请与统一API自定义配合使用。