نظرة عامة
تتيح واجهة إكزوميشنز لأنظمتك تشغيل تدفق ومتابعة ما حدث للتشغيل. نقطتا دخول تقبلان مفتاح 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)إنشاء مفتاح
- سجّل الدخول بدور مدير أو مالك وافتح مفاتيح API من الشريط الجانبي.
- سمِّ المفتاح واختر صلاحياته، وتاريخ انتهاء إن رغبت.
- انسخ المفتاح عند ظهوره. يُعرض مرة واحدة ولا يُخزَّن منه إلا تجزئة SHA-256 وأول 8 أحرف.
الصلاحيات
| الصلاحية | ما تتيحه |
|---|---|
| execute | تشغيل التدفقات عبر HTTP و MCP وقراءة التشغيلات عبر MCP. وهي الافتراضية. |
| build | استخدام أدوات البناء في MCP: البحث في التطبيقات وإنشاء التدفقات وتعديلها والتحقق منها، وتفعيل التدفقات الموجودة في بيئة الاختبار. |
يعرض النموذج أيضاً «قراءة البيانات». لا يفحصها أي مسار اليوم، لذلك فهي وحدها لا تفتح أياً من نقطتي الدخول.
- المفتاح يخص مساحة عمل واحدة ويعمل مع كل تدفقاتها.
- المفتاح المنتهي يُرفض برمز 403. لتدوير مفتاح أنشئ مفتاحاً جديداً واحذف القديم.
- إنشاء المفاتيح وحذفها يُسجَّل في سجل التدقيق.
بدء تشغيل
/api/trigger/{flowId}يبدأ تشغيلاً واحداً لتدفق مفعّل. يتطلب صلاحية execute.
/api/trigger/{tenantId}/{flowId}الطلب نفسه مع معرّف مساحة العمل في المسار. يجب أن يطابق مساحة عمل المفتاح.
الطلب
| الجزء | القيمة |
|---|---|
| X-Api-Key | مفتاح API. إلزامي. |
| Content-Type | application/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"}}'const res = await fetch("https://exomations.com/api/trigger/YOUR_FLOW_ID", {
method: "POST",
headers: {
"X-Api-Key": process.env.EXOMATIONS_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ order_id: "1042" }),
});
const run = await res.json(); // { executionId, status: "queued" }
if (res.status !== 202) throw new Error(run.error);import os, requests
res = requests.post(
"https://exomations.com/api/trigger/YOUR_FLOW_ID",
headers={"X-Api-Key": os.environ["EXOMATIONS_KEY"]},
json={"order_id": "1042"},
timeout=15,
)
res.raise_for_status()
run = res.json() # {"executionId": "...", "status": "queued"}تعرض صفحة مفاتيح API صيغة الرابط. ومن الإعدادات ← قنوات الاتصال ← Webhook تحصل على الرابط الكامل للتدفق الذي تختاره.
لكل نقطة نهاية صفحة مرجع خاصة بها فيها كل الاستجابات وأمثلة الشيفرة بـ cURL وJavaScript وPython: تشغيل تدفق وتشغيل تدفق (مساحة العمل في المسار).
الردود
الطلب المقبول يُرَدّ عليه دائماً بالرمز 202. وحقل status يخبرك بما حدث:
{
"executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
"status": "queued"
}{
"executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
"status": "held",
"message": "Accepted and held: the workspace is over its monthly execution allowance. The run is recorded and starts automatically after a top-up or upgrade, or when the month resets."
}{
"executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
"status": "duplicate_suppressed",
"message": "An identical payload was received for this flow moments ago; this delivery was deduplicated."
}| الحالة | المعنى |
|---|---|
| queued | سُجّل التشغيل وينتظر منفّذاً. |
| held | تجاوزت مساحة العمل 120% من حصتها الشهرية. يبدأ التشغيل تلقائياً بعد شحن أو ترقية أو بداية الشهر الجديد. |
| duplicate_suppressed | وصل المحتوى نفسه إلى التدفق نفسه خلال 10 ثوانٍ. لم يبدأ تشغيل ثانٍ. |
التواقيع
للتأكد من أن الطلب صادر فعلاً من نظامك، اضبط سر توقيع في الإعدادات ← إعدادات Webhook. بعد ضبطه يجب أن يحمل كل طلب تشغيل توقيعاً صحيحاً إضافة إلى مفتاح API. دون سر مضبوط تُتجاهل ترويسات التوقيع.
| الصيغة | الترويسة | القيمة |
|---|---|---|
| custom | X-Webhook-Signature | HMAC-SHA256 للمحتوى الخام بصيغة hex صغيرة |
| github | X-Hub-Signature-256 | sha256=<hex> |
| shopify | X-Shopify-Hmac-SHA256 | HMAC-SHA256 للمحتوى الخام بصيغة Base64 |
| stripe | Stripe-Signature | t=<timestamp>,v1=<hex> وتُقبل خلال 300 ثانية |
| clickup | X-Signature | HMAC-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,
});import hashlib, hmac, json, os, requests
body = json.dumps({"order_id": "1042"}).encode() # sign the exact bytes you send
signature = hmac.new(
os.environ["EXOMATIONS_WEBHOOK_SECRET"].encode(), body, hashlib.sha256
).hexdigest()
requests.post(
"https://exomations.com/api/trigger/YOUR_FLOW_ID",
data=body,
headers={
"X-Api-Key": os.environ["EXOMATIONS_KEY"],
"X-Webhook-Signature": signature,
"Content-Type": "application/json",
},
)التسليمات المكررة
المحتويات المتطابقة المرسلة إلى التدفق نفسه خلال 10 ثوانٍ تُعامل كتسليم واحد. لا توجد ترويسة لمفتاح عدم التكرار. إن كان مرسِلك قد يعيد المحاولة بعد ذلك فأضف خطوة حارس التكرار في بداية التدفق واربطها بحقل من حمولتك مثل رقم الطلب.
دورة حياة التشغيل
| الحالة | المعنى |
|---|---|
| queued | ينتظر البدء. |
| running | الخطوات قيد التنفيذ. |
| waiting_approval | متوقف عند خطوة موافقة حتى يقرر شخص. |
| retrying | فشلت خطوة وتُعاد محاولتها. |
| success | انتهت كل الخطوات. |
| partially_succeeded | انتهى التشغيل وفشلت بعض الخطوات. |
| failed | توقف التشغيل بسبب خطأ. |
| rejected | رفضه صاحب الموافقة. |
| skipped | لم يكن التشغيل لازماً ولم يفعل شيئاً. |
| held | ينتظر الحصة الشهرية. |
السعة
| الباقة | تشغيلات في الوقت نفسه | تشغيلات في الشهر |
|---|---|---|
| Starter | 25 | 5,000 |
| Professional | 50 | 10,000 |
| Enterprise | 100 | 25,000 |
- التشغيلات التي تتجاوز حد التزامن تنتظر في الطابور. والتشغيل الذي ينتظر أكثر من ساعة يفشل برسالة واضحة ويمكن إعادة تشغيله.
- تُنبَّه عند 100% من الحصة الشهرية، وتستمر التشغيلات حتى 120%، وبعدها تُعلَّق التشغيلات الجديدة ولا تُفقد.
متابعة تشغيل
احتفظ بـ executionId من رد التشغيل. يمكنك متابعة التشغيل بثلاث طرق:
- من عميل ذكاء اصطناعي أو سكربت بمفتاحك: استدعِ أداة MCP
exo_get_execution. تعيد الحالة والتوقيت ومدخلات كل خطوة ومخرجاتها وخطأها. راجع دليل خادم MCP. - اجعل التدفق يخبرك: اختم التدفق بخطوة طلب 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 | الرسالة | ما العمل |
|---|---|---|
| 400 | Flow is not active | فعّل التدفق ثم أعد الطلب. |
| 401 | API key required. Include X-Api-Key header. | أضف الترويسة. |
| 401 | Webhook signature verification failed | تحقق من السر ووقّع المحتوى الخام. |
| 401 | No webhook signature header found... | سر التوقيع مضبوط؛ أرسل ترويسة التوقيع. |
| 403 | Invalid or inactive API key | تحقق من المفتاح أو أنشئ مفتاحاً جديداً. |
| 403 | API key expired | أنشئ مفتاحاً جديداً. |
| 403 | API key lacks execute permission | استخدم مفتاحاً بصلاحية execute. |
| 403 | API key does not match tenant | معرّف مساحة العمل في المسار ليس مساحة عمل المفتاح. |
| 403 | Tenant not found or suspended | مساحة العمل موقوفة أو لم تعد موجودة. |
| 404 | Flow not found | تحقق من معرّف التدفق. تدفقات المساحات الأخرى ترد كذلك بـ 404. |
| 413 | request entity too large | أرسل جسماً أصغر (حتى 8 ميغابايت). |
| 413 | Payload nesting exceeds the depth limit of 64 | بسّط الجسم: 64 مستوى تداخل على الأكثر و500,000 مفتاح. |
| 413 | The compressed request body expands far beyond its compressed size. Send it uncompressed or split it. | أرسل الجسم دون ضغط، أو قسّمه. |
| 429 | Too many requests, please try again later | انتظر مدة Retry-After. |
| 500 | Trigger failed | أعد المحاولة؛ وإن تكرر فتواصل مع الدعم. |
المرجع الكامل
مسارات التطبيق نفسه (المشاريع والتدفقات والاتصالات والموافقات والمستخدمون والإعدادات والاستخدام) تتطلب رمز جلسة مسجّلة الدخول لا مفتاح API، وليست جزءاً من الـ API العام؛ وعلى السكربتات والتكاملات استخدام مفتاح API مع نقطتي الدخول أعلاه.
/docs/openapi.jsonنقطتا التشغيل ونقطة MCP في ملف OpenAPI 3.1. ولكل صفحة مرجع نسخة Markdown مدرجة في /llms.txt.
