Ruche API

你的网站、表格、Zapier、Make、n8n，或为你定制的系统，都可以通过一个密钥与 Ruche 对接。它们可以读取日程、客户和服务，预约、改期和取消，并在每次变更时收到通知。

适用于个人版和团队版，面向店主和合伙人。每个密钥只能看到自己的商家。

如何获取密钥

在后台打开“设置”，点击“集成”。
点击“创建密钥”，起一个名称，并勾选它可以做什么。
请立即复制密钥：它以 rk_live_ 开头，之后不会再次显示。

请在每个请求的 Authorization: Bearer 请求头中发送密钥。请从你系统的服务器调用 API，绝不要从访问者浏览器下载的页面中调用：那样所有人都能看到密钥。

每个密钥可以做什么

创建密钥时，你需要勾选权限范围。没有对应范围的接口会返回 403。

appointments.read: 查看预约：日期、时间、服务、服务人员和到店者的姓名。绝不包含预约代码。
appointments.write: 在空闲时间预约、改期，并附原因取消，规则和邮件与后台相同。
clients.read: 查看客户：姓名、电话、邮箱和生日。绝不包含备注、档案和照片。
clients.write: 登记新客户。已存在的客户不能通过 API 修改。
services.read: 查看服务、时长和价格。
payments.read: Ver os pagamentos, os valores e o horário ligado, sem dados bancários.
sales.read: Ver as vendas e os itens, sem custos nem notas internas.

写入不重复

预约、改期、取消和登记都需要 Idempotency-Key 请求头，每次操作使用一个新值（UUID 即可）。如果网络中断而你的系统用相同的密钥和相同的内容重新发送，Ruche 会返回相同的响应，不会重复预约。相同密钥但内容不同，会返回 409。响应会保存 24 小时。

给你的系统的通知

在“集成”中填写一个 https 地址，并勾选何时通知。每条通知是一个 JSON 格式的 POST，包含类型、唯一 id，以及发生变更的对象的 id 和时间。姓名、电话和金额绝不会出现在通知中：你的系统通过 API 并凭密钥获取其余信息。

GET /payments/:id e GET /sales/:id mostram o objeto do aviso. As listas GET /payments e GET /sales aceitam updatedSince, limit (1 a 100) e cursor; nextCursor nulo indica o fim. Valores em centavos, com a moeda do negócio. Uma venda com paymentPending ainda está a receber. Somente leitura.

appointment.created预约已创建
appointment.confirmed预约已确认
appointment.cancelled预约已取消
appointment.rescheduled预约已改期
client.created新客户
payment.received已收到付款
sale.created销售已登记

每条通知都在 x-ruche-signature 请求头中使用 HMAC SHA-256 签名，签名密钥为该地址的专属密钥。请先验证再信任。

示例

Listar pagamentos

curl "https://api.ruche.my/v1/api/payments?limit=50" -H "Authorization: Bearer rk_live_..."

Buscar o pagamento do aviso payment.received

curl "https://api.ruche.my/v1/api/payments/ID_DO_PAGAMENTO" -H "Authorization: Bearer rk_live_..."

Listar vendas

curl "https://api.ruche.my/v1/api/sales?limit=50" -H "Authorization: Bearer rk_live_..."

Buscar a venda do aviso sale.created

curl "https://api.ruche.my/v1/api/sales/ID_DA_VENDA" -H "Authorization: Bearer rk_live_..."

测试密钥

curl https://api.ruche.my/v1/api/me \
  -H "Authorization: Bearer rk_live_..."

十月的预约

curl "https://api.ruche.my/v1/api/appointments?from=2026-10-01T00:00:00Z&to=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer rk_live_..."

预约一个时间

curl -X POST https://api.ruche.my/v1/api/appointments \
  -H "Authorization: Bearer rk_live_..." \
  -H "Idempotency-Key: 6f1c2a9e-3b7d-4e1a-9c55-2d8f0b4a7e13" \
  -H "Content-Type: application/json" \
  -d '{"staffId":"<id>","serviceId":"<id>","startAt":"2026-10-06T10:00:00-03:00",
       "client":{"name":"Carla Nunes","phone":"+5511988887766"}}'

附原因取消

curl -X POST https://api.ruche.my/v1/api/appointments/<id>/cancel \
  -H "Authorization: Bearer rk_live_..." \
  -H "Idempotency-Key: 0b9e7d4c-58a2-4f61-8d3e-a1c7b2f60d94" \
  -H "Content-Type: application/json" \
  -d '{"reason":"A cliente pediu pelo site"}'

限制和响应

每个密钥每分钟最多 120 个请求。超出后，响应为 429，并带有 Retry-After。
401：密钥缺失、错误或已被撤销。
402：该商家的套餐不包含集成功能。
403：密钥没有该接口所需的范围。
409：时间已被占用、客户已存在，或 Idempotency-Key 在内容不同的情况下被重复使用。

OpenAPI 规范

所有接口、字段和响应都在 OpenAPI 3.1 文件中，该文件由用于校验请求的同一套模式生成。可以导入到 Postman、Insomnia 或你使用的代码生成器中。

下载 openapi.json 帮助中心中的分步说明