الـ API

مفيش نقطة وصول خاصة. ولا حتى للواجهة نفسها.

معظم المنتجات ليها اتنين API: واحد موثّق هو اللي بيقدّمولك، وواحد تاني هو اللي شاشاتهم الخاصة شغالة بيه. التاني دايماً بيبقى أحسن، ومستحيل يسمحولك تقرب منه. هنا فيه واحد بس، والواجهة نفسها عميل ليه زي أي حاجة تانية — وده قيد علينا احنا، وده سبب إن كل حاجة انت عايز تبنيها تبقى ممكنة.

ايه اللي القاعدة دي بتكلّفه فعلاً

يعني الشاشة ساعات بتضطر تستنى لحد ما الـ API يبقى مظبوط، بدل ما تلّف حواليه عشان حقل واحد مريح. اليوم اللي الشاشة محتاجة فيه حاجة الـ API العام مش قادر يديهالها، هو نفسه اليوم اللي الـ API يكون فيه غلط، والحل يبقى في الـ API نفسه.

العائد إن تلات عملاء مختلفين عن بعض جدًّا تكلفتهم الإضافية تقريباً صفر. سيرفر الـ MCP عميل. بلاطة في dash-b عميل. البرنامج النصي بتاعك عميل. ولا واحد فيهم مواطن درجة تانية بيلتف حوالين واجهة معمولة لحد غيرو، لأن مفيش واجهة تانية أصلاً يبقى هو تاني عليها.

موثّق، ومُختبر فعلاً

الـ OpenAPI بيتولّد على /docs، وكل مسار عليه اختبار هو بالظبط المثال الموجود في التوثيق. التوثيق اللي بيتكتب منفصل عن الكود بيبدأ يبعد عن الواقع جوه شهر؛ التوثيق اللي بيوقّع البناء لما يطلع غلط، عمره ما بيبدأ يبعد.

حساب castomo بتاعك، عن طريق تدفق كود التفويض مع PKCE — نفس الحساب اللي بتستخدمه مع dash-b وباقي العيلة. صفحة ملهاش سيرفر خاص بيها بتعدّي التدفق ده تمام؛ ده أصلاً اللي التدفق اتصمم عشانه. وللشغل من نظام لنظام، مفتاح API محصور على المشروع.

الواجهةapi.clicksomo.com

1الأشخاص/v1/contacts · /lists · /segments · /tags · /imports
2المحتوى/v1/creatives، مع التحقق والمعاينة والعرض لكل هدف
3أتمتة/v1/funnels · /funnels/:id/versions · /runs · /simulate
4بث/v1/campaigns، والجمهور والتجهيز والجدولة والإرسال خطوات منفصلة
5أحداث واردة/v1/events — أحداث تطبيقك انت، كمحفزات
6التسليم/sender-identities · /domains · /apps · /webhooks
7الأرقام/v1/reports/*، و/track/* على سيرفر التتبع

OpenAPI على /docs/mcp على نفس العملية

الاتفاقيات

نفس شكل باقي خدمات castomo كلها

وده مهم أكتر مما بيلمح. لو انت أصلاً بتكلم واحدة منهم، يبقى انت عارف الخدمة دي هترود إزاي، وهتفشل إزاي، وبتقسّم صفحاتها إزاي.

غلاف خطأ واحد

كل فشل ليه نفس الشكل: كود ثابت، ورسالة معمولة لإنسان يقراها. ولا مسار بيخترع لنفسه طريقة خاصة عشان يزعّق.

ترقيم صفحات بالمؤشر

مش إزاحات. القايمة اللي بتتغيّر وانت ماشي فيها مش بتنطّ ولا بتكرر صفوف في صمت — ودي حاجة ترقيم الإزاحة بيعملها بهدوء وباستمرار.

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

على كل مسار بيعدّل حاجة. كرّر أي طلب مش متأكد إنه وصل، وهتاخد نفس الإجابة بدل جهة اتصال تانية أو حملة تانية أو إرسال تاني.

محصور على المشروع

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

Webhooks صادرة

موقّعة، وبيتكرر محاولة إرسالها بفواصل متزايدة، وبتوصل مرة واحدة على الأقل — يعني نقطة الوصول بتاعتك لازم تكون محصّنة ضد التكرار هي كمان. الأحداث هي نفس المفردات اللي التقارير بتستخدمها.

المسح والتصدير

بيانات التواصل ممكن تتصدر أو تمسح عن طريق الـ API، والمسح بيوصل لكل خدمة شقيقة كانت محتفظة بنسخة عن طريق المسار الداخلي الخاص بالعيلة نفسها.

كل حاجة الواجهة تعرف تعملها، الـ POST يعرف يعملها.

الأحداث هي الجزء المهم

كل حاجة تانية في الصفحة دي سباكة متوقعة. POST /v1/events هو المسار اللي بيغيّر اللي المنتج موجود عشانه.

تطبيقك عارف حاجات مفيش أداة تسويق تقدر تشوفها: مين خلّص الإعداد، مين دعّى زميل، مين وصل للحد، مين صدّر بياناته يوم الأحد بعد الضهر. ابعتها كأحداث بتوكن بتاعك، وكل واحدة بتبقى تريجر وشرح وسيجمنت.

الباقي بيجي من موديل التواصل. الأحداث بتتضاف، عمرها ما بتتعدل؛ هي السجل اللي المنتج كله معلّق عليه. فانل بيشتغل على حدّ انت عرّفته مش تكامل — ده نفس الميكانيزم اللي message_opened بيستخدمه، بس باسم مختلف جواه.

الحدث بتاعك بيبقى فانلapi_event

1انت بتبعتهPOST /v1/events — اسم، تواصل، بيلود، ومفتاح idempotency.
2بيوصلبيتضاف لسجل التواصل. مفيش حاجة تانية محتاجة تعرف إنه موجود.
3فانل بيبدأأي فانل مدخله بيسمّي الحدث ده، لأي تواصل مؤهل حسب مواصفات مدخله.
4فوانل تانية بتتفرّع عليه"هل الحدث ده حصل في آخر ١٤ يوم" هو شرح عادي في السيجمنت.
معلومةوبتوقف التشغيلاتنود هدف بتسمّي نفس الحدث بتوقف سلسلة في نفس اللحظة اللي الشخص بيعمل فيها الحاجة.

مصطلحاتكالتوكن بتاعك

حدود تستاهل تعرفها قبل ما تبني

ClickSomo بيخزّن تلاتة معرّفات عنك — tenant و project و user، كـ ids مشفّرة — ومفيش غير كده. مفيش باسورد، مفيش بروفايل، مفيش كارت، مفيش فاتورة. حدود الخطة بتوصل كأرقام: كام تواصل، كام إرسال، كام توليد. مصطلحات الدفع مش بتعدي الخط ده في الاتجاهين.

تواصلاتك ملكك. انت الـ data controller واحنا الـ processor. مفيش أي طريق تاني منتج من العيلة يقدر يقرأ أو يكتب قايمة تواصلاتك، ومفيش مسار ingest يستخدمه حد.

لو بتقيّم الموضوع بجدية: اقرا /docs قبل ما تقرا أي حاجة تانية في الموقع ده. الـ API هو الوصف الصادق للي المنتج بيعمله، وكل ادعاء في الصفحات دي بيرجع لمسار أو نوع نود تلاقيه هناك. لما الـ schema يتغيّر، الصفحات دي بتتغيّر.