Rapid Translate API

引言

Rapid Translate API 可让您的应用程序提交文件进行认证翻译、查询最新的状态和报价，并接收完成的文件——而您的团队无需接触我们的结账流程。该 API 专为代表自身客户下达翻译订单的企业设计。

所有请求均应提交至 https://www.rapidtranslate.org/api/v1 通过 HTTPS 进行。请求和响应均为 JSON 格式，但创建订单时除外，该操作会将文件上传为 multipart/form-data. 所有金额均以 整数美分 单位为美元，所有时间戳均采用 UTC ISO‑8601 格式。

Postman 集合

在编写任何代码之前，更愿意先通过 API 进行测试吗？我们的 Postman 集合中，每个端点都已预先配置好——包括身份验证、示例请求体和查询参数。

下载 Postman 集合

1. 在 Postman 中，选择“文件”→“导入”，然后选择下载的文件。
2. 打开该收藏集的 变量 并设置 apiKey 从……到…… 企业设置 → API 密钥.
3. （可选）设置 baseUrl 适用于您的环境——默认设置为生产环境。
4. 请提交任何请求。使用沙箱密钥进行测试，无需下达计费订单。

身份验证

请使用您的私有 API 密钥作为承载令牌对每个请求进行身份验证，并请求 JSON 格式的响应。以下两个请求头均为必填项：

授权：Bearer YOUR_API_KEY
接受：application/json

您可以在仪表盘的“业务设置”→“API 密钥”下生成和轮换密钥。密钥在创建时会显示一次，并以哈希形式存储——如果丢失了密钥，请进行轮换。每个密钥属于一种模式（生产环境或沙箱环境），并具有一组固定的权限范围。

范围

每个端点都需要密钥具备特定的权限。如果密钥缺少所需的权限范围，则返回 403 禁止访问_scope.

沙盒与测试模式

测试模式是密钥的属性，而非您账户的属性。沙盒密钥在完全模拟的环境中运行；生产密钥则会下达真实的、需付费的订单。您可以同时使用这两种密钥。

沙箱订单采用相同的验证、字段映射和实际定价，但省略了文件存储、OCR 和订单履行环节。创建后，沙箱订单会自动经历其生命周期（处理中 → 已完成)，触发与真实订单相同的 webhook，最后返回一份静态示例文档。

每个响应和 Webhook 都携带一个 livemode 添加此标记，以便您的集成可以在不检查密钥的情况下进行分支：

• livemode: true — 真实的、可计费的订单
• livemode: false — 测试环境 / 测试订单

速率限制

每个组织的请求都受到速率限制。默认配额为 每分钟120次请求. 超出该值将返回 429 rate_limited; 稍作等待后重试。如果您的集成需要更高的限制，请联系 support@rapidtranslate.org.

回复

每个成功的响应都会将有效载荷封装在一个 数据 key。列出端点，添加一个 元数据 带分页的区块。

单一资源

{
  "data": {
    "id": "9b1c...-uuid",
    "reference": "APO-10432",
    "status": "processing",
    "total": 11270,
    "currency": "USD"
  }
}

分页列表

{
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 134,
    "last_page": 6
  }
}

错误

错误使用标准的 HTTP 状态码，并返回一个稳定的、机器可读的 error_code 并附带一条人工信息。验证错误会添加一个以字段为键的 错误 对象。

{
  "message": "The given data was invalid.",
  "error_code": "validation_failed",
  "errors": {
    "source_language": ["The selected source language is invalid."]
  }
}

订单状态

一个订单的 状态 遵循一个稳定的生命周期。这五个价值观也是被 状态 按……筛选 列出订单:

在订单处理过程中，会生成更细粒度的标签（例如 已分配给译员, 翻译, 已发货) 也可能出现。当需要批准时，订单可能会简要说明 支付失败 或 credit_hold 如果无法收取费用——请确定付款方式并重新批准。

字段值

创建订单时接受的固定组合。

翻译类型

扭亏为盈

配送方式

Webhooks

与其使用轮询，不如配置一个 webhook 端点，以便在事件发生时实时接收。请在“业务设置”→“Webhooks”中设置您的 URL 并查看签名密钥。Webhooks 非常方便——通过它获取订单的信息始终具有权威性。

活动

信封

每份快递都用同样的信封：一个 活动 块（包括 livemode) 以及针对特定事件的 数据 块。

{
  "event": {
    "type": "order_status",
    "id": "evt_9b1c...",
    "livemode": true,
    "sent_at": "2026-08-28T10:20:00+00:00"
  },
  "data": {
    "order": {
      "id": "9b1c2d3e-...-uuid",
      "reference": "APO-10432",
      "status": "completed"
    }
  }
}

该 文献传递 事件会添加一个 文件 数组（每个数组包含 名称, 下载链接, 版本, 状态) 和一个 门户 链接。该 客户评价 event 添加了一项明细 定价 块和一个 actions.approve 包含要调用的 URL 的对象。

验证签名

每个请求都经过签名，因此您可以确认它确实来自Rapid Translate 。我们会发送三个请求头：

将该字符串作为 HMAC-SHA256 进行计算，得出预期签名 "{timestamp}.{raw_request_body}" 使用您的 Webhook 签名密钥，然后将其与标头值进行比较：

// PHP
$expected = 'sha256=' . hash_hmac(
    'sha256',
    $timestamp . '.' . $rawBody,
    $webhookSecret
);
$valid = hash_equals($expected, $signatureHeader);

Node.js (Express) — 使用原始正文解析器挂载路由，以保留精确的字节内容：

// app.use('/webhooks/rapidtranslate', express.raw({ type: 'application/json' }))
const crypto = require('crypto');

const timestamp = req.get('X-RapidTranslate-Timestamp');
const received  = req.get('X-RapidTranslate-Signature'); // "sha256=..."
const rawBody   = req.body;                               // Buffer, untouched

const expected = 'sha256=' + crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex');

const valid = received &&
  crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

有三件事容易让人犯错：

• 该 X-RapidTranslate-Signature 标题包含一个 sha256= 前缀。要么与……进行比较 'sha256=' + yourHmac （同上）或者在比较前去除前缀——不要将裸的十六进制数与整个头信息进行比对。
• 将原始请求正文按接收时的原样进行哈希处理。解析后的 JSON 重新序列化会改变空格和键的顺序，导致签名不匹配——请在任何 JSON 中间件解析正文之前先读取正文。
• 在常数时间内进行比较（hash_equals / crypto.timingSafeEqual)，绝不与 == 或 ===.

该 {timestamp} 是签名字符串的一部分，因此请从头部读取该字符串，并在进行哈希运算前将其添加到字符串开头。此外，这还能让你拒绝过期或被重放的交付——例如，任何时间戳早于五分钟的交付。

发送失败时，将采用指数退避算法重试（最多尝试 5 次）。请回复一个 2xx 状态：已收悉。