API Ruche

Ваш сайт, таблица, 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 и отметьте, когда уведомлять. Каждое уведомление это POST в JSON с типом, уникальным 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Продажа зарегистрирована

Каждое уведомление подписано HMAC SHA-256 в заголовке x-ruche-signature, с секретом адреса. Проверьте, прежде чем доверять.

Примеры

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 Пошаговая инструкция в центре помощи