开发者

在 Granetra 上构建

一个干净的 REST API 和签名 Webhooks，供您的 AI 支持代理使用。在仪表板的开发者页面创建一个密钥，几分钟内开始构建。

获取 API 密钥阅读参考

https://granetra.com/api/v1

REST API

列出机器人，读取对话和记录，发送聊天消息，管理代理操作 — 所有这些都使用范围限定的 bearer 密钥。

签名 Webhooks

在对话开始、访客请求人工服务或捕获潜在客户时，立即获取带时间戳的 HMAC POST — 具有重试和交付日志。

为自动化而生

轮换密钥，将其锁定到您的服务器 IP，并通过 CI/CD 驱动机器人配置。仪表板所做的一切，都可以通过 API 完成。

API 参考

基础 URL： https://granetra.com/api/v1

身份验证

在每个请求中将您的 API 密钥作为 bearer 令牌传递：

Authorization: Bearer gk_your_key_here

密钥是有范围的。请求一个您密钥没有范围的端点会返回 403 insufficient_scope。可用范围： bots:read, conversations:read, chat:write, actions:read, actions:write.

端点

GET	`/bots`	列出您的机器人
GET	`/bots/:id`	单个机器人
GET	`/bots/:id/conversations`	列出对话
GET	`/conversations/:id`	对话记录
POST	`/chat`	发送消息，获取回复
GET	`/bots/:id/actions`	列出机器人的代理操作
POST	`/bots/:id/actions`	创建操作
PATCH	`/bots/:id/actions/:actionId`	更新操作
DEL	`/bots/:id/actions/:actionId`	删除操作

发送聊天消息

curl -X POST https://granetra.com/api/v1/chat \
  -H "Authorization: Bearer gk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "00000000-0000-0000-0000-000000000000",
    "message": "What are your opening hours?"
  }'

# → { "conversation_id": "…", "message_id": "…", "fallback": false, "reply": "We're open 9–5 Mon–Fri." }
# Pass the returned conversation_id back to continue the same thread.

管理代理行为

注册您自己的 HTTPS 端点作为机器人在对话中可以调用的工具 — 从 CI/CD 管理它们，而不是从仪表板。需要 actions:write 范围和一个在 Scale 计划上的机器人。

curl -X POST https://granetra.com/api/v1/bots/BOT_ID/actions \
  -H "Authorization: Bearer gk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lookup_order",
    "description": "Look up an order status by number",
    "url": "https://api.yourstore.com/orders",
    "method": "GET",
    "parameters": [
      { "name": "order_number", "type": "string", "description": "The order #", "required": true }
    ]
  }'

# → { "ok": true, "id": "…" }

Webhook 事件

每个交付都是带有此信封的 JSON POST：

{
  "id": "delivery-uuid",
  "type": "handoff.requested",
  "created": "2026-07-20T12:00:00.000Z",
  "data": { "bot_id": "…", "conversation_id": "…" }
}

事件类型： conversation.created, handoff.requested, lead.captured.

验证签名

每个 webhook 都携带一个 X-Granetra-Signature 头，格式为 t=<unix>,v1=<hmac>。使用您端点的签名密钥重新计算 `${t}.${rawBody}` 的 HMAC-SHA256 并进行比较：

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

以任何 2xx 响应以确认。非 2xx 或超时将进行重试并逐步增加延迟；长时间失败会自动禁用该端点。

将密钥锁定到您的 IP

密钥可以携带可选的 IP 允许列表（单个 IPv4 地址或 CIDR 范围）。设置后，来自任何其他地址的请求将被拒绝，返回 403 ip_not_allowed。在仪表板中按密钥管理。