API Ruche

Ваш сайт, таблиця, Zapier, Make, n8n або система, створена для вас, спілкуються з Ruche за допомогою ключа. Вони читають розклад, клієнтів і послуги, створюють, переносять і скасовують записи та отримують сповіщення про кожну зміну.

У планах Solo та «Команда», для власниці та партнерів. Кожен ключ бачить лише власний бізнес.

Як отримати ключ

У панелі відкрийте «Налаштування» і торкніться «Інтеграції».
Торкніться «Створити ключ», дайте назву й позначте, що він може робити.
Скопіюйте ключ одразу: він починається з rk_live_ і більше не відображається.

Надсилайте ключ у заголовку Authorization: Bearer кожного запиту. Викликайте API із сервера вашої системи, ніколи зі сторінки, яку завантажує браузер відвідувача: там ключ був би на виду в усіх.

Що може робити кожен ключ

Створюючи ключ, ви позначаєте області доступу (scopes). Маршрут без потрібної області відповідає 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 Покроково в довідковому центрі