API de Ruche

Votre site, un tableur, Zapier, Make, n8n ou un système fait pour vous dialoguent avec Ruche par une clé. Ils lisent l'agenda, les clients et les services, prennent, déplacent et annulent des rendez-vous, et reçoivent une notification à chaque changement.

Dans les forfaits Solo et Équipe, pour la titulaire et les associés. Chaque clé ne voit que sa propre entreprise.

Comment obtenir la clé

Dans le tableau de bord, ouvrez Réglages et touchez Intégrations.
Touchez Créer une clé, donnez-lui un nom et cochez ce qu'elle peut faire.
Copiez la clé tout de suite : elle commence par rk_live_ et n'apparaît plus ensuite.

Envoyez la clé dans l'en-tête Authorization: Bearer de chaque requête. Appelez l'API depuis le serveur de votre système, jamais depuis une page que le navigateur du visiteur télécharge : la clé y serait visible de tous.

Ce que chaque clé peut faire

À la création de la clé, vous cochez les portées. Une route sans la portée répond 403.

appointments.read: Voir les rendez-vous : date, heure, service, qui reçoit et le nom de qui vient. Jamais le code du rendez-vous.
appointments.write: Réserver sur un créneau libre, déplacer et annuler avec le motif, avec les mêmes règles et e-mails que le tableau de bord.
clients.read: Voir les clients : nom, téléphone, e-mail et anniversaire. Jamais les notes, les fiches ni les photos.
clients.write: Enregistrer un nouveau client. Qui existe déjà n'est pas modifié par l'API.
services.read: Voir les services, la durée et le prix.
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.

Écrire sans répéter

Réserver, déplacer, annuler et enregistrer demandent l'en-tête Idempotency-Key, avec une nouvelle valeur pour chaque action (un UUID convient). Si le réseau tombe et que votre système renvoie avec la même clé et le même corps, Ruche renvoie la même réponse, sans réserver deux fois. La même clé avec un autre corps répond 409. La réponse est conservée pendant 24 heures.

Notifications pour votre système

Dans Intégrations, indiquez une adresse https et cochez quand prévenir. Chaque notification est un POST en JSON avec le type, un identifiant unique et l'identifiant et l'heure de ce qui a changé. Le nom, le téléphone et les montants ne figurent jamais dans la notification : votre système va chercher le reste par l'API, avec une clé.

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.createdRendez-vous pris
appointment.confirmedRendez-vous confirmé
appointment.cancelledRendez-vous annulé
appointment.rescheduledRendez-vous déplacé
client.createdNouveau client
payment.receivedPaiement reçu
sale.createdVente enregistrée

Chaque notification est signée avec HMAC SHA-256 dans l'en-tête x-ruche-signature, avec le secret de l'adresse. Vérifiez avant de faire confiance.

Exemples

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

Tester la clé

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

Les rendez-vous d'octobre

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

Réserver un rendez-vous

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

Annuler avec le motif

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

Limites et réponses

Jusqu'à 120 requêtes par minute et par clé. Au-delà, la réponse est 429 avec Retry-After.
401 : clé absente, erronée ou révoquée.
402 : le forfait de l'entreprise n'inclut pas les intégrations.
403 : la clé n'a pas la portée de la route.
409 : créneau occupé, client déjà existant ou Idempotency-Key répétée avec un autre corps.

Spécification OpenAPI

Toutes les routes, les champs et les réponses sont dans le fichier OpenAPI 3.1, généré à partir des mêmes schémas qui valident les requêtes. Importez-le dans Postman, Insomnia ou le générateur de code que vous utilisez.

Télécharger openapi.json Pas à pas dans le centre d'aide