واجهة REST والويبهوكس

أي مساحة عمل تقدر تعمل مفاتيح API من الإعدادات، واجهة API. المفتاح بيتصرف زي مساحة العمل كلها، فعامله زي كلمة السر: بيظهر مرة واحدة وقت إنشائه، ومفيش حاجة تقدر تعرضه تاني.

التحقق

ابعت المفتاح العام والسر مع بعض كتوكن bearer، وبينهم نقطتين. الجزء العام مافيش مشكلة يتسجل في اللوج، السر لأ.

curl https://ritmo-api.uritm.com/api/v1/contacts \
  -H "Authorization: Bearer rk_live_XXXX:YOUR_SECRET"

الصلاحيات

المفتاح اللي اتعمل من غير صلاحيات بيقدر يعمل كل حاجة مساحة العمل بتقدر تعملها. اختار صلاحيات عشان تضيّقه — سكربت تقارير معاه contacts:read بس مش هيقدر يبعت رسالة حتى لو اتسرب.

• contacts:read و contacts:write
• messages:read و messages:write
• otp:send
• templates:read
• broadcasts:read و broadcasts:write
• usage:read

النقاط

• GET /api/v1/contacts — بصفحات، وبيقبل search و page و pageSize
• POST /api/v1/contacts — إنشاء جهة اتصال
• GET /api/v1/segments — شرايح الجمهور المحفوظة
• POST /api/v1/messages — رد في محادثة موجودة
• POST /api/v1/otp/send — ابعت SMS من حساب المزود بتاعك
• GET /api/v1/templates — قوالب واتساب المعتمدة
• GET /api/v1/broadcasts و POST /api/v1/broadcasts/:id/start
• GET /api/v1/usage — الشهر ده، لكل قناة

الويبهوكس

ضيف نقطة من الإعدادات، واجهة API. لازم تكون https وعلى استضافة عامة: ريتمو بيرفض العناوين الداخلية، لأن الويبهوك ده طلب سيرفراتنا بتعمله بناءً على كلامك.

كل تسليم بيجي معاه هيدر X-Ritmo-Signature بنفس شكل توقيع Stripe، والوقت جوه المحتوى الموقّع عشان طلب متسجّل ما يتعادش بعدين.

t=1735689600,v1=5257a869e7ecebeda32affa62cdca3fa

اتحقق منه بإعادة حساب HMAC-SHA256 للوقت، ونقطة، وجسم الطلب الخام، بسر النقطة بتاعتك. قارن بوقت ثابت، وارفض أي حاجة أقدم من خمس دقايق.

const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
const expected = crypto
  .createHmac("sha256", endpointSecret)
  .update(`${t}.${rawBody}`)
  .digest("hex");
const ok =
  crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected)) &&
  Math.abs(Date.now() / 1000 - Number(t)) < 300;

إعادة المحاولة

رد بأي كود 2xx. أي حاجة تانية بتتعاد تمن مرات على مدى حوالي أربع ساعات بفواصل بتكبر. عشرين فشل ورا بعض بيوقفوا النقطة وبنبلّغ الأدمن، بدل ما نفضل نجرب على سيرفر ميت للأبد.