مرجع endpointهای Public API

همه endpointهای تأییدشده Public API آلفانا با method، مسیر، پارامترها، پاسخ و کدهای خطا؛ همان داده‌ای که ابزار MCP برمی‌گرداند.

آخرین بازبینی: ۱۷ آبان ۱۴۰۵

در این صفحه

این صفحه فهرست کامل endpointهای Public Analytics API آلفاناست که از کد ماژول Public API در Backend استخراج و تأیید شده‌اند. endpointهای داخلی Dashboard، مدیریت و ingestion بخشی از این قرارداد نیستند.

همه مسیرها نسبت به آدرس پایه زیر هستند و فقط از Backend شما و با Account API Key فراخوانی می‌شوند:

text

https://api.alphana.ir

احراز هویت درخواست‌ها

هر درخواست باید Header زیر را داشته باشد. ساخت و نگهداری کلید در احراز هویت Public API توضیح داده شده است.

text

Authorization: Bearer YOUR_API_KEY

Endpointهای قابل استفاده

Method و Path	کاربرد	پارامترها	پاسخ	خطاها
POST`/api/v1/apps`	ساخت اپلیکیشناپ رهگیری‌شونده‌ای با مالکیت حساب کلید API می‌سازد.	`body: CreateAppDto شامل name و domain`	201 با مشخصات app و secretKey تازه	400, 401, 409, 429
GET`/api/v1/apps`	فهرست اپلیکیشن‌هاappهای owned و shared قابل‌دسترسی را بدون secretKey فهرست می‌کند.	—	200 با آرایه PublicAppSummaryDto	401, 429
GET`/api/v1/sessions/data-bounds`	کران زمانی دادهقدیمی‌ترین و جدیدترین session timestamp یا null را می‌دهد.	`appId: UUID اجباری`	200 با oldest و newest	400, 401, 403, 429
GET`/api/v1/sessions/overview/extended`	نمای کلی توسعه‌یافتهمعیارهای session، page، interaction، technology، error و traffic را برمی‌گرداند.	`appId: UUID اجباری` `from?: ISO 8601 شامل` `to?: ISO 8601 شامل`	200 با PublicExtendedOverviewResponseDto	400, 401, 403, 429
GET`/api/v1/sessions/overview/kpis`	KPIهای نشستcurrent، previous و change برای معیارهای کلیدی را می‌دهد.	`appId: UUID اجباری` `from?: ISO 8601 شامل` `to?: ISO 8601 شامل`	200 با PublicOverviewKpiResponseDto	400, 401, 403, 429
GET`/api/v1/sessions/pageviews`	بازدید صفحهviews و sessionهای یکتای مشاهده‌کننده را به تفکیک path می‌دهد.	`appId: UUID اجباری` `from?: ISO 8601 شامل` `to?: ISO 8601 شامل`	200 با آرایه PublicPageViewDto	400, 401, 403, 429
GET`/api/v1/sessions/timespent`	زمان حضورزمان کل و میانگین به تفکیک path و برحسب میلی‌ثانیه را می‌دهد.	`appId: UUID اجباری` `from?: ISO 8601 شامل` `to?: ISO 8601 شامل`	200 با آرایه PublicTimeSpentDto	400, 401, 403, 429
GET`/api/v1/sessions/user-growth`	رشد روزانه مخاطبsession، visitor، pageview و click روزانه UTC را می‌دهد.	`appId: UUID اجباری` `from?: ISO 8601 شامل` `to?: ISO 8601 شامل`	200 با آرایه PublicUserGrowthPointDto	400, 401, 403, 429
GET`/api/v1/sessions/traffic-heatmap`	نقشه ترافیکماتریس ساعتی هفت روز اخیر در Asia/Tehran را می‌دهد.	`appId: UUID اجباری`	200 با PublicTrafficHeatmapResponseDto	400, 401, 403, 429
GET`/api/v1/sessions/traffic-audience-activity`	فعالیت مخاطبمیانگین روز و ساعت در پنجره غلتان ۲۸ روز تهران را می‌دهد.	`appId: UUID اجباری`	200 با PublicAudienceActivityResponseDto	400, 401, 403, 429
GET`/api/v1/sessions/locations/all`	موقعیت نشست‌هاlocationهای دارای مختصات را تجمیع و بر اساس count مرتب می‌کند.	`appId: UUID اجباری` `from?: ISO 8601 شامل` `to?: ISO 8601 شامل`	200 با آرایه PublicLocationDto	400, 401, 403, 429
GET`/api/v1/growth/utm`	عملکرد UTMحداکثر ۱۰۰ ترکیب UTM دارای source را با sessions و visitors می‌دهد.	`appId: UUID اجباری` `from?: ISO 8601 شامل` `to?: ISO 8601 شامل`	200 با آرایه PublicUtmCampaignDto	400, 401, 403, 429

پارامترهای مشترک

appId: شناسه UUID یک App قابل‌دسترسی برای همان کلید؛ آن را از پاسخ GET /api/v1/apps بردارید.
from و to: کران‌های اختیاری بازه با قالب ISO 8601 که هر دو شامل هستند. فقط endpointهایی که در جدول این دو پارامتر را دارند آن‌ها را می‌پذیرند.
endpointهایی که فقط appId می‌گیرند، Window زمانی ثابت خودشان را دارند؛ مثلاً نقشه ترافیک هفت روز اخیر را برمی‌گرداند.

کدهای خطا

Status	معنا
`400`	پارامتر نامعتبر؛ مثلاً `appId` غیر UUID یا تاریخ خارج از ISO 8601
`401`	Header `Authorization` وجود ندارد یا کلید نامعتبر است
`403`	کلید معتبر است اما به App درخواستی دسترسی ندارد
`409`	تعارض هنگام ساخت App
`429`	عبور از Rate Limit؛ پیش از تلاش دوباره `Retry-After` را رعایت کنید

جزئیات Rate Limit، Headerهای محدودیت و الگوی Retry در محدودیت نرخ و خطاهای API آمده است.

همین فهرست در MCP

ابزار get_api_endpoint در سرویس MCP آلفانا همین فهرست را برمی‌گرداند؛ بنابراین دستیار هوش مصنوعی شما همان method، مسیر و پارامترهایی را می‌بیند که در این صفحه منتشر شده‌اند.