{ مستندات }

API بیا دایرکت برای برنامه‌نویس‌ها

با API از کد، سایت یا ابزار خودتون با بیا دایرکت کار کنید: پست بسازید و زمان‌بندیش کنید، اتوماسیون‌ها و آمارشون رو ببینید و اطلاعات پیجتون رو بخونید. API و MCP توی دوره‌ی آزمایشی و همه‌ی پلن‌های پولی هست.

پرامپت آماده برای دستیار کدنویسی

کد رو با ChatGPT، Claude یا Cursor می‌نویسید؟ اینو کپی کنید و اول گفتگو بفرستید که دستیار آدرس‌ها، کلید و ترتیب درست درخواست‌ها رو بدونه و فیلد از خودش نسازه.

۱. یه کلید API بسازید

توی داشبورد بیا دایرکت برید به تنظیمات ← کلیدهای API، «ساخت کلید API» رو بزنید، یه اسم بذارید و دسترسی‌هایی که لازم دارید رو انتخاب کنید. کلید با sk_ شروع می‌شه و فقط همون یه بار نشونش می‌دیم.

کلید مثل رمز عبوره: توی کد سمت مرورگر، اپ موبایل یا مخزن عمومی نذاریدش. اگه لو رفت، از همون صفحه باطلش کنید و یه کلید تازه بسازید.

۲. کلید رو توی هدر بفرستید

آدرس پایه‌ی همه‌ی درخواست‌ها:

Base URL

https://app.biadirect.ir/api/v1

کلید رو توی یکی از این دو تا هدر بفرستید:

Headers

X-API-Key: sk_...
Authorization: Bearer sk_...

درخواست‌ها و جواب‌ها JSON هستن. بیشتر جواب‌های موفق، داده رو توی فیلد data برمی‌گردونن.

دسترسی‌ها

هر کلید فقط کارایی رو می‌تونه بکنه که دسترسیش رو دادید. اسم هر دسترسی توی صفحه‌ی کلیدها همونیه که توی ستون اول می‌بینید.

توی صفحه‌ی کلیدها	کد	به چه کاری میاد
استفاده از دستیار هوش مصنوعی (سرور MCP و CLI)	`agent:execute`	برای وصل کردن هوش مصنوعی (سرور MCP) لازمه. برای REST لازم نیست.
دیدن حساب‌ها	`accounts:read`	دیدن اکانت‌های وصل و پست‌های منتشرشده.
مدیریت حساب‌ها	`accounts:write`	مدیریت اکانت‌های وصل.
دیدن پست‌ها	`posts:read`	دیدن پست‌ها، پیش‌نویس‌ها و تقویم.
نوشتن پست	`posts:write`	ساختن، زمان‌بندی، ویرایش و انتشار پست.
دیدن اتوماسیون‌ها	`flows:read`	دیدن اتوماسیون‌ها، آمار و اطلاعات جمع‌شده.
ساختن و ویرایش اتوماسیون‌ها	`flows:write`	ساختن، ویرایش، روشن و خاموش کردن اتوماسیون.
دیدن آمار	`analytics:read`	دیدن آمار پست‌ها و پیج.
دیدن قالب‌ها	`templates:read`	دیدن قالب‌ها.
نوشتن قالب	`templates:write`	ساختن قالب.
بارگذاری عکس و ویدیو	`uploads:write`	آپلود عکس و ویدیو برای پست.
دیدن اعلان‌ها	`notifications:read`	دیدن اعلان‌ها.
مدیریت اعلان‌ها (علامت خوانده‌شده)	`notifications:write`	خونده‌شده زدن اعلان‌ها.
ساختن پیش‌نویس پیام همگانی	`broadcasts:write`	ساختن پیش‌نویس پیام همگانی (پلن‌های پولی).
ساختن پیش‌نویس پیام‌های زنجیره‌ای	`sequences:write`	ساختن پیش‌نویس پیام‌های زنجیره‌ای (پلن‌های پولی).
مدیریت ابزارهای رشد (ویجت، صفحهٔ فرود، لینک معرفی)	`growth_tools:write`	ساختن لینک با شمارش کلیک و ابزارهای رشد (پلن‌های پولی).

نمونه‌ها

اکانت‌های وصل رو ببینید. شناسه‌ی هر اکانت توی فیلد id هست و برای ساختن پست لازمش دارید:

GET /connected-accounts

curl https://app.biadirect.ir/api/v1/connected-accounts \
  -H "X-API-Key: sk_..."

ده تا پست زمان‌بندی‌شده:

GET /posts

curl "https://app.biadirect.ir/api/v1/posts?status=scheduled&limit=10" \
  -H "X-API-Key: sk_..."

ساختن و زمان‌بندی پست دو قدمه. اول پست رو به‌شکل پیش‌نویس بسازید. جای ACCOUNT_ID شناسه‌ی اکانت رو بذارید. آدرس عکس باید عمومی باشه و متن پست حداکثر ۲۲۰۰ حرفه. شناسه‌ی پست ساخته‌شده توی فیلد data._id جواب هست.

POST /posts

curl -X POST https://app.biadirect.ir/api/v1/posts \
  -H "X-API-Key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "text": "Weekend sale starts now!",
      "media": [{ "type": "image", "url": "https://example.com/photo.jpg" }]
    },
    "platforms": [{ "platform": "instagram", "account_id": "ACCOUNT_ID" }],
    "schedule_type": "scheduled",
    "timezone": "Asia/Tehran"
  }'

بعد پیش‌نویس رو زمان‌بندی کنید. جای POST_ID شناسه‌ی پست رو بذارید. زمان رو با فرمت ISO و به وقت UTC بنویسید و باید توی آینده باشه؛ مثال زیر یعنی ساعت ۱۹ به وقت تهران. برای اینکه یه پیش‌نویس همین الان منتشر بشه، به‌جای این درخواست POST /posts/POST_ID/publish رو بفرستید.

POST /posts/{id}/schedule

curl -X POST https://app.biadirect.ir/api/v1/posts/POST_ID/schedule \
  -H "X-API-Key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-11-12T15:30:00Z", "timezone": "Asia/Tehran" }'

آمار یه اتوماسیون (این بار با هدر Authorization). شناسه‌ی اتوماسیون رو از GET /flows بگیرید:

GET /flows/{id}/stats

curl https://app.biadirect.ir/api/v1/flows/FLOW_ID/stats \
  -H "Authorization: Bearer sk_..."

فهرست کامل آدرس‌ها، فیلدها و جواب‌ها توی مرجع API هست (به انگلیسی): https://app.biadirect.ir/api/v1/docs

خطاها

درخواستی که موفق نشه، کد وضعیت HTTP و یه پیام توی فیلد error برمی‌گردونه:

Response

{ "error": "Insufficient permissions" }

400: درخواست درست نیست؛ مثلاً یه فیلد لازم جا افتاده یا شکلش غلطه. متن خطا می‌گه کدوم فیلد.
401: کلید فرستاده نشده، غلطه یا منقضی شده.
403: کلید درسته ولی دسترسی این کار رو نداره؛ یه کلید با دسترسی درست بسازید. اگه دوره‌ی آزمایشی‌تون تموم شده و پلن پولی ندارید هم 403 با کد upgrade_required می‌گیرید؛ برای ادامه پلن‌تون رو ارتقا بدید.
404: چیزی که خواستید پیدا نشد، یا مال حساب شما نیست.
429: درخواست‌ها از سقف رد شده. یه کم صبر کنید و دوباره بفرستید.
500: مشکل از سمت ماست. یه بار دیگه امتحان کنید و اگه باز تکرار شد، به پشتیبانی بگید.

محدودیت تعداد درخواست

API: هر حساب تا ۱۰۰۰ درخواست در دقیقه، با همه‌ی کلیدها روی هم. کلید بیشتر ساختن سقف رو بالا نمی‌بره.
ابزارهای سرور MCP: توی هر دقیقه ۱۲۰ بار خوندن، ۳۰ بار تغییر و ۵ تا کار سنگین (مثل ساختن اتوماسیون با هوش مصنوعی)، و روی هم ۱۰۰۰ بار اجرای ابزار در روز.

اگه جواب 429 گرفتید، چند ثانیه صبر کنید و دوباره بفرستید. توی حلقه‌ها بین درخواست‌ها فاصله بذارید و برای کار گروهی از آدرس‌های گروهی مثل POST /posts/bulk استفاده کنید.

محدودیت‌های پلن (مثل تعداد اکانت یا اتوماسیون) توی API هم همونیه که توی داشبورده؛ با API نمی‌شه دورشون زد.