API của Ruche

Trang web của bạn, một bảng tính, Zapier, Make, n8n hoặc một hệ thống làm riêng cho bạn trao đổi với Ruche qua một khóa. Chúng đọc lịch hẹn, khách hàng và dịch vụ, đặt, đổi và hủy lịch, và nhận thông báo mỗi khi có thay đổi.

Trong gói Solo và Nhóm, cho chủ tài khoản và các thành viên góp vốn. Mỗi khóa chỉ thấy cơ sở của chính nó.

Cách lấy khóa

Trong bảng điều khiển, mở Cài đặt và chạm vào Tích hợp.
Chạm vào Tạo khóa, đặt tên và đánh dấu những gì khóa được phép làm.
Hãy sao chép khóa ngay lúc đó: khóa bắt đầu bằng rk_live_ và không hiển thị lại.

Hãy gửi khóa trong tiêu đề Authorization: Bearer của mỗi yêu cầu. Hãy gọi API từ máy chủ của hệ thống bạn, không bao giờ từ một trang mà trình duyệt của người truy cập tải về: ở đó khóa sẽ bị lộ cho mọi người.

Mỗi khóa có thể làm gì

Khi tạo khóa, bạn đánh dấu các phạm vi quyền (scope). Một tuyến không có phạm vi quyền sẽ trả về 403.

appointments.read: Xem các lịch hẹn: ngày, giờ, dịch vụ, người phục vụ và tên người đến. Không bao giờ có mã của lịch hẹn.
appointments.write: Đặt vào một khung giờ trống, đổi lịch và hủy kèm lý do, với cùng quy tắc và email như bảng điều khiển.
clients.read: Xem khách hàng: tên, số điện thoại, email và ngày sinh nhật. Không bao giờ có ghi chú, hồ sơ hay ảnh.
clients.write: Thêm khách hàng mới. Người đã tồn tại không bị thay đổi qua API.
services.read: Xem các dịch vụ, thời lượng và giá.
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.

Ghi mà không lặp lại

Đặt, đổi, hủy và thêm đều cần tiêu đề Idempotency-Key, với một giá trị mới cho mỗi hành động (một UUID là đủ). Nếu mạng bị ngắt và hệ thống của bạn gửi lại với cùng khóa và cùng nội dung, Ruche trả về cùng một câu trả lời, không đặt lịch hai lần. Cùng khóa nhưng nội dung khác sẽ trả về 409. Câu trả lời được lưu trong 24 giờ.

Thông báo cho hệ thống của bạn

Trong Tích hợp, nhập một địa chỉ https và đánh dấu khi nào cần báo. Mỗi thông báo là một POST dạng JSON với loại sự kiện, một id duy nhất, cùng id và thời điểm của thứ đã thay đổi. Tên, số điện thoại và số tiền không bao giờ có trong thông báo: hệ thống của bạn lấy phần còn lại qua API, bằng một khóa.

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.createdLịch hẹn được đặt
appointment.confirmedLịch hẹn được xác nhận
appointment.cancelledLịch hẹn bị hủy
appointment.rescheduledLịch hẹn được đổi
client.createdKhách hàng mới
payment.receivedĐã nhận thanh toán
sale.createdĐã ghi nhận bán hàng

Mỗi thông báo được ký bằng HMAC SHA-256 trong tiêu đề x-ruche-signature, với bí mật của địa chỉ. Hãy kiểm tra trước khi tin tưởng.

Ví dụ

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_..."

Kiểm tra khóa

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

Các lịch hẹn của tháng Mười

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_..."

Đặt một lịch hẹn

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"}}'

Hủy kèm lý do

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"}'

Giới hạn và phản hồi

Tối đa 120 yêu cầu mỗi phút cho mỗi khóa. Vượt mức, phản hồi là 429 kèm Retry-After.
401: thiếu khóa, khóa sai hoặc bị thu hồi.
402: gói của cơ sở không có tích hợp.
403: khóa không có phạm vi quyền của tuyến.
409: khung giờ đã bị đặt, khách hàng đã tồn tại hoặc Idempotency-Key bị lặp với nội dung khác.

Đặc tả OpenAPI

Tất cả các tuyến, trường dữ liệu và phản hồi nằm trong tệp OpenAPI 3.1, được tạo từ chính các lược đồ dùng để kiểm tra các yêu cầu. Hãy nhập vào Postman, Insomnia hoặc trình tạo mã bạn đang dùng.

Tải openapi.json Hướng dẫn từng bước trong trung tâm trợ giúp