کانال‌یار
FA
فارسیEnglish
گرفتن کلید

API کانال‌یار

با همین API که افزونه‌ی وردپرس کانال‌یار با آن کار می‌کند، از هر سایت یا نرم‌افزاری (لاراول، جنگو، نود، اپ موبایل و …) در کانال‌های تلگرام، بله و روبیکا پست بگذارید، ویرایشش کنید یا پاکش کنید، و در اینستاگرام پست و استوری منتشر کنید. ربات، پراکسی و حد پیام‌رسان‌ها با ماست.

شروع و احراز هویت

  1. در پنل کانال‌یار ثبت‌نام کنید و پلن بگیرید.
  2. کلید اتصال را از پنل کپی کنید. این کلید مثل رمز است؛ فقط سمت سرور نگهش دارید، نه در کد مرورگر یا اپ.
  3. کانال‌تان را اضافه و تأیید کنید (از پنل، یا با API کانال‌ها).

آدرس پایه:

https://canalyarr.ir/bot-relay/v1

کلید را در هدر Authorization بفرستید:

Authorization: Bearer YOUR_KEY

روش قدیمی‌تر، گذاشتن کلید در آدرس (/v1/YOUR_KEY/publish)، هم کار می‌کند، ولی آدرس در لاگ‌ها می‌ماند؛ هدر امن‌تر است.

همه‌ی درخواست‌ها POST هستند و بدنه‌شان فرم است (multipart/form-data یا application/x-www-form-urlencoded). فیلدهایی که ساختار دارند، رشته‌ی JSON هستند.

پاسخ و خطا

پاسخ همیشه JSON است و کلید ok دارد. هر پاسخ ناموفق این سه کلید را دارد:

{
  "ok": false,
  "error": "متن خطا به فارسی، مناسب نمایش به کاربر",
  "description": "همان متن (برای سازگاری با شکل Bot API)",
  "error_code": 402
}
وضعیتیعنی
400ورودی نامعتبر: متن خالی، کانال انتخاب‌نشده، متن بلندتر از حد، …
402اشتراک منقضی (code: "expired") یا هنوز پلنی خریده نشده (code: "inactive").
403کلید نامعتبر یا غیرفعال.
404مسیر یا دستور ناشناخته.
429بیش از ۱۲۰ درخواست در دقیقه. هدر Retry-After می‌گوید چند ثانیه صبر کنید.
502ارسال به هیچ کانالی موفق نشد؛ دلیل هر کانال در results است.
503سرویس موقتاً در دسترس نیست؛ کمی بعد دوباره بفرستید.

وضعیت حساب

POST/api/account

پلن، انقضا، سهمیه و مصرف ماه (quota، used)، سقف و مصرف امروز (daily، used_today؛ سقف ۰ یعنی بی‌حد، روز به وقت تهران) و فهرست کانال‌ها. شناسه‌ی کانال‌ها و مقدار chat که در انتشار لازم دارید، از همین‌جا می‌آید.

curl -X POST https://canalyarr.ir/bot-relay/v1/api/account \
  -H "Authorization: Bearer YOUR_KEY"
{
  "ok": true,
  "plan": { "name": "حرفه‌ای", "max_channels": 5, "branding": false, … },
  "platforms": ["telegram", "bale", "rubika"],
  "expires": 1767225600,
  "active": true,
  "quota": 1000,
  "used": 42,
  "daily": 60,
  "used_today": 7,
  "channels": [
    { "id": 7, "platform": "telegram", "chat": "@myshop", "title": "فروشگاه من", "status": "verified", "verified": true }
  ],
  …
}

quota صفر یعنی نامحدود. expires زمان یونیکس است و صفر یعنی بی‌انقضا.

کانال‌ها

فقط در کانال‌های تأییدشده می‌شود پست گذاشت. تأیید یعنی ثابت کنید کانال مال شماست: ربات کانال‌یار را (نامش در bots پاسخ حساب است) مدیر کانال کنید، کانال را اضافه کنید تا ربات یک کد شش‌رقمی در آن بگذارد، و آن کد را برگردانید.

افزودن

POST/api/channels/add

فیلدتوضیح
platformtelegram، bale یا rubika
chatشناسه‌ی کانال، مثل @myshop
curl -X POST https://canalyarr.ir/bot-relay/v1/api/channels/add \
  -H "Authorization: Bearer YOUR_KEY" \
  -d platform=telegram -d chat=@myshop

پاسخ، کانال را با idش برمی‌گرداند.

تأیید

POST/api/channels/verify

فیلدها: id (شناسه‌ی کانال) و code (کد شش‌رقمی‌ای که در کانال گذاشته شد).

پیام آزمایشی و حذف

POST/api/channels/test

POST/api/channels/remove

هر دو فیلد id می‌گیرند.

انتشار پست

POST/publish

یک پست را هم‌زمان در یک یا چند کانال می‌گذارد. هر کانال موفق یک پست از سهمیه‌ی ماه و امروز کم می‌کند؛ مصرف تازه در usage پاسخ برمی‌گردد.

فیلدتوضیح
textمتن پست؛ حداکثر ۴۰۹۶ نویسه. *پررنگ*، `کد`، ~خط‌خورده~ و [متن](https://پیوند) (پیوند متنی) در تلگرام قالب می‌گیرند و در بله و روبیکا به متن ساده تبدیل می‌شوند (پیوند به‌شکل «متن: پیوند»).
channelsJSON: [{"platform":"telegram","chat":"@myshop"}, …]
image0 … image9اختیاری؛ فایل تصویر (JPG، PNG، WEBP یا GIF). چند تصویر در تلگرام و بله آلبوم می‌شوند.
image_modecaption (پیش‌فرض: متن زیر تصویر)، before (تصویرها، بعد متن)، after (متن، بعد تصویرها) یا none (بدون تصویر). اگر متن از حد کپشن (۱۰۲۴ نویسه) بلندتر باشد، خودکار before می‌شود.
fileاختیاری، به‌جای تصویرها: یک فایل تا ۳۰ مگابایت. MP3/M4A با پخش‌کننده‌ی موزیک و MP4 با پخش‌کننده‌ی ویدیو می‌رود، بقیه به‌صورت سند.
file_kindاختیاری، document: فایل را حتماً به‌صورت سند بفرست (مثلاً ویدیو بدون پخش‌کننده).
rubika_extraاختیاری، 1: روبیکا آلبوم ندارد؛ پیش‌فرض فقط تصویر اول می‌رود. با این فیلد بقیه هم، هرکدام در یک پست جدا، پشت سرش می‌روند.
ig_mode, ig_link, ig_headline, ig_highlight, ig_labelاختیاری، فقط برای کانال اینستاگرام: ig_mode یکی از post (پیش‌فرض)، story یا both؛ استوری ۹:۱۶ از همان تصویرها ساخته می‌شود. ig_link نشانی صفحه‌ی محصول (خالی: اولین پیوند متن)، ig_headline تیتر استوری (خالی: خط اول متن)، ig_highlight نام هایلایت (مثلاً دسته‌ی محصول) و ig_label برچسب بالای لینک. استیکر لینک و هایلایت فقط برای حسابی است که با نام کاربری و رمز وصل شده؛ شناسه‌ی استوری در story_id برمی‌گردد و با /edit (op: delete) حذف می‌شود. ig_story=1 قدیمی هم کار می‌کند و یعنی both.
curl -X POST https://canalyarr.ir/bot-relay/v1/publish \
  -H "Authorization: Bearer YOUR_KEY" \
  -F 'text=*کیف چرمی دست‌دوز*
قیمت: ۱٬۲۰۰٬۰۰۰ تومان
https://myshop.ir/p/123' \
  -F 'channels=[{"platform":"telegram","chat":"@myshop"},{"platform":"bale","chat":"@myshop"}]' \
  -F image0=@bag-1.jpg \
  -F image1=@bag-2.jpg
{
  "ok": true,
  "results": [
    { "platform": "telegram", "chat": "@myshop", "ok": true, "ids": ["812", "813"], "text_id": "812", "kind": "caption", "error": "", "note": "" },
    { "platform": "bale", "chat": "@myshop", "ok": false, "ids": [], "error": "این کانال برای این سایت تأیید نشده است.", "code": "" }
  ],
  "usage": { "used": 43, "quota": 1000, "today": 8, "daily": 60 }
}

اگر دست‌کم یک کانال موفق باشد، پاسخ 200 است؛ نتیجه‌ی هر کانال را جدا در results ببینید. ids، text_id و kind را نگه دارید؛ برای ویرایش و حذف همین پست لازمشان دارید. note اگر خالی نباشد، می‌گوید چه چیزی خودکار تنظیم شد (مثلاً جدا رفتن متن از تصویر).

ویرایش و حذف پست

POST/edit

سهمیه مصرف نمی‌کند. فیلد items یک آرایه‌ی JSON است، حداکثر ۳۰ مورد در هر درخواست:

[
  { "op": "edit",   "platform": "telegram", "chat": "@myshop", "id": "812", "kind": "caption", "text": "متن تازه" },
  { "op": "delete", "platform": "bale",     "chat": "@myshop", "ids": ["55", "56"] }
]
curl -X POST https://canalyarr.ir/bot-relay/v1/edit \
  -H "Authorization: Bearer YOUR_KEY" \
  --data-urlencode 'items=[{"op":"edit","platform":"telegram","chat":"@myshop","id":"812","kind":"caption","text":"*ناموجود*"}]'

پاسخ مثل انتشار است: ok و یک results برای هر مورد.

گزارش ارسال‌ها

POST/api/reports

خلاصه‌ی ۳۰ روز (summary)، شمار روزانه (daily) و سطرهای گزارش، ۵۰ تا در هر صفحه. همه‌ی فیلدها اختیاری‌اند: page، days (۱ تا ۹۰، پیش‌فرض ۱۴)، platform، result (ok یا failed)، from و to (زمان یونیکس).

{ "ok": true, "summary": { "total": 120, "failed": 3, … }, "daily": [ … ], "total": 120, "page": 1,
  "rows": [ { "time": 1767225600, "platform": "managed", "method": "publish", "status": 200, "ok": true, "error": "" } ] }

channels: پست‌های موفق هر کانال؛ d_* امروز (وقت تهران)، w_* هفت روز و m_* سی روز گذشته، *_new پست تازه و *_edit ویرایش پست قبلی.

خرید و فاکتور

POST/api/pay/start

ساخت سفارش و گرفتن آدرس درگاه. فیلدها: plan_id و months (از plans پاسخ حساب)، return_url (بعد از پرداخت کاربر با mkc_pay=ok|failed|canceled به آن برمی‌گردد؛ باید روی نشانی سایت شما باشد) و coupon اختیاری. مبلغ را سرور حساب می‌کند. پاسخ: url و amount.

POST/api/orders

همه‌ی سفارش‌ها و پرداخت‌های این سایت، تازه‌ترین اول: id، number، پلن، مبلغ، تخفیف، مالیات، paid و invoiced_at.

POST/api/invoice

POST/api/invoice/pay

POST/api/invoice/issue

حساب، کلید و معرفی

POST/api/profile

POST/api/profile/update

مشخصات صاحب حساب: first_name، last_name، email، business، site_url و همان فیلدهای مالیاتی. در update فقط فیلدهایی که می‌فرستید عوض می‌شوند. شماره‌ی موبایل شناسه‌ی ورود است و با API عوض نمی‌شود.

POST/api/key/rotate

کلید تازه می‌سازد و در key برمی‌گرداند. کلید فعلی همان لحظه از کار می‌افتد؛ پاسخ را فوراً ذخیره کنید. مصرف ماه با کلید تازه ادامه می‌یابد.

POST/api/sites

POST/api/sites/add

هر سایت کلید، کانال‌ها و اشتراک خودش را دارد. sites همه‌ی سایت‌های حساب را با پلن، انقضا و current (سایتِ همین کلید) برمی‌گرداند، ولی کلید بقیه‌ی سایت‌ها را نه. sites/add با name (اجباری، دست‌کم دو حرف) و site_url اختیاری سایت تازه می‌سازد و کلیدش را فقط همین یک بار در key برمی‌گرداند. سایت تازه تا خرید پلن فعال نیست. حداکثر ۱۰ سایت.

POST/api/referral

پیوند معرفی (link)، آمار (stats: دعوت‌شده، خریده، روزهای هدیه)، هدیه‌ی هر خرید (days) و درصد تخفیف تازه‌وارد (discount).

پشتیبانی (تیکت)

دستورفیلدها
/api/tickets— فهرست تیکت‌ها، به‌همراه دسته‌ها (categories) و اولویت‌ها (priorities)
/api/tickets/newsubject، category، body، priority (اختیاری)، file (اختیاری؛ تصویر JPG، PNG یا WebP)
/api/tickets/getid — تیکت با همه‌ی پیام‌ها؛ پاسخ‌های تازه خوانده‌شده می‌شوند
/api/tickets/replyid، body، file (اختیاری). پاسخ به تیکت بسته آن را دوباره باز می‌کند.
/api/tickets/closeid
/api/tickets/attachmentid پیام — خود تصویر برمی‌گردد، نه JSON

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

محدودیت‌ها

سؤال یا مشکل؟ از بخش تیکت‌های پنل بپرسید.

زبان را انتخاب کنیدChoose your language

فارسیEnglish