المطورون

    مرجع API

    شغّل التدفقات من أنظمتك وتابع كل تشغيل.

    نظرة عامة

    تتيح واجهة إكزوميشنز لأنظمتك تشغيل تدفق ومتابعة ما حدث للتشغيل. نقطتا دخول تقبلان مفتاح API:

    نقطة الدخولالاستخدام
    POST /api/trigger/{flowId}تشغيل تدفق مفعّل مع حمولة JSON.
    POST /api/mcpتشغيل التدفقات وقراءة التشغيلات وبناء التدفقات من عميل ذكاء اصطناعي. راجع دليل خادم MCP.

    العنوان الأساسي: https://exomations.com. إن كانت مساحة عملك تستخدم نطاقها الخاص فالمسارات نفسها تعمل عليه.

    لا تحمل المسارات رقم إصدار (لا يوجد /v1)، ولا توجد سياسة إصدارات منفصلة بعد.

    كل تشغيل غير متزامن. يعود طلب التشغيل فوراً بمعرّف التنفيذ ولا ينتظر انتهاء التدفق.

    المصادقة

    أرسل مفتاحك في ترويسة X-Api-Key مع كل طلب. لا تُقبل المفاتيح في عنوان URL إطلاقاً.

    X-Api-Key: exo_3f9a...   (exo_ followed by 64 hex characters)

    إنشاء مفتاح

    1. سجّل الدخول بدور مدير أو مالك وافتح مفاتيح API من الشريط الجانبي.
    2. سمِّ المفتاح واختر صلاحياته، وتاريخ انتهاء إن رغبت.
    3. انسخ المفتاح عند ظهوره. يُعرض مرة واحدة ولا يُخزَّن منه إلا تجزئة SHA-256 وأول 8 أحرف.

    الصلاحيات

    الصلاحيةما تتيحه
    executeتشغيل التدفقات عبر HTTP و MCP وقراءة التشغيلات عبر MCP. وهي الافتراضية.
    buildاستخدام أدوات البناء في MCP: البحث في التطبيقات وإنشاء التدفقات وتعديلها والتحقق منها، وتفعيل التدفقات الموجودة في بيئة الاختبار.

    يعرض النموذج أيضاً «قراءة البيانات». لا يفحصها أي مسار اليوم، لذلك فهي وحدها لا تفتح أياً من نقطتي الدخول.

    • المفتاح يخص مساحة عمل واحدة ويعمل مع كل تدفقاتها.
    • المفتاح المنتهي يُرفض برمز 403. لتدوير مفتاح أنشئ مفتاحاً جديداً واحذف القديم.
    • إنشاء المفاتيح وحذفها يُسجَّل في سجل التدقيق.

    بدء تشغيل

    POST/api/trigger/{flowId}

    يبدأ تشغيلاً واحداً لتدفق مفعّل. يتطلب صلاحية execute.

    POST/api/trigger/{tenantId}/{flowId}

    الطلب نفسه مع معرّف مساحة العمل في المسار. يجب أن يطابق مساحة عمل المفتاح.

    الطلب

    الجزءالقيمة
    X-Api-Keyمفتاح API. إلزامي.
    Content-Typeapplication/json
    X-Webhook-Signatureإلزامية فقط عند ضبط سر توقيع لمساحة العمل. راجع التواقيع.
    bodyأي كائن JSON حتى 8 ميغابايت. يصبح بيانات المشغّل؛ اقرأ الحقل في التدفق هكذا {{trigger.order_id}}.
    curl -X POST https://exomations.com/api/trigger/YOUR_FLOW_ID \
      -H "X-Api-Key: exo_your_key" \
      -H "Content-Type: application/json" \
      -d '{"order_id": "1042", "customer": {"phone": "+9665XXXXXXXX"}}'

    تعرض صفحة مفاتيح API صيغة الرابط. ومن الإعدادات ← قنوات الاتصال ← Webhook تحصل على الرابط الكامل للتدفق الذي تختاره.

    لكل نقطة نهاية صفحة مرجع خاصة بها فيها كل الاستجابات وأمثلة الشيفرة بـ cURL وJavaScript وPython: تشغيل تدفق وتشغيل تدفق (مساحة العمل في المسار).

    الردود

    الطلب المقبول يُرَدّ عليه دائماً بالرمز 202. وحقل status يخبرك بما حدث:

    {
      "executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
      "status": "queued"
    }
    الحالةالمعنى
    queuedسُجّل التشغيل وينتظر منفّذاً.
    heldتجاوزت مساحة العمل 120% من حصتها الشهرية. يبدأ التشغيل تلقائياً بعد شحن أو ترقية أو بداية الشهر الجديد.
    duplicate_suppressedوصل المحتوى نفسه إلى التدفق نفسه خلال 10 ثوانٍ. لم يبدأ تشغيل ثانٍ.

    التواقيع

    للتأكد من أن الطلب صادر فعلاً من نظامك، اضبط سر توقيع في الإعدادات ← إعدادات Webhook. بعد ضبطه يجب أن يحمل كل طلب تشغيل توقيعاً صحيحاً إضافة إلى مفتاح API. دون سر مضبوط تُتجاهل ترويسات التوقيع.

    الصيغةالترويسةالقيمة
    customX-Webhook-SignatureHMAC-SHA256 للمحتوى الخام بصيغة hex صغيرة
    githubX-Hub-Signature-256sha256=<hex>
    shopifyX-Shopify-Hmac-SHA256HMAC-SHA256 للمحتوى الخام بصيغة Base64
    stripeStripe-Signaturet=<timestamp>,v1=<hex> وتُقبل خلال 300 ثانية
    clickupX-SignatureHMAC-SHA256 للمحتوى الخام بصيغة hex
    auto—الافتراضية. تكتشف أي ترويسة من أعلاه موجودة.
    import crypto from "node:crypto";
    
    const body = JSON.stringify({ order_id: "1042" });   // sign the exact bytes you send
    const signature = crypto
      .createHmac("sha256", process.env.EXOMATIONS_WEBHOOK_SECRET)
      .update(body)
      .digest("hex");
    
    await fetch("https://exomations.com/api/trigger/YOUR_FLOW_ID", {
      method: "POST",
      headers: {
        "X-Api-Key": process.env.EXOMATIONS_KEY,
        "X-Webhook-Signature": signature,
        "Content-Type": "application/json",
      },
      body,
    });
    وقّع البايتات نفسها التي ترسلها. إعادة تحويل JSON بعد التوقيع تغيّر البايتات فيفشل التحقق برمز 401.

    التسليمات المكررة

    المحتويات المتطابقة المرسلة إلى التدفق نفسه خلال 10 ثوانٍ تُعامل كتسليم واحد. لا توجد ترويسة لمفتاح عدم التكرار. إن كان مرسِلك قد يعيد المحاولة بعد ذلك فأضف خطوة حارس التكرار في بداية التدفق واربطها بحقل من حمولتك مثل رقم الطلب.

    دورة حياة التشغيل

    الحالةالمعنى
    queuedينتظر البدء.
    runningالخطوات قيد التنفيذ.
    waiting_approvalمتوقف عند خطوة موافقة حتى يقرر شخص.
    retryingفشلت خطوة وتُعاد محاولتها.
    successانتهت كل الخطوات.
    partially_succeededانتهى التشغيل وفشلت بعض الخطوات.
    failedتوقف التشغيل بسبب خطأ.
    rejectedرفضه صاحب الموافقة.
    skippedلم يكن التشغيل لازماً ولم يفعل شيئاً.
    heldينتظر الحصة الشهرية.

    السعة

    الباقةتشغيلات في الوقت نفسهتشغيلات في الشهر
    Starter255,000
    Professional5010,000
    Enterprise10025,000
    • التشغيلات التي تتجاوز حد التزامن تنتظر في الطابور. والتشغيل الذي ينتظر أكثر من ساعة يفشل برسالة واضحة ويمكن إعادة تشغيله.
    • تُنبَّه عند 100% من الحصة الشهرية، وتستمر التشغيلات حتى 120%، وبعدها تُعلَّق التشغيلات الجديدة ولا تُفقد.

    متابعة تشغيل

    احتفظ بـ executionId من رد التشغيل. يمكنك متابعة التشغيل بثلاث طرق:

    • من عميل ذكاء اصطناعي أو سكربت بمفتاحك: استدعِ أداة MCP exo_get_execution. تعيد الحالة والتوقيت ومدخلات كل خطوة ومخرجاتها وخطأها. راجع دليل خادم MCP.
    • اجعل التدفق يخبرك: اختم التدفق بخطوة طلب HTTP ترسل النتيجة إلى نظامك. هذه طريقة الحصول على إشعار عند الانتهاء.
    • في التطبيق: افتح التنفيذات لترى كل تشغيل خطوة بخطوة.
    ليس لنقطة التشغيل معامل لعنوان الإشعار، ورد HTTP لا ينتظر التدفق أبداً.

    حدود المعدل

    يُسمح لكل جهة مرسِلة بما يصل إلى 100 طلب في الدقيقة لمجموع طلبات API و MCP. والأرقام الأعلى أدناه حدود قصوى لا حصص إضافية.

    الحدفي الدقيقةيُحسب لكل
    كل الطلبات، API و MCP معاً100جهة مرسِلة
    طلبات التشغيل، حد أقصى200تدفق
    طلبات MCP، حد أقصى200مفتاح API
    طلبات MCP لمساحة العمل كلها100 / 200 / 500مساحة عمل، حسب الباقة

    الطلب الذي يتجاوز الحد يحصل على 429. تحمل الردود الترويسات القياسية RateLimit-Limit وRateLimit-Remaining وRateLimit-Reset، ويحمل رد 429 ترويسة Retry-After. انتظر تلك المدة قبل إعادة المحاولة.

    {
      "error": "Too many requests, please try again later",
      "code": "RATE_LIMIT",
      "message": "Too many requests, please try again later"
    }

    الأخطاء

    الأخطاء بصيغة JSON: يحمل error النص، ويكرره message، ويذكر code نوع الخطأ (مثل FORBIDDEN).

    HTTPالرسالةما العمل
    400Flow is not activeفعّل التدفق ثم أعد الطلب.
    401API key required. Include X-Api-Key header.أضف الترويسة.
    401Webhook signature verification failedتحقق من السر ووقّع المحتوى الخام.
    401No webhook signature header found...سر التوقيع مضبوط؛ أرسل ترويسة التوقيع.
    403Invalid or inactive API keyتحقق من المفتاح أو أنشئ مفتاحاً جديداً.
    403API key expiredأنشئ مفتاحاً جديداً.
    403API key lacks execute permissionاستخدم مفتاحاً بصلاحية execute.
    403API key does not match tenantمعرّف مساحة العمل في المسار ليس مساحة عمل المفتاح.
    403Tenant not found or suspendedمساحة العمل موقوفة أو لم تعد موجودة.
    404Flow not foundتحقق من معرّف التدفق. تدفقات المساحات الأخرى ترد كذلك بـ 404.
    413request entity too largeأرسل جسماً أصغر (حتى 8 ميغابايت).
    413Payload nesting exceeds the depth limit of 64بسّط الجسم: 64 مستوى تداخل على الأكثر و500,000 مفتاح.
    413The compressed request body expands far beyond its compressed size. Send it uncompressed or split it.أرسل الجسم دون ضغط، أو قسّمه.
    429Too many requests, please try again laterانتظر مدة Retry-After.
    500Trigger failedأعد المحاولة؛ وإن تكرر فتواصل مع الدعم.

    المرجع الكامل

    مسارات التطبيق نفسه (المشاريع والتدفقات والاتصالات والموافقات والمستخدمون والإعدادات والاستخدام) تتطلب رمز جلسة مسجّلة الدخول لا مفتاح API، وليست جزءاً من الـ API العام؛ وعلى السكربتات والتكاملات استخدام مفتاح API مع نقطتي الدخول أعلاه.

    GET/docs/openapi.json

    نقطتا التشغيل ونقطة MCP في ملف OpenAPI 3.1. ولكل صفحة مرجع نسخة Markdown مدرجة في /llms.txt.

    ابنِ أول تكامل لك اليوم.

    تجربة 7 أيامتحقق من البطاقة بمبلغ 1 ريالمستضاف في الرياض