مستندات توسعه‌دهندگان ادزیتو

API ادزیتو

تبلیغات، آمار و کیف پول فضای کاری را از سرویس خود مدیریت کنید. پاسخ‌ها JSON و همهٔ مبلغ‌ها به تومان هستند.

احراز هویت

کلید را در داشبورد بسازید، IP سرور را در فهرست مجاز قرار دهید و آن را با Bearer بفرستید.

Authorization: Bearer adsito_live_…

آدرس پایه

https://adsito.online/api/v1

خطاها

Problem Details با کد پایدار و traceId

سرویس تبلیغات

ساخت، مشاهده و مدیریت تبلیغات فضای کاری.

GETفهرست تبلیغات/ads

فهرست صفحه‌بندی‌شدهٔ تبلیغات فضای کاری را برمی‌گرداند.

پارامترها

pageاختیاریinteger

شماره صفحه؛ پیش‌فرض ۱

pageSizeاختیاریinteger

تعداد نتیجه در هر صفحه

statusاختیاریAdStatus

فیلتر اختیاری وضعیت

درخواست cURL

curl 'https://adsito.online/api/v1/ads?page=1&pageSize=20' \
  -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "items": [{
    "id": "019a...",
    "number": "AD-1405-0012",
    "title": "کمپین پاییز",
    "status": "Active",
    "views": 18420,
    "clicks": 613,
    "spentToman": 920000
  }],
  "page": 1,
  "pageSize": 20,
  "total": 1
}

POSTساخت کامل تبلیغ/ads

محتوا، هدف‌گیری، تنظیمات، بودجه و تصویر base64 را در یک درخواست داخل پیش‌نویس می‌سازد. ثبت نهایی جداست چون بودجه را جابه‌جا می‌کند.

پارامترها

targetTypeالزامیAdTargetType

نوع هدف‌گیری: Channel، Bot، Search یا Users

titleاختیاریstring

نام داخلی تبلیغ

contentاختیاریAdContent

متن و لینک مقصد

targetingاختیاریAdTargeting

مخاطبان و فیلترها

mediaاختیاریInlineMedia

نام، نوع و base64 تصویر ۱۶:۹

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/ads' \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{"targetType":"Channel","title":"کمپین پاییز","content":{"text":"همین امروز عضو شوید","promoteUrl":"@adsito"},"targeting":{"channels":[{"id":"-1001","username":"@news","title":"اخبار","subscribers":12000}]},"options":{"viewsPerUser":2},"cpmToman":100000,"budgetToman":2000000,"media":{"fileName":"ad.jpg","contentType":"image/jpeg","base64":"<base64>"}}'

پاسخ نمونه

{
  "id": "019a...",
  "number": "AD-1405-0012",
  "title": "کمپین پاییز",
  "targetType": "Channel",
  "status": "Draft"
}

GETجزئیات تبلیغ/ads/{id}

جزئیات، بودجه‌ها، آمار و بازبینی‌های یک تبلیغ را می‌خواند.

پارامترها

idالزامیuuid

شناسه تبلیغ در مسیر

درخواست cURL

curl 'https://adsito.online/api/v1/ads/<ad_id>' \
  -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "id": "019a...",
  "status": "Active",
  "budgetToman": 2500000,
  "remainingToman": 1580000,
  "views": 18420,
  "clicks": 613
}

PUTویرایش کامل تبلیغ/ads/{id}

فیلدهای تبلیغ و تصویر base64 را بدون سرویس فایل جداگانه ویرایش می‌کند.

درخواست cURL

curl -X PUT 'https://adsito.online/api/v1/ads/<ad_id>' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

DELETEحذف پیش‌نویس/ads/{id}

پیش‌نویس حذف‌پذیر را پاک می‌کند.

درخواست cURL

curl -X DELETE 'https://adsito.online/api/v1/ads/<ad_id>' -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

204 No Content

GETتصویر تبلیغ/ads/{id}/media

تصویر متصل به تبلیغ را مستقیماً برمی‌گرداند.

درخواست cURL

curl -X GET 'https://adsito.online/api/v1/ads/<ad_id>/media' -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "status": "ok"
}

GETاطلاعات مقصد/ads/{id}/promoted-peer

اطلاعات مقصد تأییدشدهٔ تلگرام را می‌خواند.

درخواست cURL

curl -X GET 'https://adsito.online/api/v1/ads/<ad_id>/promoted-peer' -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "status": "ok"
}

POSTکپی تبلیغ/ads/{id}/clone

یک پیش‌نویس تازه از تبلیغ می‌سازد.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/ads/<ad_id>/clone' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

POSTارسال برای بررسی/ads/{id}/submit

با quoteId و Idempotency-Key تبلیغ را ثبت و بودجه را رزرو می‌کند.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/ads/<ad_id>/submit' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

POSTتوقف تبلیغ/ads/{id}/pause

تحویل تبلیغ فعال را متوقف می‌کند.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/ads/<ad_id>/pause' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

POSTادامه تبلیغ/ads/{id}/resume

تحویل تبلیغ متوقف‌شده را ادامه می‌دهد.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/ads/<ad_id>/resume' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

POSTپایان تبلیغ/ads/{id}/end

تبلیغ را پایان می‌دهد.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/ads/<ad_id>/end' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

POSTبایگانی/ads/{id}/archive

تبلیغ را از فهرست فعال بایگانی می‌کند.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/ads/<ad_id>/archive' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

POSTبازیابی/ads/{id}/restore

تبلیغ بایگانی‌شده را برمی‌گرداند.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/ads/<ad_id>/restore' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

POSTبازکردن تبلیغ ردشده/ads/{id}/reopen

تبلیغ ردشده را برای اصلاح به پیش‌نویس تبدیل می‌کند.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/ads/<ad_id>/reopen' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

POSTافزایش بودجه/ads/{id}/add-budget

بودجه را با quoteId و Idempotency-Key افزایش می‌دهد.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/ads/<ad_id>/add-budget' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

POSTبازگرداندن بودجه/ads/{id}/withdraw-unspent

بودجهٔ مصرف‌نشده را به کیف پول برمی‌گرداند.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/ads/<ad_id>/withdraw-unspent' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

POSTتغییر CPM/ads/{id}/cpm

درخواست تغییر نرخ هر هزار نمایش را ثبت می‌کند.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/ads/<ad_id>/cpm' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

POSTنسخه اصلاحی/ads/{id}/revisions

محتوا، تصویر، CPM یا سقف روزانهٔ تبلیغ منتشرشده را اصلاح می‌کند.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/ads/<ad_id>/revisions' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

POSTاعتبارسنجی لینک/ads/validate-promote-link

لینک مقصد تلگرام را پیش از ساخت تبلیغ بررسی می‌کند.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/ads/validate-promote-link' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

هدف‌گیری و قیمت

اعتبارسنجی مقصد، انتخاب مخاطب و محاسبه نرخ پیش از ثبت.

GETشناسایی مقصد/targeting/resolve

کانال، ربات یا مقصد تلگرام را شناسایی می‌کند.

درخواست cURL

curl -X GET 'https://adsito.online/api/v1/targeting/resolve' -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "status": "ok"
}

GETپیش‌نمایش مقصد/targeting/preview

پیش‌نمایش عمومی مقصد تبلیغ را می‌خواند.

درخواست cURL

curl -X GET 'https://adsito.online/api/v1/targeting/preview' -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "status": "ok"
}

GETگزینه‌های هدف‌گیری/targeting/options

زبان‌ها، کشورها، موضوع‌ها و گزینه‌های قابل استفاده را برمی‌گرداند.

درخواست cURL

curl -X GET 'https://adsito.online/api/v1/targeting/options' -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "status": "ok"
}

POSTانتخاب مخاطبان/targeting/select

فهرست مخاطبان انتخابی را اعتبارسنجی می‌کند.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/targeting/select' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

POSTانتخاب تصادفی/targeting/random

بر اساس دسته‌بندی، مخاطبان پیشنهادی برمی‌گرداند.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/targeting/random' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

GETتعرفه فعلی/pricing/current

تعرفه و تنظیمات قیمت‌گذاری فضای کاری را می‌خواند.

درخواست cURL

curl -X GET 'https://adsito.online/api/v1/pricing/current' -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "status": "ok"
}

GETحداقل نرخ‌ها/rates/minimums

حداقل CPM و بودجه را برای نوع تبلیغ برمی‌گرداند.

درخواست cURL

curl -X GET 'https://adsito.online/api/v1/rates/minimums' -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "status": "ok"
}

POSTصدور پیش‌فاکتور/rates/quote

نرخ کوتاه‌مدت لازم برای ثبت یا افزایش بودجه را صادر می‌کند.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/rates/quote' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

سرویس آمار

آمار تحویل و عملکرد فضای کاری و تبلیغات.

GETنمای کلی آمار/stats/overview

مجموع آمار و سری روزانه را در بازهٔ تقویم تهران برمی‌گرداند.

پارامترها

fromاختیاریdate

ابتدای بازه با قالب yyyy-MM-dd

toاختیاریdate

انتهای بازه با قالب yyyy-MM-dd

درخواست cURL

curl 'https://adsito.online/api/v1/stats/overview?from=2026-10-01&to=2026-10-11' \
  -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "from": "2026-10-01",
  "to": "2026-10-11",
  "total": { "views": 18420, "clicks": 613, "spentToman": 920000 },
  "activeAds": 2,
  "daily": []
}

GETبرترین تبلیغات/stats/top-ads

تبلیغ‌های با بیشترین هزینه در بازه را رتبه‌بندی می‌کند.

پارامترها

limitاختیاریinteger

بین ۱ تا ۲۰؛ پیش‌فرض ۵

درخواست cURL

curl 'https://adsito.online/api/v1/stats/top-ads?limit=5' \
  -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "from": "2026-09-12",
  "to": "2026-10-11",
  "items": []
}

GETآمار یک تبلیغ/ads/{id}/stats

آمار تجمیعی و روزانهٔ یک تبلیغ را می‌خواند.

درخواست cURL

curl -X GET 'https://adsito.online/api/v1/ads/<ad_id>/stats' -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "status": "ok"
}

POSTبه‌روزرسانی آمار/ads/{id}/stats/refresh

همگام‌سازی آمار تبلیغ را درخواست می‌کند.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/ads/<ad_id>/stats/refresh' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

خروجی‌ها

فایل‌های گزارش برای حسابداری و تحلیل عملکرد.

GETخروجی تبلیغات/exports/ads.xlsx

فهرست تبلیغات را به‌صورت Excel دریافت می‌کند.

درخواست cURL

curl -X GET 'https://adsito.online/api/v1/exports/ads.xlsx' -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "status": "ok"
}

GETآمار روزانه Excel/exports/ads/{id}/daily.xlsx

آمار روزانهٔ تبلیغ را در بازهٔ انتخابی صادر می‌کند.

درخواست cURL

curl -X GET 'https://adsito.online/api/v1/exports/ads/<ad_id>/daily.xlsx' -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "status": "ok"
}

GETگزارش PDF/exports/ads/{id}/report.pdf

گزارش تصویری و مالی تبلیغ را صادر می‌کند.

درخواست cURL

curl -X GET 'https://adsito.online/api/v1/exports/ads/<ad_id>/report.pdf' -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "status": "ok"
}

POSTلینک دانلود/exports/links

برای خروجی انتخاب‌شده لینک دانلود کوتاه‌عمر می‌سازد.

درخواست cURL

curl -X POST 'https://adsito.online/api/v1/exports/links' -H 'Authorization: Bearer <api_key>' -H 'Content-Type: application/json'

پاسخ نمونه

{
  "status": "ok"
}

سرویس کیف پول

موجودی و گردش مالی فضای کاری به تومان.

GETموجودی کیف پول/wallet

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

درخواست cURL

curl 'https://adsito.online/api/v1/wallet' \
  -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "balance": 6400000,
  "held": 1580000,
  "available": 4820000
}

GETگردش حساب/wallet/ledger

رویدادهای مالی را به‌ترتیب جدیدترین مورد برمی‌گرداند.

پارامترها

pageاختیاریinteger

شماره صفحه

typeاختیاریLedgerEntryType

فیلتر اختیاری نوع رویداد

درخواست cURL

curl 'https://adsito.online/api/v1/wallet/ledger?page=1' \
  -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "items": [],
  "page": 1,
  "pageSize": 20,
  "total": 0
}

GETفهرست افزایش موجودی/deposits

سوابق افزایش موجودی را فقط برای مشاهده برمی‌گرداند.

درخواست cURL

curl -X GET 'https://adsito.online/api/v1/deposits' -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "status": "ok"
}

GETجزئیات افزایش موجودی/deposits/{id}

جزئیات یک افزایش موجودی را فقط برای مشاهده برمی‌گرداند.

درخواست cURL

curl -X GET 'https://adsito.online/api/v1/deposits/<ad_id>' -H 'Authorization: Bearer <api_key>'

پاسخ نمونه

{
  "status": "ok"
}