واجهة Ruche البرمجية

موقعك أو جدول بيانات أو Zapier أو Make أو n8n أو نظام صُنع لك، تتواصل مع Ruche عبر مفتاح. تقرأ الجدول والعملاء والخدمات، وتحجز المواعيد وتعيد جدولتها وتلغيها، وتستلم تنبيهًا مع كل تغيير.

في خطتي Solo والفريق، لصاحب العمل والشركاء. كل مفتاح يرى عمله فقط.

كيف تحصل على المفتاح

في اللوحة، افتح الإعدادات واضغط على «التكاملات».
اضغط على «إنشاء مفتاح»، وسمّه، وحدد ما يمكنه فعله.
انسخ المفتاح في الحال: يبدأ بـ rk_live_ ولا يظهر مرة أخرى.

أرسل المفتاح في ترويسة Authorization: Bearer مع كل طلب. استدعِ الواجهة من خادم نظامك، لا من صفحة ينزّلها متصفح الزائر: هناك يصبح المفتاح مكشوفًا للجميع.

ما يمكن لكل مفتاح فعله

عند إنشاء المفتاح، تحدد النطاقات. المسار دون نطاقه يردّ بالخطأ 403.

appointments.read: عرض المواعيد: التاريخ والساعة والخدمة ومن يقدّمها واسم القادم. وليس رمز الموعد أبدًا.
appointments.write: الحجز في موعد متاح، وإعادة الجدولة، والإلغاء مع السبب، بالقواعد ورسائل البريد الإلكتروني نفسها في اللوحة.
clients.read: عرض العملاء: الاسم والهاتف والبريد الإلكتروني وعيد الميلاد. وليس الملاحظات ولا الملفات ولا الصور أبدًا.
clients.write: تسجيل عميل جديد. من هو موجود لا يتغير عبر الواجهة.
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 وحدد متى ننبّه. كل تنبيه طلب POST بصيغة JSON مع النوع ومعرّف فريد ومعرّف ما تغيّر ووقته. لا يُرسل في التنبيه اسم ولا هاتف ولا مبالغ: يجلب نظامك الباقي عبر الواجهة، بمفتاح.

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عملية بيع مسجّلة

يُوقَّع كل تنبيه بـ HMAC SHA-256 في ترويسة x-ruche-signature، بسر العنوان. تحقق منه قبل أن تثق.

أمثلة

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 طلبًا في الدقيقة لكل مفتاح. عند التجاوز، يكون الرد 429 مع Retry-After.
401: المفتاح غائب أو خاطئ أو ملغى.
402: خطة العمل لا تتضمن التكاملات.
403: المفتاح لا يملك نطاق المسار.
409: موعد مشغول، أو عميل موجود، أو Idempotency-Key مكرر مع محتوى آخر.

مواصفات OpenAPI

جميع المسارات والحقول والردود في ملف OpenAPI 3.1، المولَّد من المخططات نفسها التي تتحقق من الطلبات. استورده في Postman أو Insomnia أو مولّد الشيفرة الذي تستخدمه.

تنزيل openapi.json خطوات مفصلة في مركز المساعدة