/api/trigger/{flowId}يرسل جسم الطلب إلى خطوة المشغّل في التدفق ويسجّل تشغيلاً واحداً. يردّ الطلب فوراً بالرمز 202 ومعرّف التنفيذ، ولا ينتظر انتهاء التدفق أبداً. يجب أن يكون التدفق نشطاً وأن ينتمي إلى مساحة عمل المفتاح.
للأدوات ووكلاء الذكاء الاصطناعي: هذه الصفحة بصيغة Markdown · ملف OpenAPI العام
معاملات المسار
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
flowId | string | نعم | معرّف التدفق. يجب أن يكون التدفق نشطاً وأن ينتمي إلى مساحة عمل المفتاح. |
الترويسات
| الاسم | مطلوب | الوصف |
|---|---|---|
| X-Api-Key | نعم | مفتاح API الخاص بك: exo_ تليها 64 خانة ست عشرية. |
| Content-Type | لا | أرسل application/json. من دونه لا يُقرأ الجسم: يُقبل الطلب مع ذلك ويبدأ التشغيل ببيانات مشغّل فارغة. |
| X-Webhook-Signature | لا | مطلوب فقط عند ضبط سرّ توقيع لمساحة العمل: قيمة HMAC-SHA256 للجسم الخام بصيغة ست عشرية بأحرف صغيرة. الصيغ الأخرى المقبولة مذكورة في مرجع API. |
الجسم
أي كائن JSON حتى 8 ميغابايت. يصبح بيانات المشغّل للتشغيل، ويُقرأ أي حقل في التدفق هكذا: {{trigger.order_id}}. لا يُفحص الجسم وفق مخطط.
الاستجابات
202
مقبول. يوضح الحقل status ما حدث: queued (التشغيل ينتظر عاملاً)، أو held (تجاوزت مساحة العمل 120% من حصتها الشهرية، ويبدأ التشغيل تلقائياً بعد الشحن أو الترقية أو بداية الشهر)، أو duplicate_suppressed (وصل الجسم نفسه إلى التدفق نفسه خلال 10 ثوانٍ ولم يبدأ تشغيل ثانٍ؛ وexecutionId هو تشغيل التسليم الأول، أو null إذا لم يكن معروفاً).
{
"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."
}| الحالة | المعنى | الرسالة |
|---|---|---|
| 400 | التدفق موجود لكنه غير نشط. | Flow is not active |
| 401 | الترويسة X-Api-Key مفقودة، أو أن سرّ توقيع مضبوط والتوقيع مفقود أو غير مطابق. | API key required. Include X-Api-Key header. · Webhook signature verification failed |
| 403 | المفتاح غير معروف أو غير نشط أو منتهي الصلاحية، أو لا يحمل execute، أو أن مساحة العمل موقوفة. | Invalid or inactive API key · API key expired · API key lacks execute permission · Tenant not found or suspended |
| 404 | لا يوجد تدفق بهذا المعرّف في مساحة عمل المفتاح. تدفقات مساحات العمل الأخرى تردّ أيضاً بالرمز 404. | Flow not found |
| 429 | طلبات كثيرة خلال دقيقة. انتظر عدد الثواني المذكور في الترويسة Retry-After. | Too many requests, please try again later · Rate limit exceeded for webhook triggers · Rate limit exceeded: too many trigger calls for this workspace in the last minute. Retry shortly. |
| 413 | الجسم أكبر من 8 ميغابايت، أو يتداخل لأكثر من 64 مستوى، أو فيه أكثر من 500,000 مفتاح، أو أُرسل مضغوطاً ويتمدد إلى أضعاف حجمه المضغوط بكثير. الجسم الأكبر من الحجم يُرفض قبل البحث عن التدفق وفي ردّه حقل message وحده؛ والحالات الأخرى تردّ { error, code, message }. | request entity too large · Payload nesting exceeds the depth limit of 64 · The compressed request body expands far beyond its compressed size. Send it uncompressed or split it. |
| 500 | تعذّر تسجيل التشغيل. أعد المحاولة، وإذا تكرر ذلك فتواصل مع الدعم. | Trigger failed |
تظهر الرسائل كما يرسلها الخادم تماماً، بالإنجليزية. القيمة بين علامتي < > تُملأ وقت التشغيل.
أمثلة
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, // exo_...
"Content-Type": "application/json",
},
body: JSON.stringify({ order_id: "1042", customer: { phone: "+9665XXXXXXXX" } }),
});
const run = await res.json();
if (res.status !== 202) throw new Error(run.error);
console.log(run.executionId, run.status); // "queued", "held" or "duplicate_suppressed"import os, requests
res = requests.post(
"https://exomations.com/api/trigger/YOUR_FLOW_ID",
headers={"X-Api-Key": os.environ["EXOMATIONS_KEY"]}, # exo_...
json={"order_id": "1042", "customer": {"phone": "+9665XXXXXXXX"}},
timeout=15,
)
run = res.json()
if res.status_code != 202:
raise RuntimeError(run["error"])
print(run["executionId"], run["status"])