Ruche API

आपकी साइट, एक स्प्रेडशीट, Zapier, Make, n8n या आपके लिए बना सिस्टम एक चाबी से Ruche से बात करते हैं। वे शेड्यूल, ग्राहक और सेवाएँ पढ़ते हैं, अपॉइंटमेंट बुक करते हैं, समय बदलते हैं और रद्द करते हैं, और हर बदलाव पर सूचना पाते हैं।

सोलो और टीम प्लान में, मालिक और साझेदारों के लिए। हर चाबी सिर्फ़ अपना व्यवसाय देखती है।

चाबी कैसे पाएँ

पैनल में सेटिंग्स खोलें और इंटीग्रेशन पर टैप करें।
चाबी बनाएँ पर टैप करें, एक नाम दें और चिह्नित करें कि वह क्या कर सकती है।
चाबी उसी समय कॉपी करें: वह rk_live_ से शुरू होती है और दोबारा नहीं दिखती।

चाबी को हर अनुरोध के Authorization: Bearer हेडर में भेजें। API को अपने सिस्टम के सर्वर से कॉल करें, कभी ऐसे पेज से नहीं जिसे आने वाले का ब्राउज़र डाउनलोड करता है: वहाँ चाबी सबको दिख जाएगी।

हर चाबी क्या कर सकती है

चाबी बनाते समय आप स्कोप चिह्नित करते हैं। जिस रूट का स्कोप न हो वह 403 देता है।

appointments.read: अपॉइंटमेंट देखना: तारीख़, समय, सेवा, कौन सेवा देता है और आने वाले का नाम। अपॉइंटमेंट का कोड कभी नहीं।
appointments.write: खाली समय पर बुक करना, समय बदलना और कारण के साथ रद्द करना, पैनल के वही नियमों और ईमेल के साथ।
clients.read: ग्राहक देखना: नाम, फ़ोन, ईमेल और जन्मदिन। नोट्स, रिकॉर्ड और फ़ोटो कभी नहीं।
clients.write: नया ग्राहक दर्ज करना। जो पहले से है वह API से नहीं बदलता।
services.read: सेवाएँ, अवधि और कीमत देखना।
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.

बिना दोहराए लिखना

बुक करना, समय बदलना, रद्द करना और दर्ज करना Idempotency-Key हेडर माँगते हैं, हर क्रिया के लिए नए मान के साथ (UUID चलता है)। नेटवर्क टूटे और आपका सिस्टम उसी चाबी और उसी बॉडी के साथ फिर भेजे, तो Ruche वही जवाब लौटाता है, दो बार बुक किए बिना। वही चाबी दूसरी बॉडी के साथ 409 देती है। जवाब 24 घंटे सहेजा रहता है।

आपके सिस्टम के लिए सूचनाएँ

इंटीग्रेशन में एक https पता डालें और चिह्नित करें कि कब बताना है। हर सूचना JSON में एक POST है, जिसमें प्रकार, एक अनोखी आईडी, और जो बदला उसकी आईडी और समय होता है। नाम, फ़ोन और रकम कभी सूचना में नहीं जाते: आपका सिस्टम बाकी चाबी के साथ API से लेता है।

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.createdअपॉइंटमेंट तय हुआ
appointment.confirmedअपॉइंटमेंट की पुष्टि हुई
appointment.cancelledअपॉइंटमेंट रद्द हुआ
appointment.rescheduledअपॉइंटमेंट का समय बदला
client.createdनया ग्राहक
payment.receivedभुगतान मिला
sale.createdबिक्री दर्ज हुई

हर सूचना पते के सीक्रेट के साथ x-ruche-signature हेडर में HMAC SHA-256 से हस्ताक्षरित होती है। भरोसा करने से पहले जाँचें।

उदाहरण

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

चाबी जाँचना

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

अक्टूबर के अपॉइंटमेंट

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

अपॉइंटमेंट बुक करना

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

कारण के साथ रद्द करना

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

सीमाएँ और जवाब

हर चाबी पर प्रति मिनट 120 अनुरोध तक। पार करने पर जवाब Retry-After के साथ 429 है।
401: चाबी नहीं है, ग़लत है या रद्द है।
402: व्यवसाय के प्लान में इंटीग्रेशन नहीं है।
403: चाबी के पास रूट का स्कोप नहीं है।
409: अपॉइंटमेंट भरा हुआ है, ग्राहक पहले से है या Idempotency-Key दूसरी बॉडी के साथ दोहराई गई।

OpenAPI विनिर्देश

सभी रूट, फ़ील्ड और जवाब OpenAPI 3.1 फ़ाइल में हैं, उन्हीं स्कीमा से बनी जो अनुरोधों को जाँचते हैं। इसे Postman, Insomnia या अपने कोड जनरेटर में आयात करें।

openapi.json डाउनलोड करें सहायता केंद्र में चरण-दर-चरण