واجهة API لجهات الاتصال والصفقات والرحلات

تتيح هذه النقاط لشيفرتك الخاصة أو لـ Zapier أو n8n العمل على حسابك: إضافة جهات اتصال، وفتح الصفقات ونقلها، وإدخال جهات اتصال في رحلات، وقراءة المعرّفات التي تحتاجها هذه الاستدعاءات. وتستخدم مفتاح API نفسه الذي تستخدمه Send API.

Authorization: Bearer mia_live_...

تسمح كل مجموعة من النقاط بـ 60 طلبًا في الدقيقة لكل مفتاح، وبعد ذلك تحصل على 429. تُرجَع الأخطاء بالشكل {"error": "…"} مع حالة 4xx. العقد الكامل، بما فيه كل أشكال الاستجابة، موجود في مواصفات OpenAPI.

جهات الاتصال

الإنشاء أو التحديث

يضيف POST /api/v1/contacts عنوانًا إلى قائمة جهات اتصال، أو يحدّثه إن كان موجودًا:

{
  "listId": "list_abc123",
  "email": "[email protected]",
  "fields": { "first_name": "Ada", "company": "Analytical Engines" }
}

يُرجع 201 لجهة اتصال جديدة و200 للتحديث، مع جهة الاتصال المحفوظة. لإرسال حتى 500 دفعة واحدة، استخدم {"listId": "…", "contacts": [{"email": "…", "first_name": "…"}, …]}، ويُرجع حينها أعدادًا.

يُتحقَّق من كل عنوان عند حفظه. لا تسجّل الواجهة أبدًا إجابة موافقة، لذا تتلقى جهات الاتصال هذه الرسائل كما كانت. وجهة الاتصال المفردة التي ستتجاوز بها القائمة حد جهات الاتصال في باقتك تحصل على 409.

البحث

يُرجع GET /api/v1/[email protected] جهة اتصال هذا العنوان في كل قائمة، من الأحدث إلى الأقدم. أضف &listId= للبحث في قائمة واحدة فقط. تُسجَّل كل عملية بحث في سجل الوصول إلى البيانات في حسابك، كما يحدث عند عرض جهة اتصال في لوحة التحكم.

القوائم

يُرجع GET /api/v1/lists قيم id وname وfields وrowCount لكل قائمة جهات اتصال، دون أي بيانات لجهات الاتصال.

الصفقات

الإنشاء

POST /api/v1/deals:

{
  "email": "[email protected]",
  "title": "Annual plan",
  "value": 1200,
  "currency": "SAR"
}

حدّد جهة الاتصال عبر email، أو عبر listId مع rowId. إذا لم يتوفر إلا البريد، تُنشأ الصفقة في أحدث قائمة محدَّثة تحتوي على العنوان. ومن دون pipelineId وstageId، تدخل أول مرحلة مفتوحة في مسارك الافتراضي. العملة currency افتراضيًا USD.

أرسل الترويسة Idempotency-Key (رقم طلب مثلًا) لتكون إعادة المحاولة آمنة. التكرار بالمفتاح نفسه يُرجع 200 مع "created": false بدلًا من إنشاء صفقة ثانية.

التحديث أو النقل

يقبل PATCH /api/v1/deals/{id} الحقول title وvalue وcurrency وstageId. النقل إلى مرحلة رابحة أو خاسرة يغلق الصفقة. يُتحقَّق من النص كاملًا أولًا، فلا تغيّر المرحلة غير المعروفة أي شيء. ويُطلق النقل مشغّل الرحلة تغيّر مرحلة صفقة وحدث deal.stage_changed، تمامًا كالنقل على اللوحة.

المسارات

يُرجع GET /api/v1/pipelines مساراتك، والافتراضي أولًا، مع مراحل كل منها (id وname وkind). استخدمه لإيجاد stageId الذي تنقل إليه الصفقة.

الرحلات

يعرض GET /api/v1/journeys رحلاتك مع المعرّف والاسم والمشغّل وحالة التشغيل. ويُرجع ?trigger=api الرحلات التي يمكن لشيفرتك إدخال جهات اتصال فيها فقط.

يُدخل POST /api/v1/journeys/{id}/trigger مع {"email": "…", "listId": "…"} جهة اتصال في رحلة مشغّلها استدعاء API. راجع الرحلات.

أحداث نموذجية

يُرجع GET /api/v1/events/sample?type=deal.stage_changed القيمة {"events": [ … ]} مع غلاف Webhook نموذجي من ذلك النوع، أو نموذجًا لكل نوع إن لم يُحدَّد type. تستخدمه أدوات الأتمتة لتعرض لك الحقول قبل وصول حدث حقيقي.

Webhooks

يدير GET وPOST /api/v1/webhooks وDELETE /api/v1/webhooks/{id} الاشتراكات في الأحداث. راجع Webhooks والأحداث.