ZeeDo API

سیٹنگز → API اور ویب ہکس میں ایک کنجی بنائیں (پہلے کوئی مالک اپنی شناخت کی تصدیق کرتا ہے)، پھر اسے bearer token کے طور پر استعمال کر کے API کو کال کریں۔ بنیادی 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 کی problem دستاویزات ہوتی ہیں: type، title، status، detail اور، مسترد شدہ فیلڈ کے لیے، JSON pointer کے ساتھ errors[]۔
• فہرستیں limit (زیادہ سے زیادہ 200) اور next_cursor کے ساتھ صفحوں میں آتی ہیں۔
• ہر POST کے ساتھ Idempotency-Key ہیڈر بھیجیں: 24 گھنٹوں کے اندر دہرائی گئی کال کا جواب وہی ہوتا ہے جو پہلی کا تھا۔
• فی کنجی ایک منٹ میں 600 درخواستیں اور 10 کھلی اسٹریمز، RateLimit-* ہیڈرز کے ساتھ۔

ایک ادارہ ایک اینڈ پوائنٹ رجسٹر کرتا ہے (سیٹنگز → API اور ویب ہکس، یا POST /webhooks) اور اپنے ایونٹس منتخب کرتا ہے۔ ہر ایونٹ JSON کا ایک POST ہوتا ہے جس میں ids، قسم اور ٹائم اسٹیمپس ہوتے ہیں — کبھی کسی انسان کا نام، ای میل یا IP پتہ نہیں، جو آپ کنجی کے ساتھ API سے واپس پڑھتے ہیں۔

{
  "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=<دستخط>، جہاں دستخط <t>.<خام باڈی> کا hex HMAC-SHA256 ہے جو آپ کے اینڈ پوائنٹ کے راز سے بنتا ہے۔ راز بدلنے کے بعد پچھلا راز 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)));
}

• 10 سیکنڈ کے اندر کسی بھی 2xx سے جواب دیں۔ اس کے علاوہ کچھ بھی — غلطی، ری ڈائریکٹ، کوئی جواب نہیں — 24 گھنٹے تک بڑھتے وقفوں سے دوبارہ بھیجا جاتا ہے؛ پھر ترسیل dead letter بن جاتی ہے، 7 دن رکھی جاتی ہے اور سیٹنگز سے دوبارہ بھیجی جا سکتی ہے۔
• ترسیل کم از کم ایک بار اور کسی خاص ترتیب کے بغیر ہوتی ہے: جو id آپ پہلے سنبھال چکے ہوں اسے چھوڑ دیں۔
• درخواستوں میں ZeeDo-Event-Id، ZeeDo-Event-Type اور ZeeDo-Delivery-Id بھی ہوتے ہیں۔ اینڈ پوائنٹس کسی عوامی ہوسٹ نام پر پورٹ 443 پر https ہوتے ہیں۔
• ایونٹس: 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 اور ویب ہکس میں “آزمائشی بھیجیں” دبائیں: webhook.test قسم کی ایک ترسیل، خالی data کے ساتھ، باقی سب کی طرح دستخط شدہ، آپ نے جو بھی ایونٹس چنے ہوں، بھیجی جاتی ہے۔ ایک منٹ میں زیادہ سے زیادہ ایک بار۔