واجهة ZeeDo البرمجية

أنشئ مفتاحًا من الإعدادات ← API وWebhooks (يؤكد المالك هويته أولًا)، ثم استدعِ الواجهة البرمجية به كرمز Bearer. عنوان URL الأساسي هو https://api.zeedo.cloud/v1.

curl https://api.zeedo.cloud/v1/me \
  -H "Authorization: Bearer <مفتاح API الخاص بك>"

• تتبع المفاتيح المؤسسة، ولكل منها نطاق: read أو write أو admin، ويمكن قصرها على مساحة عمل واحدة.
• أجسام JSON، وحقول بصيغة snake_case، والأوقات بصيغة ISO 8601 بتوقيت UTC.
• الأخطاء مستندات مشكلات وفق RFC 9457: type وtitle وstatus وdetail، وللحقل المرفوض errors[] مع مؤشر JSON.
• تُقسَّم القوائم إلى صفحات باستخدام limit (200 كحد أقصى) وnext_cursor.
• أرسل ترويسة Idempotency-Key مع كل طلب POST: فأي تكرار خلال 24 ساعة يتلقى الرد نفسه الذي تلقاه الطلب الأول.
• 600 طلب في الدقيقة و10 تدفقات مفتوحة لكل مفتاح، مع ترويسات RateLimit-*.

تسجّل المؤسسة نقطة استقبال واحدة (الإعدادات ← API وWebhooks، أو POST /webhooks) وتختار أحداثها. كل حدث طلب POST بصيغة JSON يحمل المعرّفات والنوع والطوابع الزمنية، ولا يحمل أبدًا اسم شخص أو بريده الإلكتروني أو عنوان IP الخاص به، وهي بيانات تقرؤها عبر الواجهة البرمجية بمفتاح.

{
  "id": "evt_eu_01J9ZQ3M7X5V2K8R4T6Y1N0PBA",
  "type": "run.completed",
  "version": 1,
  "occurred_at": "2026-09-27T10:02:31.000Z",
  "org_id": "org_eu_01J9ZQ1C4H8D6F2W5S7K3M9QXE",
  "data": {
    "run_id": "run_eu_01J9ZQ2V8N4B6C1X3Z5Q7W9ERT",
    "bot_id": "bot_eu_01J9ZQ2A3S5D7F9G1H3J5K7L9M"
  }
}

كل تسليم موقّع: ZeeDo-Signature: t=<ثوانٍ بتوقيت Unix>,v1=<التوقيع>، حيث التوقيع هو HMAC-SHA256 بالترميز الست عشري لـ <t>.<الجسم الخام> باستخدام السر الخاص بنقطة الاستقبال. بعد تغيير السر، يوقّع السر السابق بجانبه لمدة 24 ساعة، كتوقيع v1 ثانٍ. ارفض أي توقيع يزيد عمره على 5 دقيقة.

import { createHmac, timingSafeEqual } from 'node:crypto';

// header: قيمة ZeeDo-Signature؛ body: جسم الطلب الخام، قبل أي تحليل لـ JSON
export function verified(header, body, secret) {
  const parts = header.split(',');
  const t = parts.find((p) => p.startsWith('t='))?.slice(2);
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
  return parts.filter((p) => p.startsWith('v1=')).some((p) =>
    p.length === expected.length + 3 && timingSafeEqual(Buffer.from(p.slice(3)), Buffer.from(expected)));
}

• أجب بأي رمز 2xx خلال 10 ثوانٍ. أي رد آخر، سواء كان خطأ أو إعادة توجيه أو عدم رد، تُعاد محاولته بفترات انتظار متزايدة لمدة 24 ساعة؛ ثم يصبح التسليم رسالة غير مُسلَّمة، يُحتفظ بها 7 أيام ويمكن إعادة إرسالها من الإعدادات.
• تُسلَّم الأحداث مرة واحدة على الأقل ودون ترتيب محدد: تجاهل أي id عالجته من قبل.
• تحمل الطلبات أيضًا ZeeDo-Event-Id وZeeDo-Event-Type وZeeDo-Delivery-Id. نقاط الاستقبال تعمل عبر https على المنفذ 443 باسم مضيف عام.
• الأحداث: alert.fired وapproval.decided وapproval.requested وbilling.service_state_changed وbot.state_changed وbudget.threshold وconnection.created وconnection.error وconsent.recorded وmemory.note_created وpolicy.updated وrun.cancelled وrun.completed وrun.failed وrun.parked وtask.completed وtask.created.
• للتحقق من نقطة الاستقبال، اضغط «إرسال اختبار» في الإعدادات ← API وWebhooks: يُرسَل تسليم واحد من النوع webhook.test بحقل data فارغ، موقَّع مثل أي تسليم آخر، أيًّا كانت الأحداث التي اخترتها. مرة واحدة في الدقيقة على الأكثر.