身份验证
所有 API 请求都使用 API 密钥作为持有者令牌。在应用中的 开发者 → API 密钥下创建密钥。密钥分为 只读 或 读/写.
curl https://savrsoft.com/api/v1/events \ -H "Authorization: Bearer savr_live_your_key_here"
基础 URL： https://savrsoft.com/api/v1 · 所有响应均为 JSON 格式。错误返回 { "error": "…" } 并带有 4xx/5xx 状态码。
状态码
| 代码 | 出现情况 |
|---|---|
200 | 读取成功。 |
201 | 创建成功。返回体为 { "id": 42 } ——如需获取其余信息，请查询该记录。 |
400 | 缺少必填字段，例如 { "error": "name is required" }，或分页游标无法读取。 |
401 | 未提供 API 密钥、密钥格式有误，或密钥已被吊销。 |
403 | 使用只读密钥执行了写入操作。请在以下位置创建读写密钥 开发者 → API 密钥. |
404 | 该记录不存在，或属于其他组织——这两种情况被刻意设计为无法区分。对于无法识别的路径或方法，也会返回同样的结果。 |
本 API 的适用范围
该 API 仅支持 读取与创建)，不提供 DELETE, PUT 或 PATCH
接口——使用这些方法的请求会返回 404 Unknown endpoint，与访问未知路径时的返回结果相同。删除和
编辑操作均在应用内完成，因此集成程序无法删除caterer的记录。如果您需要创建以外的写入权限，请
告诉我们您正在构建的内容.
分页
每个列表接口都支持分页。传入 limit 参数（默认为 100，最大为 500)，并
持续跟进 next_cursor ，直到 has_more 为 false:
{
"data": [ ... ],
"has_more": true,
"next_cursor": "eyJuYW1lIjoiQWNtZSIsImlkIjo0Mn0"
}
将该游标原样传回即可获取下一页。请将其视为不透明字符串——其编码方式可能会发生变化：
curl "https://savrsoft.com/api/v1/clients?limit=100&cursor=eyJuYW1lIjoiQWNtZSIsImlkIjo0Mn0" \ -H "Authorization: Bearer savr_live_your_key_here"
分页锚定在你收到的最后一行记录上，而非某个偏移量，因此在你翻页期间新增或删除的行 不会导致你跳过或重复某条记录。游标可无限期保持有效。
| 参数 | 行为 |
|---|---|
limit | 1–500。缺省、为零、为负数或非数字时回退为 100；超过 500 的一律按 500 处理。 |
cursor | next_cursor 来自上一页。首页请省略此参数。若游标无法解析——已损坏，或来自不同的接口——则返回 400 Invalid cursor 而不会悄悄地从头开始。 |
排序方式： /events 和 /invoices 按最新排在前面； /recipes 和
/clients 按名称排序，若名称相同则按 id 决胜，确保名称重复时分页依然稳定。
接口
/v1/me你的组织信息（id、名称、货币）。
/v1/events列出活动，按最新排在前面。支持分页——参见 分页 部分。
/v1/events/{id}一场活动及其菜品。
/v1/events · 需要读写权限创建一个活动。请求体：
{ "name": "Acme holiday party", "event_date": "2026-12-18",
"guests": 120, "price_per_head": 55, "event_type": "corporate" }
/v1/recipes · GET/v1/recipes/{id}获取食谱列表（含过敏原和饮食标签），或单个食谱及其配料。列表支持分页，按名称排序。
/v1/clients · POST/v1/clients获取客户列表（分页，按名称排序）或创建客户。创建请求体： { "name": "...", "email": "...", "phone": "...", "company": "..." }
/v1/invoices · GET/v1/invoices/{id}获取账单列表及计算总额，按最新排序，或单个账单及明细项目。列表支持分页。
Webhooks
注册一个端点，路径在 开发者 → Webhooks下。事件发生时，我们会 POST 一个 JSON 数据：
{
"id": "evt_abc123",
"type": "event.inquiry",
"created_at": "2026-07-17T18:20:00.000Z",
"data": { "id": 42, "name": "Corporate lunch — Dana Ruiz", ... }
}
事件类型
| 类型 | 触发时机 |
|---|---|
event.created | 创建活动时 |
event.inquiry | 收到新的在线订餐请求时 |
invoice.sent | 账单被标记为已发送时 |
invoice.paid | 账单被标记为已付款时 |
proposal.approved | 客户确认提案时 |
client.created | 创建客户时 |
验证签名
每次推送都包含一个 x-savrsoft-signature 请求头：使用您的 webhook 签名密钥对原始请求体计算的 HMAC-SHA256 值。请自行计算并比对：
// Node.js
const crypto = require('crypto');
const sig = crypto.createHmac('sha256', SIGNING_SECRET)
.update(rawBody).digest('hex');
if (sig !== req.headers['x-savrsoft-signature']) reject();