3Min API
菜单路径: 仪表盘 > APIs > 端点名称

端点详情

概述

端点详情是处理单个端点所有设置的页面。在这一个页面上您可以：

  • 查看和编辑端点信息（名称、描述、URL、版本）
  • 切换激活 / 停用
  • 部署和重新部署到生产环境
  • 管理默认 API 密钥
  • 添加和删除必填字段
  • 配置 Webhook
  • 删除端点

协作密钥管理（签发密钥、邀请、权限）在单独的页面处理。详情请参阅协作密钥。

如果您以协作者身份参与，只会显示您有权限访问的部分（所有者专属部分自动隐藏）。

如何进入

端点列表页

  • 顶部菜单 APIs → 点击列表中的端点名称
  • 仪表盘最近活动 → 点击端点
  • 完成新手引导步骤 1 后自动跳转

免费套餐警告横幅

免费套餐横幅

使用免费套餐时显示在顶部。免费套餐下可以随意创建和试用端点。端点会在创建 7 天后自动清理，但您随时可以创建新的——放心尝试。

激活/停用和部署按钮

页眉操作区域

仅所有者可见。

  • 激活/停用按钮（电源图标）：当您想要临时暂停所有环境的 API 调用时使用。停用期间调用被拒绝，但数据保留。
  • 部署到生产环境 按钮（仅沙盒环境标签页）：
    • 将当前沙盒环境设置复制到生产环境
    • 条件：必须在沙盒环境中完成至少 1 次测试调用后才可激活

如果协作者访问此页面，会显示 请求部署 按钮，向所有者发送部署请求消息。

环境标签页

环境标签页

页眉栏下方有 沙盒环境 | 生产环境 标签页。两个环境完全独立。

推荐的工作流程是：在沙盒环境中测试并与协作者讨论 → 部署到生产环境 → 运营。需要变更时，先在沙盒环境修改再重新部署。

沙盒环境

  • 使用沙盒环境 API 密钥（tm_test_）调用的环境
  • 仅用于测试。上线前可以自由试验
  • 沙盒环境数据30 天后自动删除（所有套餐）

生产环境

  • 使用生产环境 API 密钥（tm_live_）调用的环境
  • 用于正式运营。记录至少保留 30 天，之后按月整批删除。需要长期保存的数据请通过 Webhook 或列表 API 在记录到达时导出
  • 生产环境部署前，生产环境密钥调用将被拒绝且不记录日志

概览卡片

概览卡片

包含端点基本信息的区域。

项目 说明
描述 端点描述。所有者可在沙盒环境标签页内联编辑
端点 URL 实际 API 调用地址。**向此 URL 发送 POST/GET/PUT/DELETE 请求。**提供复制按钮
版本 配置版本。每次部署递增
创建时间 端点创建时间
更新时间 最后一次设置变更时间（沙盒环境）
发布时间 生产环境部署时间（仅生产环境标签页）

默认 API 密钥

仅所有者可见。

默认 API 密钥

  • 端点创建时签发的默认 API 密钥
  • 用于测试与集成指南页面的认证，可通过右侧的立即测试按钮访问
  • 显示 / 隐藏 切换，在屏幕上隐藏或显示密钥
  • 重新生成 按钮：旧密钥立即失效。仅在怀疑泄露时使用

协作者访问时，此区域替换为其分配的协作密钥卡片。

协作密钥

协作密钥

此处仅提供摘要卡片——密钥创建、邀请和权限管理在单独的管理页面进行。

  • 所有者视图：查看全部 按钮和每个协作者的摘要（名称、邀请数）
  • 协作者视图：分配给您的密钥的权限标签

详细说明请参阅协作密钥。

必填字段

必填字段

定义 API 调用中必须包含的 JSON 字段。详细说明请参阅创建新端点。

  • 要添加或编辑字段，点击 编辑 按钮
  • 编辑时可以添加、删除和更改字段类型。完成后点击 保存 或 取消
  • 保存后更新沙盒环境配置——要应用到生产环境，需要重新部署
  • 即使部署后，修改必填字段不影响已存储的数据。更新的字段规则仅适用于新的传入调用

Webhook

仅所有者可见。

Webhook 设置

API 调用成功处理后，可以向指定的 Webhook URL 发送二次请求。无论 Webhook 是否成功，数据存储始终完成。

输入字段

  • Webhook URL：接收 Webhook 的地址（推荐 HTTPS）
  • Auth Header（可选）：认证头键。默认 Authorization
  • Auth Value（可选）：认证头值。示例：Bearer abc123

对于不需要认证的 Webhook（简单接收器、URL 中嵌入 Token 等），留空认证字段即可。

Webhook 策略摘要

  • 超时：必须在 15 秒内响应。超时视为失败
  • 响应状态码：2xx 表示"我收到了"，而不是"处理成功了"。即使你这边的处理失败也要返回 2xx，并把该失败记录在你自己的系统里。5xx 表示投递根本没有送达，我们会按下方的重试计划反复重发同一条记录，你的接收端每次都会把同一份工作再执行一遍
  • 重试：生产环境共 6 次尝试——首次投递 1 次 + 重试 5 次（30 秒·2 分·10 分·1 小时·4 小时，约 5 小时）。沙箱环境共 4 次尝试——首次投递 1 次 + 重试 3 次（30 秒·2 分·10 分，约 12 分钟）
  • 会重试：5xx、429、超时、连接错误。若 429 附带 Retry-After，我们会相应地多等一段时间（不会短于默认间隔）
  • 不重试：除 429 外的所有 4xx，包括 409。修正设置后，下次调用即可正常送达
  • 查看失败：投递失败或仍在重试的记录会出现在日志页面的 Webhook 投递中。成功送达的 Webhook 不会被记录
  • 邮件通知：一旦放弃投递（重试用尽，或永久性响应），我们会发邮件通知您，不分套餐（免费套餐同样适用），但仅限生产环境 Webhook，每个端点每天最多一封，且没有恢复通知。协作者 Webhook 的失败不会发送邮件——因为您无法更改该 URL
  • 幂等性：每次尝试都携带相同的 X-3minapi-Record-Id。请用它判断重复
  • 签名：每个请求都带有 HMAC-SHA256 签名（webhook-signature）。详情请参见下方的 Webhook 签名密钥

Webhook 签名密钥

位于 Webhook 设置卡片正下方。它不是所有者专属区域，协作者同样可以查看 — 因为协作者通过 X-Webhook-Callback 自行接收的 Webhook 也使用同一个密钥签名。

  • 按环境区分 — 沙箱标签页和生产标签页的密钥各自独立。请使用你所接收环境的那一个
  • 所有者和协作者都可以查看
  • 只有所有者可以重新签发（轮换）。 协作者的界面上不会出现重新签发按钮
  • 这不是需要定期轮换的值。 重新签发是密钥泄露时的应对手段
  • 重新签发后，24 小时内会同时发送新旧两个签名。在这段时间内的任意时刻更换接收服务器上的值，都不会丢失投递。宽限期内卡片上会显示到期时间横幅

拿到这个值之后该怎么用，请参见验证 Webhook 签名。

Webhook Payload

API 调用处理后，以下 JSON Payload 将发送到 Webhook URL。您可以展开截图中的 Webhook Payload 示例 区域查看实际格式。

字段 说明
id 存储记录的唯一 ID
operation 执行的操作（create、update、delete）
status 处理结果（success、failed）
endpoint_slug 端点标识符
payload 调用者发送的原始 JSON 数据，原样包含（delete 时为 null）
target_record_id 目标记录 ID（update/delete 时包含）
processed_at 处理完成时间

协作者 Webhook

如果协作者需要 Webhook，可以在 API 请求中包含 X-Webhook-Callback 等头信息来设置自己的 Webhook。协作者 Webhook 与所有者 Webhook 独立运行，Payload 格式相同。详细设置说明请参阅测试与集成指南。

协作者 Webhook 与所有者 Webhook 适用相同的重试策略和相同的签名。用于验证签名的密钥可在上方的 Webhook 签名密钥卡片中查看。

危险区域

仅所有者可见。

危险区域

  • 删除端点 按钮
  • 删除后立即且永久移除：
    • 端点配置本身
    • 沙盒环境和生产环境的所有 API 记录
    • 相关统计 / 部署请求 / Webhook / 协作密钥
  • 协作者也将失去访问权限
  • 无法撤销 — 确认对话框中必须输入端点名称才能继续

右侧边栏

详情页右侧根据环境显示不同的快捷卡片。

API 调用记录

查看日志

跳转到可以查看该端点 API 调用结果的页面。您可以详细查看请求成功/失败、Payload、Webhook 状态等。

沙盒环境测试

在沙盒环境标签页显示。

沙盒环境测试

跳转到可以直接在浏览器中测试 API 调用和查看集成方法的页面。详情请参阅测试与集成指南。

生产控制台

在生产环境标签页显示，部署后仅所有者可见。

生产控制台

直接从仪表盘管理生产环境数据的控制台。适用于预先填充产品列表或公告，供协作者通过 GET 获取。支持 POST（创建）、GET（读取）、PUT（更新）和 DELETE（删除）。控制台使用所有者的 API 密钥运行，不会触发协作者 Webhook。如果配置了所有者 Webhook，则正常触发。详情请参阅生产控制台。

部署请求通知

在沙盒环境标签页显示。

部署请求通知

协作者请求了生产环境部署时显示。该通知也会通过邮件发送，不会错过。点击 查看全部 按钮查看完整的部署请求历史。

常见问题

  • 部署按钮被禁用：可能是沙盒环境中没有进行过测试调用，或者最新的沙盒环境版本已经部署到了生产环境。请先在沙盒环境中运行测试
  • 生产环境标签页没有记录：部署前生产环境调用会被拒绝，因此不记录日志。请检查部署是否成功，以及是否使用了 tm_live_ 密钥
  • 必填字段已更改但未反映在生产环境：沙盒环境的更改不会自动应用到生产环境。请再次点击 部署到生产环境
  • Webhook 未到达：Webhook 服务器必须在 15 秒内响应。请检查服务器是否可公开访问且使用 HTTPS。Discord 和 Slack 等平台有自己的速率限制——如果短时间内触发了过多 Webhook，部分可能会被拦截。请同时检查接收平台的速率限制策略
上一篇
创建新端点
下一篇
协作密钥