رفتن به محتوای اصلی
آلفاناDocs

API اپلیکیشن‌ها

دریافت فهرست Appهای قابل‌دسترسی و ساخت App جدید از طریق Public API آلفانا.

API اپلیکیشن‌ها برای دریافت Appهایی که حساب شما به آن‌ها دسترسی دارد و ساخت App جدید از طریق Public API استفاده می‌شود.

تمام درخواست‌های این بخش باید با Account API Key معتبر ارسال شوند. این کلید به حساب آلفانا متصل است و مشخص می‌کند درخواست به چه Appها و منابعی دسترسی دارد.

فهرست Appها#

برای دریافت Appهایی که حساب فعلی به آن‌ها دسترسی دارد، درخواست زیر را ارسال کنید:

text
GET /api/v1/apps

این endpoint هم Appهایی را برمی‌گرداند که مستقیماً متعلق به حساب متصل به API Key هستند و هم Appهایی که با همان حساب Share شده‌اند.

نمونه درخواست:

curl
curl https://api.alphana.ir/api/v1/apps \
  -H "Authorization: Bearer $ALPHANA_API_KEY"

مقدار ALPHANA_API_KEY باید Account API Key معتبر شما باشد.

برای مثال، بهتر است این مقدار از Environment Variable سمت Server خوانده شود:

env
ALPHANA_API_KEY=alphana_api_...

و مستقیماً داخل Source Code قرار نگیرد.

داده‌های پاسخ#

پاسخ GET /api/v1/apps اطلاعات Appهای قابل‌دسترسی را برمی‌گرداند تا بتوانید App موردنظر را برای درخواست‌های بعدی Public API انتخاب کنید.

پاسخ این endpoint عمداً شامل secretKey هر App نیست.

این جداسازی مهم است؛ چون دریافت فهرست Appها نباید باعث افشای credential مورد استفاده SDK برای ingestion شود.

در نتیجه، می‌توانید از این endpoint برای مواردی مثل این استفاده کنید:

  • نمایش Appهای قابل‌دسترسی در یک ابزار داخلی
  • انتخاب appId برای گزارش‌های بعدی
  • ساخت integrationهای Server-side
  • بررسی Appهای owned و shared
  • پیدا کردن App مناسب برای درخواست‌های بعدی Public API

اما نباید انتظار داشته باشید App Secret موجود را از این endpoint دریافت کنید.

Appهای متعلق به حساب و Appهای Share‌شده#

فهرست برگردانده‌شده فقط به Appهایی که خود حساب ساخته محدود نیست.

اگر App دیگری با حساب شما Share شده باشد و سطح دسترسی لازم وجود داشته باشد، آن App نیز می‌تواند در نتیجه GET /api/v1/apps دیده شود.

بنابراین هنگام استفاده از نتیجه این endpoint، مالکیت App و صرفاً قابل‌دسترسی بودن آن را یک مفهوم در نظر نگیرید.

اگر integration شما باید فقط روی Appهای مشخصی کار کند، appId موردنظر را صریح انتخاب و نگهداری کنید.

ساخت App#

برای ساخت یک App جدید از endpoint زیر استفاده کنید:

text
POST /api/v1/apps

App جدید تحت مالکیت حسابی ساخته می‌شود که Account API Key درخواست به آن تعلق دارد.

Body درخواست مطابق قرارداد فعلی CreateAppDto در Backend است.

نمونه Body:

json
{
  "name": "Storefront",
  "domain": "https://example.com"
}

در این مثال:

  • name نام App در آلفانا را مشخص می‌کند.
  • domain دامنه‌ای است که App برای آن ساخته می‌شود.

دامنه را به شکلی ارسال کنید که با محیط واقعی‌ای که SDK روی آن اجرا خواهد شد هماهنگ باشد.

نمونه درخواست ساخت App#

یک درخواست کامل می‌تواند به این شکل باشد:

curl
curl -X POST https://api.alphana.ir/api/v1/apps \
  -H "Authorization: Bearer $ALPHANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Storefront",
    "domain": "https://example.com"
  }'

در صورت موفقیت، endpoint با status زیر پاسخ می‌دهد:

text
201 Created

پاسخ ساخت App شامل اطلاعات App جدید و Secret مربوط به همان App است.

Secret در پاسخ ساخت#

برخلاف endpoint فهرست Appها، پاسخ ساخت App شامل Secret App تازه است.

این مقدار credential مربوط به همان App است و باید بلافاصله بعد از دریافت در محل امن ذخیره شود.

بهتر است جریان ساخت App را طوری طراحی کنید که Secret مستقیماً وارد Secret Manager، Environment Configuration یا محل امن مشابه شود و نیازی به Copy کردن آن در چند محیط مختلف نباشد.

برای مثال، اگر یک سیستم داخلی Appها را به‌صورت خودکار ایجاد می‌کند، Secret را بعد از پاسخ 201 در storage امن همان سیستم نگهداری کنید.

تفاوت App Secret و Account API Key#

در این جریان با دو نوع credential متفاوت سروکار دارید:

Account API Key#

Account API Key برای دسترسی به Public API استفاده می‌شود:

text
alphana_api_...

این کلید می‌تواند برای درخواست‌هایی مثل:

text
GET /api/v1/apps
POST /api/v1/apps

استفاده شود.

App Secret#

App Secret به یک App مشخص تعلق دارد و در جریان SDK و ingestion همان App استفاده می‌شود.

این مقدار با Account API Key یکسان نیست و نباید جای یکدیگر استفاده شوند.

به‌صورت خلاصه:

Credentialکاربرد
Account API Keyدسترسی Server-side به Public API در سطح حساب
App Secretاستفاده SDK و ingestion برای یک App مشخص

Account API Key باید فقط در Server نگهداری شود. App Secret نیز باید فقط در contextهایی استفاده شود که برای قرارداد SDK همان App در نظر گرفته شده‌اند.

نگهداری امن Secret#

Secret برگشتی از POST /api/v1/apps را مانند یک credential واقعی مدیریت کنید.

از قرار دادن آن در موارد زیر خودداری کنید:

  • Git Repository
  • فایل‌های commitشده .env
  • Logهای Application
  • خروجی CI/CD
  • Issue Tracker
  • پیام‌های عمومی تیم
  • مستندات عمومی
  • ابزارهای MCP مستندات

اگر App به‌صورت خودکار ساخته می‌شود، بهتر است ثبت Secret هم بخشی از همان Workflow باشد.

استفاده از appId#

بعد از دریافت App، appId معمولاً شناسه‌ای است که برای درخواست‌های بعدی Public API یا تنظیم SDK همان App استفاده می‌شود.

برای مثال، integration شما می‌تواند ابتدا Appها را دریافت کند:

text
GET /api/v1/apps

سپس appId موردنظر را انتخاب کند و آن را برای گزارش یا endpointهای دیگر استفاده کند.

این روش بهتر از وابسته کردن integration به نام App است؛ چون Name می‌تواند تغییر کند اما شناسه برای ارتباط API مناسب‌تر است.

خطاهای رایج#

اگر درخواست فهرست یا ساخت App موفق نبود، ابتدا این موارد را بررسی کنید:

  • Header مربوط به Authorization ارسال شده باشد.
  • API Key با پیشوند alphana_api_ معتبر باشد.
  • API Key متعلق به حساب درست باشد.
  • Body درخواست ساخت با قرارداد فعلی CreateAppDto هماهنگ باشد.
  • مقدار domain معتبر باشد.
  • درخواست با Content-Type: application/json ارسال شده باشد.
  • API Key در Client-side اجرا نشده باشد.

برای درخواست ساخت، بهتر است Status Code و Body خطا را در سمت Server بررسی کنید و فقط پیام عمومی آن را به Client منتقل کنید.

جریان پیشنهادی#

برای integrationهایی که App را از طریق API مدیریت می‌کنند، یک جریان ساده می‌تواند به این شکل باشد:

  1. Account API Key را در Server نگهداری کنید.
  2. با GET /api/v1/apps Appهای قابل‌دسترسی را دریافت کنید.
  3. در صورت نیاز با POST /api/v1/apps App جدید بسازید.
  4. appId پاسخ را برای درخواست‌های بعدی نگهداری کنید.
  5. Secret App تازه را بلافاصله در محل امن ثبت کنید.
  6. Account API Key یا App Secret را وارد Log یا خروجی عمومی نکنید.