مستندات API ادمتریکس

🔐 OAuth برای توسعه‌دهندگان

ادمتریکس یک ارائه‌دهندۀ OAuth 2.0 یکپارچه است. هر کاربر پنل می‌تواند تا ۱۰ برنامه ثبت کند و از طریق توکن Bearer، خواندن/نوشتنِ داده‌های خودش (صفحه‌ها، پروژه‌ها، رسانه، تیکت، آمار و…) را به سرویس‌ها و اتوماسیون‌های خود وصل کند.

۱) ثبت برنامه و دریافت اعتبارنامه

در پنل، بخش «برنامه‌ها و API» نام برنامه، آدرس‌های بازگشت (HTTPS، localhost برای توسعه آزاد)، اسکوپ‌های موردنیاز و در صورت نیاز لوگو را ثبت کنید. در پاسخ، App Id و App Secret داده می‌شود؛ رمز فقط یک‌بار نمایش داده می‌شود و قابل بازیابی نیست — در صورت گم‌شدن با دکمۀ «چرخش رمز» رمز تازه بسازید (با چرخش، تمام توکن‌های فعال برنامه بازمی‌گردند).

۲) گرفتن توکن

دو حالت اصلی داریم:

• دسترسی ماشین (client_credentials): برای اتوماسیونی که از طرف خودِ صاحب برنامه کار می‌کند — توکن بلافاصله با دسترسی‌های صاحب برنامه صادر می‌شود و تأیید انسانی لازم ندارد.
• دسترسی کاربری (authorization_code + PKCE): کاربر را به صفحۀ تأیید ادمتریکس بفرستید: /dashboard/oauth/consent?client_id=…&redirect_uri=…&scope=…&state=… پس از تأیید کاربر، یک بارِ code (۶۰ ثانیه، یک‌مصرفه) به آدرس بازگشت شما می‌رسد و آن را در ازای توکن دسترسی + توکن تازه‌سازی مبادله می‌کنید.

# دسترسی ماشین
curl -X POST https://admetrix.ir/api/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "app_XXXX",
    "client_secret": "YYYY",
    "scope": "overview:read pages:read"
  }'

# استفاده از توکن
curl https://admetrix.ir/api/owner/pages \
  -H 'Authorization: Bearer <access_token>'

توکن دسترسی ۱ ساعت معتبر است (JWT). توکن تازه‌سازی opaque است، هر بار چرخش می‌کند و در صورت استفادهٔ تکراری، کل خانوادۀ توکن‌ها برای محافظت از شما باطل می‌شود. وضعیت هر توکن را می‌توانید با POST /api/oauth/introspect ببینید.

۳) اسکوپ‌ها

هر توکن فقط اسکوپ‌های تأییدشده را دارد و هیچ‌گاه از توانایی خودِ کاربرِ تأییدکننده فراتر نمی‌رود. پرجامعۀ owner:full تمام دسترسی‌های پنل صاحب برنامه را می‌دهد. فهرست کامل و برچسب فارسی هر اسکوپ در صفحۀ ثبت برنامه و در مستندات کامل پایین همین صفحه موجود است.

۴) رویدادها (Webhook)

فیلد «آدرس وب‌هوک» هنگام ثبت برنامه ذخیره می‌شود؛ بستۀ تحویل رویدادها (رسانه، انتشار، تیکت و فاکتور) در حال پیاده‌سازی است و به‌زودی فعال می‌شود — تا آن زمان رویدادی ارسال نمی‌شود.