Ruche-API

Ihre Website, eine Tabelle, Zapier, Make, n8n oder ein für Sie gebautes System sprechen über einen Schlüssel mit Ruche. Sie lesen den Kalender, die Kunden und die Leistungen, buchen, verschieben und sagen Termine ab und erhalten bei jeder Änderung einen Hinweis.

In den Tarifen Solo und Team, für die Inhaberin und die Gesellschafter. Jeder Schlüssel sieht nur den eigenen Betrieb.

So bekommen Sie den Schlüssel

Öffnen Sie im Dashboard Einstellungen und tippen Sie auf Integrationen.
Tippen Sie auf Schlüssel erstellen, geben Sie einen Namen an und markieren Sie, was er darf.
Kopieren Sie den Schlüssel sofort: Er beginnt mit rk_live_ und erscheint nicht wieder.

Senden Sie den Schlüssel im Header Authorization: Bearer jeder Anfrage. Rufen Sie die API vom Server Ihres Systems aus auf, nie von einer Seite, die der Browser der Besucher herunterlädt: Dort läge der Schlüssel offen für alle.

Was jeder Schlüssel darf

Beim Erstellen des Schlüssels markieren Sie die Scopes. Eine Route ohne den Scope antwortet mit 403.

appointments.read: Die Termine sehen: Datum, Uhrzeit, Leistung, wer behandelt und der Name der Person, die kommt. Nie den Code des Termins.
appointments.write: Auf einen freien Termin buchen, verschieben und mit Grund absagen, mit denselben Regeln und E-Mails wie im Dashboard.
clients.read: Die Kunden sehen: Name, Telefon, E-Mail und Geburtstag. Nie die Notizen, die Karteikarten oder die Fotos.
clients.write: Neue Kunden anlegen. Wer schon existiert, wird über die API nicht geändert.
services.read: Die Leistungen, die Dauer und den Preis sehen.
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.

Schreiben ohne Wiederholung

Buchen, verschieben, absagen und anlegen verlangen den Header Idempotency-Key, mit einem neuen Wert für jede Aktion (eine UUID genügt). Wenn das Netz ausfällt und Ihr System mit demselben Schlüssel und demselben Body erneut sendet, liefert Ruche dieselbe Antwort, ohne zweimal zu buchen. Derselbe Schlüssel mit anderem Body antwortet mit 409. Die Antwort wird 24 Stunden gespeichert.

Hinweise an Ihr System

Tragen Sie unter Integrationen eine https-Adresse ein und markieren Sie, wann benachrichtigt wird. Jeder Hinweis ist ein POST in JSON mit dem Typ, einer eindeutigen ID und der ID und Zeit dessen, was sich geändert hat. Name, Telefon und Beträge gehen nie im Hinweis mit: Ihr System holt den Rest über die API mit einem Schlüssel.

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.createdTermin gebucht
appointment.confirmedTermin bestätigt
appointment.cancelledTermin abgesagt
appointment.rescheduledTermin verschoben
client.createdNeuer Kunde
payment.receivedZahlung erhalten
sale.createdVerkauf erfasst

Jeder Hinweis wird mit HMAC SHA-256 im Header x-ruche-signature mit dem Geheimnis der Adresse signiert. Prüfen Sie ihn, bevor Sie vertrauen.

Beispiele

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

Den Schlüssel testen

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

Die Termine im Oktober

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

Termin buchen

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

Mit Grund absagen

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

Limits und Antworten

Bis zu 120 Anfragen pro Minute und Schlüssel. Darüber ist die Antwort 429 mit Retry-After.
401: Schlüssel fehlt, falsch oder widerrufen.
402: Der Tarif des Betriebs hat keine Integrationen.
403: Der Schlüssel hat nicht den Scope der Route.
409: Termin belegt, Kunde existiert bereits oder Idempotency-Key mit anderem Body wiederholt.

OpenAPI-Spezifikation

Alle Routen, Felder und Antworten stehen in der OpenAPI-3.1-Datei, erzeugt aus denselben Schemata, die die Anfragen prüfen. Importieren Sie sie in Postman, Insomnia oder den Codegenerator, den Sie nutzen.

openapi.json herunterladen Schritt für Schritt im Hilfezentrum