API ng Ruche

Ang site mo, isang spreadsheet, Zapier, Make, n8n o sistemang ginawa para sa iyo ay nakikipag-usap sa Ruche gamit ang isang susi. Binabasa nila ang iskedyul, mga kliyente at serbisyo, nagbu-book, naglilipat at nagka-cancel ng oras, at tumatanggap ng abiso sa bawat pagbabago.

Sa mga planong Solo at Team, para sa may-ari at mga kasosyo. Ang bawat susi ay nakakakita lang ng sariling negosyo.

Paano kumuha ng susi

Sa panel, buksan ang Mga Setting at i-tap ang Integrations.
I-tap ang Gumawa ng susi, bigyan ng pangalan at markahan ang puwede nitong gawin.
Kopyahin agad ang susi: nagsisimula ito sa rk_live_ at hindi na ito lalabas ulit.

Ipadala ang susi sa header na Authorization: Bearer ng bawat request. Tawagin ang API mula sa server ng sistema mo, hindi kailanman mula sa pahinang dina-download ng browser ng bumibisita: doon, makikita ng lahat ang susi.

Ang puwedeng gawin ng bawat susi

Sa paggawa ng susi, minamarkahan mo ang mga scope. Ang rutang walang scope ay sumasagot ng 403.

appointments.read: Tingnan ang mga oras: petsa, oras, serbisyo, nagseserbisyo at pangalan ng darating. Hindi kailanman ang code ng oras.
appointments.write: Mag-book sa bakanteng oras, maglipat at magkansela nang may dahilan, na may parehong patakaran at email ng panel.
clients.read: Tingnan ang mga kliyente: pangalan, telepono, email at kaarawan. Hindi kailanman ang mga tala, talaan o larawan.
clients.write: Magrehistro ng bagong kliyente. Ang umiiral na ay hindi nababago sa API.
services.read: Tingnan ang mga serbisyo, haba at presyo.
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.

Magsulat nang hindi inuulit

Ang pag-book, paglipat, pagkansela at pagrehistro ay humihingi ng header na Idempotency-Key, na may bagong halaga sa bawat aksyon (puwede ang UUID). Kung bumagsak ang network at ipinadala ulit ng sistema mo gamit ang parehong susi at parehong katawan, ibabalik ng Ruche ang parehong sagot, nang hindi nagbu-book nang dalawang beses. Ang parehong susi na may ibang katawan ay sumasagot ng 409. Itinatago ang sagot nang 24 oras.

Mga abiso para sa sistema mo

Sa Integrations, maglagay ng https address at markahan kung kailan mag-aabiso. Bawat abiso ay isang POST sa JSON na may uri, natatanging id at ang id at oras ng nagbago. Hindi kailanman kasama sa abiso ang pangalan, telepono at halaga: kukunin ng sistema mo ang iba pa sa API, gamit ang susi.

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.createdNaka-book na oras
appointment.confirmedKumpirmadong oras
appointment.cancelledKinanselang oras
appointment.rescheduledInilipat na oras
client.createdBagong kliyente
payment.receivedNatanggap na bayad
sale.createdNaitalang benta

Bawat abiso ay pinipirmahan ng HMAC SHA-256 sa header na x-ruche-signature, gamit ang sikreto ng address. Suriin bago magtiwala.

Mga halimbawa

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

Subukan ang susi

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

Ang mga oras ng Oktubre

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

Mag-book ng oras

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

Magkansela nang may dahilan

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

Mga limitasyon at sagot

Hanggang 120 request kada minuto bawat susi. Kapag lumampas, 429 ang sagot na may Retry-After.
401: nawawala, mali o binawing susi.
402: walang integrations ang plano ng negosyo.
403: walang scope ng ruta ang susi.
409: okupadong oras, kliyenteng umiiral na o Idempotency-Key na inulit na may ibang katawan.

Detalye ng OpenAPI

Lahat ng ruta, field at sagot ay nasa file na OpenAPI 3.1, na ginawa mula sa parehong schema na nagva-validate ng mga request. I-import sa Postman, Insomnia o sa code generator na ginagamit mo.

I-download ang openapi.json Hakbang-hakbang sa help center