Partner API — نمای کلی

یک رابط REST دارای موجودی پیش‌پرداخت برای پلتفرم‌های B2B — کاربران خود را در درگاه AI آشا مدیریت کنید.

آشا یک Partner API اختصاصی و پیش‌پرداخت فراهم می‌کند تا پلتفرم شما بتواند کاربران خود را در درگاه هوش مصنوعی آشا مدیریت کند: ثبت‌نام تنبلانه، شارژ موجودی و صدور کلید API — همه بدون در اختیار گذاشتن اعتبارنامه داشبورد.

نسخه مستندات: ۲.۰

تغییر شکست‌پذیر نسخه ۲.۰: اندپویت‌های کاربر اکنون با external_user_identifier شما مشخص می‌شوند (نه شماره تلفن). شماره تلفن همراه آن فقط وقتی استفاده می‌شود که شناسه خارجی جدید باشد.

آدرس پایه و مدارک

همه درخواست‌ها با فرمت JSON ارسال می‌شوند. آدرس پایهٔ محیط تولید:

BASE URL production

https://app.asha-ai.ir/partner/v1

مدارک: هر همکار یک کلید Partner API اختصاصی دارد که هنگام پذیرش همکاری از سوی تیم آشا در اختیار شما قرار می‌گیرد.

KEY partner_api_key

partner_<partner_code>_<40-character-random-secret>

کلید کامل فقط یک بار هنگام تنظیم همکاری در اختیار شما قرار می‌گیرد — آن را امن نگه دارید.
نوع مدارک مستقلی است و با کلیدهای کاربری sk-asha-* کاملاً جدا است.
اگر کلیدتان افشا شد، فوراً به تیم پشتیبانی آشا گزارش دهید تا آن را باطل کنند.

احراز هویت

همه درخواست‌ها با همین هدر احراز هویت می‌کنند:

HEADER Authorization

Authorization: Bearer <partner_api_key>

هدر	مقدار	توضیح
`Authorization`	`Bearer partner_...`	الزامی.
`Content-Type`	`application/json`	الزامی برای درخواست‌های POST با بدنه.

مفاهیم کلیدی

شناسه خارجی کاربر + شماره تلفن

هر کاربر شما با شناسه خارجی (شناسه کاربری پایگاهای خودتان) تعریف می‌شود — مثلاً UUID یا شناسه داخلی شما — تا ۲۵۵ حرف، مقایسه دقیق (case-sensitive). این شناسه، کلید معتبر نگاشت است: به‌محض نگاشت partner + external_user_identifier به یک کاربر آشا، هر درخواست بعدی با همان شناسه، همان کاربر آشا را برمی‌گرداند — حتی اگر شماره تلفن تغییر کرده باشد.

شماره موبایل ایرانی در قالب 09XXXXXXXXX همراه شناسه ارسال می‌شود و فقط زمانی که شناسه خارجی جدید است استفاده می‌شود: اگر آن شماره از قبل در آشا موجود باشد همان کاربر استفاده می‌شود، وگرنه اکانت جدید ساخته می‌شود. ارقام فارسی/عربی (۰۱۲۳...) پذیرفته و خودکار نرمال می‌شوند.

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

موجودی همکار (پیش‌پرداخت)

هر همکار موجودی ریالی پیش‌پرداخت دارد که توسط تیم آشا شارژ می‌شود. هر شارژی که برای کاربر می‌گذارید از این موجودی کسر می‌شود. موجودی ثبت دفتری ندارد — برای افزایش آن با تیم آشا تماس بگیرید.

توانایی تکرار (Idempotency)

عملیات شارژ نیاز به external_transaction_id یکتا دارند. ارسال مجدد همان شناسه، همان نتیجه قبلی را برمی‌گرداند بدون جا به جا انتقال پول (already_processed: true).

اندپویت‌ها

همه اندپویتها با آدرس پایهٔ https://app.asha-ai.ir/partner/v1 ترکیب می‌شوند:

متد	مسیر	شرح
`POST`	`/users/authenticate`	ساخت یا دریافت کاربر
`GET`	`/wallet`	موجودی کیف پول همکار
`GET`	`/users/{external_user_identifier}/wallet`	موجودی کیف پول کاربر
`POST`	`/users/{external_user_identifier}/wallet/credit`	شارژ اعتبار کاربر
`POST`	`/users/{external_user_identifier}/api-keys`	ساخت کلید API کاربر
`POST`	`/users/{external_user_identifier}/api-keys/{api_key_id}/disable`	غیرفعال‌سازی کلید API کاربر

۱. ساخت یا دریافت کاربر

POST /partner/v1/users/authenticate

POST https://app.asha-ai.ir/partner/v1/users/authenticate

کاربر داخلی partner + phone را پیدا می‌کند؛ اگر وجود نداشت، حساب را (با کیف پول و اشتراک رایگان) می‌سازد. همچنین کلید OpenRouter اختصاصی کاربر را فراهم می‌کند؛ اگر آماده نشد، پاسخ "provisioning": "pending" را برمی‌گرداند و ورکر آن را در پس‌زمینه تکمیل می‌کند.

بدنه درخواست

JSON body

{
  "external_user_identifier": "user_92831",
  "phone": "09123456789"
}

فیلد	نوع	الزامی	توضیح
`external_user_identifier`	string	بله	شناسه کاربری خودتان (۱ تا ۲۵۵ حرف، مقایسه دقیق) — کلید نگاشت معتبر.
`phone`	string	بله	`09XXXXXXXXX`؛ ارقام فارسی پذیرفته است. فقط برای شناسه خارجی جدید استفاده می‌شود.

پاسخ موفق — `200 OK`

JSON response

{
  "user_id": 38,
  "external_user_identifier": "user_92831",
  "phone": "09123456789",
  "status": "active",
  "provisioning": "ready",
  "created": true,
  "detail": "User authenticated successfully",
  "code": "PARTNER_USER_AUTHENTICATED"
}

user_id — شناسه داخلی کاربر؛ در صورت نیاز برای فیلد خارجی خود نگه دارید.
external_user_identifier — همان شناسه ارسالی شما در پاسخ بازتاب می‌شود.
phone — شماره تلفن فعلی کاربر در آشا.
provisioning — ready: کلید OpenRouter آماده است؛ pending: به‌زودی آماده می‌شود.
created — true اگر حساب همین حالا ساخت شد.
code — PARTNER_USER_AUTHENTICATED.

مثال cURL

bash curl

curl.exe -X POST https://app.asha-ai.ir/partner/v1/users/authenticate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer partner_acme_<secret>" \
  -d "{\"external_user_identifier\": \"user_92831\", \"phone\": \"09123456789\"}"

خطاهای اعتبارسنجی: 400 — فرمت شماره تلفن نامعتبر، یا شناسه خارجی خالی/بیش از ۲۵۵ حرف.

۲. موجودی کیف پول همکار

GET /partner/v1/wallet

GET https://app.asha-ai.ir/partner/v1/wallet

موجودی پیش‌پرداخت همکار احرازشده را برمی‌گرداند (برای مرجع، همان مقداری که از تیم آشا دریافت کرده‌اید).

پاسخ موفق — `200 OK`

JSON response

{
  "partner_code": "acme",
  "balance": "2000000",
  "currency": "IRR",
  "detail": "Partner balance retrieved",
  "code": "PARTNER_WALLET_OK"
}

مثال cURL

bash curl

curl.exe https://app.asha-ai.ir/partner/v1/wallet \
  -H "Authorization: Bearer partner_acme_<secret>"

۳. موجودی کیف پول کاربر

GET /partner/v1/users/{external_user_identifier}/wallet

GET https://app.asha-ai.ir/partner/v1/users/{external_user_identifier}/wallet

موجودی کیف پول یکی از کاربران خود همکار را برمی‌گرداند.

پارامتر	مثال	توضیح
`external_user_identifier`	`user_92831`	شناسه کاربری پایگاه خودتان

پاسخ موفق — `200 OK`

JSON response

{
  "partner_code": "acme",
  "external_user_identifier": "user_92831",
  "phone": "09993456789",
  "balance": "1000000",
  "currency": "IRR",
  "detail": "User wallet retrieved",
  "code": "PARTNER_USER_WALLET_OK"
}

مثال cURL

bash curl

curl.exe https://app.asha-ai.ir/partner/v1/users/user_92831/wallet \
  -H "Authorization: Bearer partner_acme_<secret>"

خطاها: 404 — برای این همکار+شناسه خارجی هیچ نگاشتی وجود ندارد (کاربر هنوز احراز نشده).

۴. شارژ اعتبار کاربر

POST /partner/v1/users/{external_user_identifier}/wallet/credit

POST https://app.asha-ai.ir/partner/v1/users/{external_user_identifier}/wallet/credit

به‌صورت اتمیک مبلغ amount ریال از موجودی همکار به کیف پول کاربر منتقل می‌کند:

هر دو ردیف را قفل می‌کند، مالکیت و کفایت موجودی را بررسی و سپس در یک تراکنشن دیتابیس پول و تراکنشن سمت کاربر را ثبت می‌کند.
توانایی تکرار: جفت (partner, external_transaction_id) یکتاست؛ درخواست تکراری همان نتیجه را بدون شارژ مجدد برمی‌گرداند.
موجودی ناکافی همکار → 402؛ هیچ چیزی تغییر نمی‌کند.

بدنه درخواست

JSON body

{
  "amount": 1000000,
  "currency": "IRR",
  "external_transaction_id": "payment-2026-0001"
}

فیلد	نوع	الزامی	توضیح
`amount`	number	بله	ریال؛ باید بزرگ‌تر از ۰ باشد.
`currency`	string	بله	فقط `"IRR"` پشتیبانی می‌شود.
`external_transaction_id`	string	بله	شناسه یکتای شما (حداکثر ۲۵۶ نویسه). تکرار → همان نتیجه.

پاسخ موفق — `200 OK`

JSON response

{
  "amount": "1000000",
  "currency": "IRR",
  "external_transaction_id": "payment-2026-0001",
  "partner_balance": "1000000",
  "user_balance": "1000000",
  "already_processed": false,
  "detail": "Credit applied",
  "code": "PARTNER_CREDIT_OK"
}

ارسال مجدد همان شناسه (already_processed: true):

JSON response (idempotent replay)

{
  "amount": "1000000",
  "currency": "IRR",
  "external_transaction_id": "payment-2026-0001",
  "partner_balance": "1000000",
  "user_balance": "1000000",
  "already_processed": true,
  "detail": "Credit request already processed",
  "code": "PARTNER_CREDIT_ALREADY_PROCESSED"
}

مثال cURL

bash curl

curl.exe -X POST https://app.asha-ai.ir/partner/v1/users/user_92831/wallet/credit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer partner_acme_<secret>" \
  -d "{\"amount\": 1000000, \"currency\": \"IRR\", \"external_transaction_id\": \"payment-2026-0001\"}"

خطاها

400 — شناسه خارجی نامعتبر / مبلغ غیرمثبت / ارز غیر IRR / شناسه نامعتبر یا ناقص.
402 — موجودی همکار کافی نیست.
404 — کاربری متناظر برای این همکار پیدا نشد.
409 — همان external_transaction_id قبلاً برای کاربر یا مبلغ دیگری استفاده شده است.

توصیه: external_transaction_id را یک UUID یا مقداری شبیه {your_payment_id} قرار دهید. هرگز آن را بین شارژهای مختلف بازاستفاده نکنید.

۵. ساخت کلید API کاربر

POST /partner/v1/users/{external_user_identifier}/api-keys

POST https://app.asha-ai.ir/partner/v1/users/{external_user_identifier}/api-keys

برای یکی از کاربران خود همکار، کلید API سازگار با OpenAI (sk-asha-...) می‌سازد — همان کلیدی که کاربر نهایی در کلاینت SDK خود استفاده می‌کند.

از همان مسیر ساخت کلید داشبورد استفاده می‌کند (sk-asha-، هش SHA-256 در ذخیره).
یک کاربر می‌تواند چندین کلید مستقل داشته باشند.
کیف پولی که در قسمت ۴ شارژ کردید، هزینه تماس‌های این کلید را پرداخت می‌کند.
همانند شارژ کیف پول: یک key_creation_id یکتا بفرستید؛ تکرار درخواست با همان key_creation_id کلید دومی نمی‌سازد و همان کلید قبلی با already_processed: true برمی‌گردد.

بدنه درخواست

JSON body

{ "key_creation_id": "key-create-2026-0001", "name": "my-key", "credit_limit": 500000 }

فیلد	نوع	الزامی	توضیح
`key_creation_id`	string	بله	شناسه یکتای شما (۱–۲۵۵ نویسه). تکرار → بی‌اثر (کلید دومی ساخته نمی‌شود)
`name`	string	نه	لیبل نمایشی، حداکثر ۱۰۰ نویسه.
`credit_limit`	number	نه	سقف جمیعی ریال برای این کلید؛ حذف یا `0`/`null` → بدون محدودیت.

پاسخ موفق — `201 Created`

JSON response

{
  "id": 35,
  "key_prefix": "sk-asha-1db4fd6302e...261d",
  "name": null,
  "status": "active",
  "credit_limit": null,
  "created_at": "2026-09-13T15:20:44Z",
  "already_processed": false,
  "full_key": "sk-asha-1db.........61d",
  "detail": "API key created",
  "code": "PARTNER_API_KEY_CREATED"
}

full_key — همان کلید واقعی؛ فقط یک بار برگردانده می‌شود. فوراً ذخیره کنید؛ دیگر هرگز قابل بازیابی نیست. فقط key_prefix بعداً ذخیره/برگردانده می‌شود.
credit_limit — null به معنای بدون محدودیت است.
already_processed — false: کلید تازه ساخته شد؛ true: این key_creation_id قبلاً استفاده شده است.
code — PARTNER_API_KEY_CREATED (بار اول) / PARTNER_API_KEY_ALREADY_CREATED (بازپخش).

تکرار درخواست (بازپخش همان `key_creation_id`) — `201` با `already_processed: true`

JSON replay

{
  "id": 35,
  "key_prefix": "sk-asha-1db4fd6302e...261d",
  "name": null,
  "status": "active",
  "credit_limit": null,
  "created_at": "2026-09-13T15:20:44Z",
  "already_processed": true,
  "full_key": null,
  "detail": "Key already exists for this key_creation_id",
  "code": "PARTNER_API_KEY_ALREADY_CREATED"
}

توجه: اگر با همان key_creation_id تکرار کنید، already_processed: true و full_key ندارد (کلید همان بار اول ساخته شده). اگر آن را گم کرده‌اید، با یک key_creation_id جدید کلید تازه بسازید.

کلید بدون محدودیت (بدون سقف)

JSON body

{ "key_creation_id": "key-create-2026-0002" }

مثال cURL

bash curl

curl.exe -X POST https://app.asha-ai.ir/partner/v1/users/user_92831/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer partner_acme_<secret>" \
  -d "{\"key_creation_id\": \"key-create-2026-0001\", \"name\": \"my-key\"}"

خطاها

404 — کاربر متناظر برای این همکار پیدا نشد.
400 — شناسه خارجی نامعتبر / key_creation_id از قلم افتاده / name نامعتبر / credit_limit منفی.
409 — همان key_creation_id برای کاربر دیگری استفاده شده است.

۶. غیرفعال‌سازی کلید API کاربر

POST /partner/v1/users/{external_user_identifier}/api-keys/{api_key_id}/disable

POST https://app.asha-ai.ir/partner/v1/users/{external_user_identifier}/api-keys/{api_key_id}/disable

کلید API یکی از کاربران خود همکار را غیرفعال (باطل) می‌کند — همان اقدام «غیرفعال‌سازی» در داشبورد کاربر. کلید دیگر هرگز قابل فعال‌سازی مجدد نیست.

مالکیت اجباری: فقط کلیدِ کاربری که به شما نگاشت شده و فقط کلیدی که واقعاً متعلق به همان کاربر است قابل غیرفعال‌سازی است.
بی‌اثر (idempotent): غیرفعال‌سازی کلیدِ از‌قبل‌غیرفعال، تغییری ایجاد نمی‌کند و already_disabled: true برمی‌گردد (بدون خطا).

پارامترهای مسیر

پارامتر	مثال	توضیح
`external_user_identifier`	`user_92831`	شناسه کاربر شما
`api_key_id`	`35`	همان `id` کلیدِ برگشت‌داده‌شده در قسمت ۵

پاسخ موفق — `200 OK`

JSON response

{
  "id": 35,
  "key_prefix": "sk-asha-1db4fd6302e...261d",
  "name": null,
  "status": "revoked",
  "credit_limit": null,
  "created_at": "2026-09-13T15:20:44Z",
  "already_disabled": false,
  "detail": "API key disabled",
  "code": "PARTNER_API_KEY_DISABLED"
}

کلید از‌قبل غیرفعال (بازپخش) — `200 OK` با `already_disabled: true`

JSON replay

{
  "id": 35,
  "key_prefix": "sk-asha-1db4fd6302e...261d",
  "name": null,
  "status": "revoked",
  "credit_limit": null,
  "created_at": "2026-09-13T15:20:44Z",
  "already_disabled": true,
  "detail": "API key already disabled",
  "code": "PARTNER_API_KEY_ALREADY_DISABLED"
}

خطاها

404 — PARTNER_API_KEY_NOT_FOUND: چنین کلیدی وجود ندارد یا به کاربرِ این همکار تعلق ندارد.

مثال cURL

bash curl

curl.exe -X POST https://app.asha-ai.ir/partner/v1/users/user_92831/api-keys/35/disable \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer partner_acme_<secret>"

استفاده از کلید صادرشده (سازگار با OpenAI)

full_key به‌عنوان کلید OpenAI آمادهٔ استفاده کار می‌کند. SDK خود را به آدرس پایهٔ آشا کنید:

TXT base_url

https://app.asha-ai.ir/v1

Python (openai SDK)

python example.py

from openai import OpenAI

client = OpenAI(
    api_key="sk-asha-1db.........61d",
    base_url="https://app.asha-ai.ir/v1",
)

chat = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)
print(chat.choices[0].message.content)

cURL

bash curl

curl.exe https://app.asha-ai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-asha-1db.........61d" \
  -d "{\"model\": \"openai/gpt-4o\", \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}]}"

هزینه‌دهی بر اساس مصرف واقعی است: بعد از هر تماس، هزینه دقیق ریال از کیف پول کاربر (همان کیف پولی که در قسمت ۴ شارژ کردید) کسر می‌شود. اگر موجودی تمام شود، تماس‌ها با 402 رد می‌شوند تا مجدد شارژ شود.

پاسخ‌های خطا

پاسخ‌ها از کدهای وضعیت استاندارد HTTP استفاده می‌کنند. بدنه پاسخ به‌صورت JSON است:

JSON error_body

{ "detail": "پیام خوانا به فارسی", "code": "PARTNER_..." }

قانون برای توسعه‌دهندگان همکار: منطق شما باید بر اساس code باشد، هرگز بر اساس متن detail یا ساختار JSON پیام‌های خطا. متن detail ممکن است هر زمان بازنویسی شود؛ code قرارداد ثابت است. هر پاسخ Partner — موفق یا خطا — یک code یک‌به‌یک با detail دارد.

کد	معنی
`200`	موفقیت
`201`	ساخته شد (ساخت کلید API)
`400`	درخواست نامعتبر (شماره/مبلغ/شناسه ناقص و...)
`401`	کلید Partner ناقص/نامعتبر/غیرفعال یا اکانت همکار غیرفعال
`402`	موجودی ناکافی (همکار)
`404`	برای این همکار + شناسه خارجی کاربری پیدا نشد، یا چنین کلید API وجود ندارد
`409`	`external_transaction_id` برای شارژ دیگری بازاستفاده شده است یا `key_creation_id` برای کاربر دیگری بازاستفاده شده است
`422`	خطای اعتبارسنجی اسکیما (فیلد اجباری ناقص و...)
`429`	تعداد درخواست‌ها بیش از حد مجاز (rate limit)
`5xx`	خطای بالادستی — با بک‌آف مجدد تلاش کنید

کدهای ثابت («code»)

هر detail یک code ثابت دارد. آن‌هایی که بیشتر به آن‌ها برخواهید خورد:

HTTP	`code`	چه زمانی
`401`	`PARTNER_UNAUTHORIZED`	توکن Bearer ناقص/خالی
`401`	`PARTNER_API_KEY_INVALID`	کلید Partner اشتباه/غیرفعال/ناشناس
`401`	`PARTNER_ACCOUNT_DISABLED`	اکانت همکار غیرفعال است
`404`	`PARTNER_USER_NOT_FOUND`	کاربر برای این همکار نگاشت نشده
`404`	`PARTNER_API_KEY_NOT_FOUND`	چنین کلید API وجود ندارد یا به کاربر این همکار تعلق ندارد
`402`	`PARTNER_BALANCE_INSUFFICIENT`	موجودی رزرو همکار کافی نیست
`409`	`PARTNER_CREDIT_ID_CONFLICT`	`external_transaction_id` برای شارژ دیگری استفاده شده
`409`	`PARTNER_KEY_CREATION_ID_CONFLICT`	`key_creation_id` برای کاربر دیگری استفاده شده
`422`	`PARTNER_VALIDATION_ERROR`	بدنه درخواست از اعتبارسنجی اسکیما رد شد
`200`/`201`	`PARTNER__OK` / `PARTNER__CREATED`...	کدهای موفقیت ویژه هر اندپویت (در بالا در هر اندپویت نشان داده شده)

detailهای ناشناخته باز هم با یک کد برمی‌گردند (PARTNER_ERROR / PARTNER_VALIDATION_ERROR) — هر کدی را که نمی‌شناسید به‌عنوان شکست عمومی در نظر بگیرید؛ وضعیت HTTP همچنان مرجع است.

محدودیت نرخ

درخواست‌ها محدوده می‌شوند (پیش‌فرض ۱٬۲۰۰ درخواست در ۶۰ ثانیه برای هر تماس‌گیرنده). ترکش را پخش کنید؛ در 429 با بک‌آف نمایی مجدد تلاش کنید.

عملیات	آیا تکرار پذیر است؟
`authenticate`	بله — idempotent (همان شناسه خارجی → همان کاربر)
`GET /wallet`، `GET /users/{external_user_identifier}/wallet`	بله — فقط خواندنی
`credit`	بله — همان `external_transaction_id` را مجدد بفرستید
`api-keys`	بله — همان `key_creation_id` را مجدد بفرستید (کلید اصلی برمی‌گردد، کلید دومی ساخته نمی‌شود)
`api-keys/{id}/disable`	بله — کلیدهای از‌قبل غیرفعال `already_disabled: true` برمی‌گردانند

شروع سریع

موجودی همکار شما را شارژ کنید (با تیم آشا تماس بگیرید).
کاربر را بسازید/دریافت کنید: POST /users/authenticate با {external_user_identifier, phone} → user_id.
موجودی همکار و کاربر را بررسی کنید (اختیاری).
کاربر را شارژ کنید: POST /users/{external_user_identifier}/wallet/credit با یک external_transaction_id یکتا → کاربر اکنون موجودی خرج دارد.
کلید صادر کنید: POST /users/{external_user_identifier}/api-keys با یک key_creation_id یکتا → full_key.
full_key + https://app.asha-ai.ir/v1 را به کاربر نهایی بسپارید — او تماس‌های سازگار با OpenAI می‌گیرد و از کیف پول شما پرداخت می‌کند.
هر زمان با شارژ مجدد (شناسه جدید) دوباره شارژ کنید.
وقتی کاربری را قطع کردید، کلیدش را غیرفعال کنید: POST /users/{external_user_identifier}/api-keys/{id}/disable.

داشبورد نماینده (پنل وب)

علاوه بر رابط، هر همکار می‌تواند یک نماینده داشته باشد — کارمند همکار که وارد داشبورد وب آشا می‌شود و کاربران همکار را از طریق یک پنل تصویری (به‌جای رابط) مدیریت می‌کند.

نماینده توسط تیم آشا / مدیر تعیین می‌شود (Partner.representative_user_id). فقط کاربرِ تعیین‌شدهٔ یک همکار فعال منوی «داشبورد همکاران» و مسیرهای آن را می‌بیند.
پنل در /partners/dashboard در وب‌اپ آشا قرار دارد — ورود جداگانه لازم نیست؛ نماینده با اکانت داشبورد معمولی خود وارد می‌شود.
نماینده چه می‌تواند کند (همه محدود به همکارِ خود):
مشاهده موجودی پیش‌پرداخت همکار و تعداد کل کاربران،
مرور بر کاربران همکار (جستجو + مرتب‌سازی بر اساس جدیدترین/قدیمی‌ترین/موجودی/مصرف)،
باز کردن یک کاربر و دیدن کلیدهای API او با مصرف هر کلید (توکن/درخواست/هزینه) و وضعیت هر کلید (فعال/غیرفعال).

نماینده نمی‌تواند کلید API بسازد یا غیرفعال کند — ساخت و غیرفعال‌سازی کلید تنها از طریق رابط Partner API (قسمت‌های ۵ و ۶) انجام می‌شود؛ پنل برای کلیدها فقط‌خواندنی است. نماینده همچنین نمی‌تواند موجودی را تغییر دهد، کاربر بسازد یا به دادهٔ همکارهای دیگر دسترسی داشته باشد. موجودی و شارژها نزد تیم آشا باقی است.

مستنداتی که از دکمهٔ «مستندات همکاران» در پنل باز می‌شود در آدرس https://asha-ai.ir/partners/docs قرار دارد.

محدودیت‌ها و نکات: فقط ارز IRR پشتیبانی می‌شود؛ شماره‌ها باید موبایل ایرانی (09XXXXXXXXX) باشند؛ external_user_identifier مقایسه دقیق و حداکثر ۲۵۵ حرف است — آن را برای هر کاربر ثابت نگه دارید؛ موجودی همکار فقط توسط تیم آشا شارژ می‌شود (رابط خودخدمت وجود ندارد)؛ هر همکار فقط کاربران خود را مدیریت می‌کند — درخواست برای کاربر همکار دیگر 404 برمی‌گرداند؛ باطل شدن کلید Partner همکار، فوراً همه اندپویت‌های همکار را متوقف می‌کند اما کلیدهای صادرشدهٔ کاربر (sk-asha-*) تا لحظهٔ لغو جداگانه معتبر می‌مانند.

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

Partner API — نمای کلی

آدرس پایه و مدارک

احراز هویت

مفاهیم کلیدی

شناسه خارجی کاربر + شماره تلفن

موجودی همکار (پیش‌پرداخت)

توانایی تکرار (Idempotency)

اندپویت‌ها

۱. ساخت یا دریافت کاربر

بدنه درخواست

پاسخ موفق — 200 OK

مثال cURL

۲. موجودی کیف پول همکار

پاسخ موفق — 200 OK

مثال cURL

۳. موجودی کیف پول کاربر

پاسخ موفق — 200 OK

مثال cURL

۴. شارژ اعتبار کاربر

بدنه درخواست

پاسخ موفق — 200 OK

مثال cURL

خطاها

۵. ساخت کلید API کاربر

بدنه درخواست

پاسخ موفق — 201 Created

تکرار درخواست (بازپخش همان key_creation_id) — 201 با already_processed: true

کلید بدون محدودیت (بدون سقف)

مثال cURL

خطاها

۶. غیرفعال‌سازی کلید API کاربر

پارامترهای مسیر

پاسخ موفق — 200 OK

کلید از‌قبل غیرفعال (بازپخش) — 200 OK با already_disabled: true

خطاها

مثال cURL

استفاده از کلید صادرشده (سازگار با OpenAI)

Python (openai SDK)

cURL

پاسخ‌های خطا

کدهای ثابت («code»)

محدودیت نرخ

شروع سریع

داشبورد نماینده (پنل وب)

پاسخ موفق — `200 OK`

پاسخ موفق — `200 OK`

پاسخ موفق — `200 OK`

پاسخ موفق — `200 OK`

پاسخ موفق — `201 Created`

تکرار درخواست (بازپخش همان `key_creation_id`) — `201` با `already_processed: true`

پاسخ موفق — `200 OK`

کلید از‌قبل غیرفعال (بازپخش) — `200 OK` با `already_disabled: true`