API de Ruche

Tu sitio, una hoja de cálculo, Zapier, Make, n8n o un sistema hecho para ti hablan con Ruche mediante una clave. Leen la agenda, los clientes y los servicios, agendan, reprograman y cancelan citas, y reciben un aviso con cada cambio.

En los planes Solo y Equipo, para la titular y los socios. Cada clave ve solo el propio negocio.

Cómo obtener la clave

En el panel, abre Ajustes y toca Integraciones.
Toca Crear clave, ponle un nombre y marca lo que puede hacer.
Copia la clave al momento: empieza por rk_live_ y no se muestra de nuevo.

Envía la clave en la cabecera Authorization: Bearer de cada petición. Llama a la API desde el servidor de tu sistema, nunca desde una página que descargue el navegador de quien visita: allí la clave quedaría a la vista de todos.

Lo que puede hacer cada clave

Al crear la clave, marcas los permisos. Una ruta sin el permiso responde 403.

appointments.read: Ver las citas: fecha, hora, servicio, quién atiende y el nombre de quien viene. Nunca el código de la cita.
appointments.write: Agendar en un horario libre, reprogramar y cancelar con el motivo, con las mismas reglas y correos del panel.
clients.read: Ver los clientes: nombre, teléfono, correo y cumpleaños. Nunca las notas, las fichas ni las fotos.
clients.write: Dar de alta un cliente nuevo. Quien ya existe no cambia por la API.
services.read: Ver los servicios, la duración y el precio.
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.

Escribir sin repetir

Agendar, reprogramar, cancelar y dar de alta piden la cabecera Idempotency-Key, con un valor nuevo para cada acción (sirve un UUID). Si la red falla y tu sistema envía de nuevo con la misma clave y el mismo cuerpo, Ruche devuelve la misma respuesta, sin agendar dos veces. La misma clave con otro cuerpo responde 409. La respuesta se guarda durante 24 horas.

Avisos para tu sistema

En Integraciones, pon una dirección https y marca cuándo avisar. Cada aviso es un POST en JSON con el tipo, un id único y el id y la hora de lo que cambió. El nombre, el teléfono y los valores nunca van en el aviso: tu sistema busca el resto por la API, con una clave.

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.createdCita agendada
appointment.confirmedCita confirmada
appointment.cancelledCita cancelada
appointment.rescheduledCita reprogramada
client.createdCliente nuevo
payment.receivedPago recibido
sale.createdVenta registrada

Cada aviso se firma con HMAC SHA-256 en la cabecera x-ruche-signature, con el secreto de la dirección. Compruébalo antes de fiarte.

Ejemplos

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

Probar la clave

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

Las citas de octubre

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

Agendar una cita

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

Límites y respuestas

Hasta 120 peticiones por minuto por clave. Si se supera, la respuesta es 429 con Retry-After.
401: clave ausente, errónea o revocada.
402: el plan del negocio no incluye integraciones.
403: la clave no tiene el permiso de la ruta.
409: horario ocupado, cliente que ya existe o Idempotency-Key repetida con otro cuerpo.

Especificación OpenAPI

Todas las rutas, los campos y las respuestas están en el archivo OpenAPI 3.1, generado a partir de los mismos esquemas que validan las peticiones. Impórtalo en Postman, en Insomnia o en el generador de código que uses.

Descargar openapi.json Paso a paso en el centro de ayuda