API do Ruche

O seu site, uma folha de cálculo, o Zapier, o Make, o n8n ou um sistema feito para si conversam com o Ruche por uma chave. Leem a agenda, os clientes e os serviços, marcam, remarcam e cancelam horários, e recebem um aviso a cada mudança.

Nos planos Solo e Equipa, para a titular e os sócios. Cada chave vê só o próprio negócio.

Como obter a chave

No painel, abra Ajustes e toque em Integrações.
Toque em Criar chave, dê um nome e marque o que ela pode fazer.
Copie a chave logo: começa com rk_live_ e não volta a aparecer.

Envie a chave no cabeçalho Authorization: Bearer de cada pedido. Chame a API a partir do servidor do seu sistema, nunca de uma página que o navegador de quem visita descarrega: ali a chave ficaria à vista de todos.

O que cada chave pode fazer

Ao criar a chave, marca os escopos. Uma rota sem o escopo responde 403.

appointments.read: Ver os horários: data, hora, serviço, quem atende e o nome de quem vem. Nunca o código do horário.
appointments.write: Marcar num horário livre, remarcar e cancelar com o motivo, com as mesmas regras e e-mails do painel.
clients.read: Ver os clientes: nome, telefone, e-mail e aniversário. Nunca as notas, as fichas nem as fotos.
clients.write: Registar cliente novo. Quem já existe não é alterado pela API.
services.read: Ver os serviços, a duração e o preço.
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.

Escrever sem repetir

Marcar, remarcar, cancelar e registar pedem o cabeçalho Idempotency-Key, com um valor novo para cada ação (um UUID serve). Se a rede falhar e o seu sistema enviar de novo com a mesma chave e o mesmo corpo, o Ruche devolve a mesma resposta, sem marcar duas vezes. A mesma chave com outro corpo responde 409. A resposta fica guardada por 24 horas.

Avisos para o seu sistema

Em Integrações, indique um endereço https e escolha quando avisar. Cada aviso é um POST em JSON com o tipo, um id único e o id e a hora do que mudou. Nome, telefone e valores nunca vão no aviso: o seu sistema obtém o resto pela API, com uma chave.

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.createdHorário marcado
appointment.confirmedHorário confirmado
appointment.cancelledHorário cancelado
appointment.rescheduledHorário remarcado
client.createdCliente novo
payment.receivedPagamento recebido
sale.createdVenda registada

Cada aviso é assinado com HMAC SHA-256 no cabeçalho x-ruche-signature, com o segredo do endereço. Verifique antes de confiar.

Exemplos

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

Testar a chave

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

Os horários de outubro

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

Marcar um horário

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

Cancelar com o 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"}'

Limites e respostas

Até 120 pedidos por minuto por chave. Se passar, a resposta é 429 com Retry-After.
401: chave ausente, errada ou revogada.
402: o plano do negócio não tem integrações.
403: a chave não tem o escopo da rota.
409: horário ocupado, cliente que já existe ou Idempotency-Key repetida com outro corpo.

Especificação OpenAPI

Todas as rotas, os campos e as respostas estão no ficheiro OpenAPI 3.1, gerado dos mesmos esquemas que validam os pedidos. Importe no Postman, no Insomnia ou no gerador de código que usa.

Descarregar openapi.json Passo a passo na central de ajuda