Ruche API

Je site, een spreadsheet, Zapier, Make, n8n of een systeem dat voor jou is gebouwd praten met Ruche via een sleutel. Ze lezen de agenda, de klanten en de diensten, boeken, verzetten en annuleren afspraken, en ontvangen een melding bij elke wijziging.

In de abonnementen Solo en Team, voor de eigenaar en de partners. Elke sleutel ziet alleen de eigen zaak.

Hoe je de sleutel krijgt

Open in het dashboard Instellingen en tik op Integraties.
Tik op Sleutel maken, geef een naam en vink aan wat ze mag doen.
Kopieer de sleutel meteen: ze begint met rk_live_ en verschijnt niet opnieuw.

Stuur de sleutel in de header Authorization: Bearer van elk verzoek. Roep de API aan vanaf de server van je systeem, nooit vanaf een pagina die de browser van de bezoeker downloadt: daar zou de sleutel voor iedereen zichtbaar zijn.

Wat elke sleutel mag doen

Bij het maken van de sleutel vink je de scopes aan. Een route zonder de scope antwoordt 403.

appointments.read: De afspraken zien: datum, tijd, dienst, wie behandelt en de naam van wie komt. Nooit de code van de afspraak.
appointments.write: Boeken op een vrije tijd, verzetten en annuleren met de reden, met dezelfde regels en e-mails als het dashboard.
clients.read: De klanten zien: naam, telefoon, e-mail en verjaardag. Nooit de notities, de klantkaarten of de foto’s.
clients.write: Een nieuwe klant toevoegen. Wie al bestaat, verandert niet via de API.
services.read: De diensten, de duur en de prijs zien.
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.

Schrijven zonder te herhalen

Boeken, verzetten, annuleren en toevoegen vragen de header Idempotency-Key, met een nieuwe waarde voor elke actie (een UUID volstaat). Als het netwerk uitvalt en je systeem opnieuw stuurt met dezelfde sleutel en dezelfde inhoud, geeft Ruche hetzelfde antwoord terug, zonder twee keer te boeken. Dezelfde sleutel met andere inhoud antwoordt 409. Het antwoord wordt 24 uur bewaard.

Meldingen naar je systeem

Zet bij Integraties een https-adres en vink aan wanneer je gewaarschuwd wilt worden. Elke melding is een POST in JSON met het type, een unieke id en de id en het tijdstip van wat veranderde. Naam, telefoon en bedragen gaan nooit mee in de melding: je systeem haalt de rest op via de API, met een sleutel.

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.createdAfspraak gepland
appointment.confirmedAfspraak bevestigd
appointment.cancelledAfspraak geannuleerd
appointment.rescheduledAfspraak verzet
client.createdNieuwe klant
payment.receivedBetaling ontvangen
sale.createdVerkoop geregistreerd

Elke melding is ondertekend met HMAC SHA-256 in de header x-ruche-signature, met het geheim van het adres. Controleer voordat je vertrouwt.

Voorbeelden

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

De sleutel testen

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

De afspraken van 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_..."

Een tijd boeken

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

Annuleren met de reden

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

Limieten en antwoorden

Tot 120 verzoeken per minuut per sleutel. Daarboven is het antwoord 429 met Retry-After.
401: sleutel ontbreekt, is fout of ingetrokken.
402: het abonnement van de zaak heeft geen integraties.
403: de sleutel heeft de scope van de route niet.
409: tijd bezet, klant die al bestaat of Idempotency-Key herhaald met andere inhoud.

OpenAPI-specificatie

Alle routes, de velden en de antwoorden staan in het OpenAPI 3.1-bestand, gegenereerd uit dezelfde schema’s die de verzoeken valideren. Importeer het in Postman, Insomnia of de codegenerator die je gebruikt.

openapi.json downloaden Stap voor stap in het helpcentrum