API di Ruche

Il tuo sito, un foglio di calcolo, Zapier, Make, n8n o un sistema fatto per te dialogano con Ruche tramite una chiave. Leggono l'agenda, i clienti e i servizi, fissano, spostano e annullano appuntamenti, e ricevono un avviso a ogni modifica.

Nei piani Solo e Team, per la titolare e i soci. Ogni chiave vede solo la propria attività.

Come ottenere la chiave

Nel pannello, apri Impostazioni e tocca Integrazioni.
Tocca Crea chiave, dai un nome e seleziona cosa può fare.
Copia subito la chiave: inizia con rk_live_ e non compare di nuovo.

Invia la chiave nell'intestazione Authorization: Bearer di ogni richiesta. Chiama l'API dal server del tuo sistema, mai da una pagina che il browser di chi visita scarica: lì la chiave sarebbe visibile a tutti.

Cosa può fare ogni chiave

Quando crei la chiave, selezioni gli scope. Una rotta senza lo scope risponde 403.

appointments.read: Vedere gli appuntamenti: data, ora, servizio, chi li segue e il nome di chi viene. Mai il codice dell'appuntamento.
appointments.write: Fissare in un orario libero, spostare e annullare con il motivo, con le stesse regole e le stesse e-mail del pannello.
clients.read: Vedere i clienti: nome, telefono, e-mail e compleanno. Mai le note, le schede né le foto.
clients.write: Registrare un nuovo cliente. Chi esiste già non cambia tramite l'API.
services.read: Vedere i servizi, la durata e il prezzo.
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.

Scrivere senza duplicare

Fissare, spostare, annullare e registrare richiedono l'intestazione Idempotency-Key, con un valore nuovo per ogni azione (basta un UUID). Se la rete cade e il tuo sistema reinvia con la stessa chiave e lo stesso corpo, Ruche restituisce la stessa risposta, senza fissare due volte. La stessa chiave con un altro corpo risponde 409. La risposta resta conservata per 24 ore.

Avvisi al tuo sistema

In Integrazioni, inserisci un indirizzo https e seleziona quando avvisare. Ogni avviso è un POST in JSON con il tipo, un id univoco e l'id e l'ora di ciò che è cambiato. Nome, telefono e importi non vanno mai nell'avviso: il tuo sistema recupera il resto tramite l'API, con una chiave.

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.createdAppuntamento fissato
appointment.confirmedAppuntamento confermato
appointment.cancelledAppuntamento annullato
appointment.rescheduledAppuntamento spostato
client.createdNuovo cliente
payment.receivedPagamento ricevuto
sale.createdVendita registrata

Ogni avviso è firmato con HMAC SHA-256 nell'intestazione x-ruche-signature, con il segreto dell'indirizzo. Verifica prima di fidarti.

Esempi

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

Testare la chiave

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

Gli appuntamenti di ottobre

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

Fissare un appuntamento

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

Annullare con il motivo

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

Limiti e risposte

Fino a 120 richieste al minuto per chiave. Superato, la risposta è 429 con Retry-After.
401: chiave assente, errata o revocata.
402: il piano dell'attività non include le integrazioni.
403: la chiave non ha lo scope della rotta.
409: orario occupato, cliente già esistente o Idempotency-Key ripetuta con un altro corpo.

Specifica OpenAPI

Tutte le rotte, i campi e le risposte sono nel file OpenAPI 3.1, generato dagli stessi schemi che validano le richieste. Importalo in Postman, in Insomnia o nel generatore di codice che usi.

Scarica openapi.json Guida passo passo nel centro assistenza