API do Ruche e avisos para outros sistemas

A API do Ruche deixa outro sistema seu (o site do negócio, uma planilha, o Zapier, o Make, o n8n ou um programa feito para você) ler a agenda, os clientes e os serviços, marcar, remarcar e cancelar horários, cadastrar clientes e receber um aviso na hora em que algo muda. Fica em Ajustes, Integrações, para a titular e os sócios, nos planos Solo e Equipe.

Criar uma chave

1. Abra Ajustes e toque em Integrações.
2. Toque em Criar chave, dê um nome (por exemplo, "Site do salão") e marque o que ela pode fazer: ver os horários, os clientes ou os serviços, marcar, remarcar e cancelar, ou cadastrar clientes.
3. Toque em Criar chave e copie a chave na hora. Ela começa com rk_live_ e não aparece de novo, nem para você.

Cada chave faz só o que foi marcado, vale só para o seu negócio e aguenta até 120 pedidos por minuto. Na lista, você vê quando ela foi usada pela última vez e quantos pedidos fez em 30 dias. Para tirar o acesso, toque na chave e em Revogar a chave: o pedido seguinte já é recusado.

Usar a chave

Mande a chave no cabeçalho Authorization: Bearer rk_live_... (ou em X-Api-Key) de cada pedido para https://api.ruche.my/v1/api/. As respostas são em JSON, com as horas em UTC e os valores em centavos com a moeda do negócio. Chame a API do servidor do seu sistema, nunca do código de uma página que o navegador de quem visita baixa: ali a chave ficaria à vista de todos.

• GET /v1/api/me: o negócio e a chave (bom para testar). Qualquer chave.
• GET /v1/api/appointments?from=2026-10-01T00:00:00Z&to=2026-11-01T00:00:00Z: os horários do intervalo (até 93 dias), com o serviço, quem atende, o nome de quem vem e a situação. Dá para filtrar com status e staffId. Escopo "Ver os horários".
• GET /v1/api/appointments/{id}: um horário. Escopo "Ver os horários".
• GET /v1/api/clients?updatedSince=2026-10-01T00:00:00Z: os clientes, do que mudou primeiro para o que mudou por último, com nome, telefone, e-mail e aniversário. Escopo "Ver os clientes".
• GET /v1/api/clients/{id}: um cliente. Escopo "Ver os clientes".
• GET /v1/api/services: os serviços, com a duração e o preço. Escopo "Ver os serviços".

Marcar, remarcar, cancelar e cadastrar

Estas rotas passam pelo mesmo caminho do painel, com as mesmas regras, o limite do plano, os e-mails e os avisos. Cada pedido precisa do cabeçalho Idempotency-Key com um valor novo por ação (um UUID serve): se o seu sistema mandar de novo com a mesma chave e o mesmo corpo, o Ruche devolve a mesma resposta sem repetir a ação; com outro corpo, responde 409. A resposta fica guardada por 24 horas.

• POST /v1/api/appointments: marca num horário livre, com staffId, serviceId, startAt (data e hora com o fuso) e client ({ "id" } de quem já existe ou { "name", "phone", "email" }). Escopo "Marcar, remarcar e cancelar".
• POST /v1/api/appointments/{id}/reschedule: remarca para startAt (e staffId, se for com outra pessoa). Nasce um horário novo; o antigo fica como remarcado.
• POST /v1/api/appointments/{id}/cancel: cancela com reason, o motivo.
• POST /v1/api/clients: cadastra cliente novo com name, phone, email, birthDate e consent: true (a pessoa concordou em ter os dados guardados). Telefone que já existe volta 409 com o id da ficha. Escopo "Cadastrar clientes".

A lista completa das rotas e dos campos está na página API do Ruche, com o arquivo OpenAPI para importar no Postman ou no Insomnia.

As listas vêm de 50 em 50 (até 100, com limit). Quando há mais, a resposta traz nextCursor: mande de novo com cursor igual a esse valor. Nunca saem pela API o código do horário (é a senha da página do horário), o motivo do cancelamento, as notas e as fichas dos clientes, as fotos, as conversas e os valores da equipe.

Respostas de erro

• 401: sem chave, chave errada ou revogada, ou conta fora do ar.
• 402 com PLAN_INTEGRATIONS: o plano não tem integrações. O que você criou fica guardado e volta com o plano Solo ou Equipe.
• 403 com API_SCOPE_MISSING: a chave não pode ver isso. Crie outra com o que falta.
• 409: horário ocupado (SLOT_TAKEN), cliente que já existe (CLIENT_EXISTS) ou a mesma Idempotency-Key com outro corpo.
• 429: passou de 120 pedidos no minuto. Espere os segundos de Retry-After.

Avisos para outros sistemas

Em vez de perguntar a toda hora se algo mudou, o seu sistema pode receber um aviso. Em Integrações, toque em Pôr um endereço, cole o endereço https:// que o Zapier, o Make, o n8n ou o seu sistema dá e marque quando avisar: horário marcado, confirmado, cancelado ou remarcado, cliente novo, pagamento recebido ou venda registrada. Copie o segredo da assinatura (começa com whsec_), que também aparece uma vez só.

Cada aviso é um POST em JSON com o tipo (event), um identificador único (id, para não contar o mesmo aviso duas vezes) e o identificador e a hora do que mudou (o horário, o cliente, o pagamento ou a venda). Os dados da pessoa e os valores não vão no aviso: o sistema busca o resto pela API, com uma chave. O endereço precisa responder com um código 2xx em até 10 segundos; se não responder, o Ruche tenta de novo 8 vezes, com espera crescente. Depois de 15 avisos seguidos perdidos, o endereço é pausado e o painel mostra. Em cada endereço você vê os envios recentes, manda um teste, manda de novo o que falhou, pausa, troca o segredo e apaga.

Conferir a assinatura

Todo aviso leva os cabeçalhos x-ruche-event, x-ruche-delivery, x-ruche-timestamp e x-ruche-signature. Para conferir que ele veio do Ruche:

1. Junte o valor de x-ruche-timestamp, um ponto e o corpo do aviso exatamente como chegou.
2. Calcule o HMAC SHA-256 desse texto com o segredo do endereço, em hexadecimal.
3. Compare com o que vem depois de sha256= em x-ruche-signature (com comparação de tempo constante) e recuse avisos com mais de 5 minutos.

O que ainda não tem

Ligar o Google Agenda ou o Outlook por login ainda não está disponível. Para ver a agenda no seu calendário, use o link da Agenda no seu calendário.