API Ruche

Twoja strona, arkusz, Zapier, Make, n8n lub system zrobiony dla Ciebie rozmawiają z Ruche przez klucz. Czytają kalendarz, klientów i usługi, umawiają, przekładają i odwołują wizyty oraz dostają powiadomienie przy każdej zmianie.

W planach Solo i Zespół, dla właścicielki i wspólników. Każdy klucz widzi tylko własną firmę.

Jak zdobyć klucz

W panelu otwórz Ustawienia i dotknij Integracje.
Dotknij Utwórz klucz, nadaj nazwę i zaznacz, co może robić.
Skopiuj klucz od razu: zaczyna się od rk_live_ i nie pojawi się ponownie.

Wysyłaj klucz w nagłówku Authorization: Bearer każdego żądania. Wywołuj API z serwera swojego systemu, nigdy ze strony pobieranej przez przeglądarkę odwiedzającego: tam klucz byłby na widoku dla wszystkich.

Co może robić każdy klucz

Przy tworzeniu klucza zaznaczasz zakresy. Trasa bez zakresu odpowiada 403.

appointments.read: Przeglądanie wizyt: data, godzina, usługa, kto obsługuje i imię osoby, która przychodzi. Nigdy kod wizyty.
appointments.write: Umawianie w wolnym terminie, przekładanie i odwoływanie z powodem, z tymi samymi zasadami i e-mailami co panel.
clients.read: Przeglądanie klientów: imię i nazwisko, telefon, e-mail i urodziny. Nigdy notatek, kart ani zdjęć.
clients.write: Dodawanie nowego klienta. Istniejący nie zmienia się przez API.
services.read: Przeglądanie usług, czasu trwania i ceny.
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.

Zapis bez powtórzeń

Umawianie, przekładanie, odwoływanie i dodawanie wymagają nagłówka Idempotency-Key, z nową wartością dla każdej akcji (wystarczy UUID). Jeśli sieć padnie, a Twój system wyśle ponownie z tym samym kluczem i tą samą treścią, Ruche zwraca tę samą odpowiedź, bez umówienia dwa razy. Ten sam klucz z inną treścią odpowiada 409. Odpowiedź jest przechowywana przez 24 godziny.

Powiadomienia dla Twojego systemu

W Integracjach wpisz adres https i zaznacz, kiedy powiadamiać. Każde powiadomienie to POST w JSON z typem, unikalnym id oraz id i godziną tego, co się zmieniło. Imię, telefon i kwoty nigdy nie idą w powiadomieniu: Twój system pobiera resztę przez API, kluczem.

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.createdWizyta umówiona
appointment.confirmedWizyta potwierdzona
appointment.cancelledWizyta odwołana
appointment.rescheduledWizyta przełożona
client.createdNowy klient
payment.receivedPłatność otrzymana
sale.createdSprzedaż zarejestrowana

Każde powiadomienie jest podpisane HMAC SHA-256 w nagłówku x-ruche-signature, z sekretem adresu. Sprawdź podpis, zanim zaufasz.

Przykłady

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

Przetestuj klucz

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

Wizyty z października

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

Umów wizytę

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

Odwołaj z powodem

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

Limity i odpowiedzi

Do 120 żądań na minutę na klucz. Po przekroczeniu odpowiedź to 429 z Retry-After.
401: brak klucza, błędny lub unieważniony.
402: plan firmy nie ma integracji.
403: klucz nie ma zakresu tej trasy.
409: termin zajęty, klient już istnieje lub Idempotency-Key powtórzony z inną treścią.

Specyfikacja OpenAPI

Wszystkie trasy, pola i odpowiedzi są w pliku OpenAPI 3.1, wygenerowanym z tych samych schematów, które walidują żądania. Zaimportuj w Postmanie, Insomnii lub generatorze kodu, którego używasz.

Pobierz openapi.json Instrukcja krok po kroku w centrum pomocy