title: "مستندات توسعه‌دهندگان بله‌استور" order: 0 description: "نمای کلی انتشار برنامه، SDK پرداخت درون‌برنامه‌ای، API سرور به سرور و مرجع خطاها"

مستندات توسعه‌دهندگان بله‌استور

بله‌استور فروشگاه برنامه‌های اندروید داخل پیام‌رسان بله است. کاربر برنامه را در بله پیدا می‌کند و با یک لمس نصب و به‌روز می‌کند؛ شما فایل APK امضاشدهٔ خودتان را منتشر می‌کنید و بله‌استور هیچ‌وقت آن را دوباره امضا نمی‌کند. به همین دلیل یک بیلد واحد می‌تواند هم‌زمان در بله‌استور، بازار و مایکت منتشر شود و نسخه‌هایی که کاربر از فروشگاه دیگری نصب کرده، از بله‌استور هم به‌روز شوند (به شرط یکسان بودن کلید امضا).

از کجا شروع کنم؟

می‌خواهم… بخوانید
اولین برنامه‌ام را منتشر کنم راهنمای انتشار
بدانم بررسی (Review) چه چیزهایی را رد می‌کند سیاست‌ها و معیارهای بررسی
مالکیت نام بسته را ثابت کنم ابزار اثبات مالکیت (CLI)
پرداخت درون‌برنامه‌ای اضافه کنم SDK اندروید
در بازی Unity پرداخت داشته باشم افزونهٔ Unity
خرید را در سرورم بررسی کنم API سرور به سرور و تأیید توکن خرید
رویدادهای خرید و اشتراک را دریافت کنم Webhookها
از Poolakey (بازار) مهاجرت کنم مهاجرت از Poolakey
از myket-billing-client (مایکت) مهاجرت کنم مهاجرت از مایکت
معنی یک کد خطای نصب یا بارگذاری را بفهمم مرجع کدهای خطا
پل وب ↔ بومی را در اپ میزبان یکپارچه کنم (تیم بله) مرجع پل نصب

مسیر کلی انتشار

  1. ورود به کنسول توسعه‌دهندگان با حساب بله (پیشنهادی) یا ایمیل + کد یک‌بارمصرف.
  2. ساخت سازمان (شخص حقیقی یا حقوقی) و احراز هویت: کد ملی یا شناسهٔ ملی شرکت، و تأیید شمارهٔ موبایل.
  3. پذیرش قرارداد توزیع و سیاست محتوا.
  4. بارگذاری اولین APK: نام بسته، versionCode، targetSdk، ABIها، مجوزها و گواهی امضا از خود فایل خوانده می‌شوند.
  5. اثبات مالکیت بسته با یک APK کوچک که با همان کلید امضا شده است.
  6. تکمیل صفحهٔ فروشگاه (فارسی الزامی است).
  7. ارسال برای بررسی؛ بررسی خودکار معمولاً کمتر از ۳۰ دقیقه و بررسی انسانی کمتر از ۲۴ ساعت (اهداف سرویس).
  8. انتشار فوری یا زمان‌بندی‌شده، با انتشار مرحله‌ای به‌روزرسانی‌ها (پیش‌فرض ۱٪ ← ۱۰٪ ← ۱۰۰٪).

جزئیات هر مرحله در راهنمای انتشار آمده است.

اجزای فنی

جزء توضیح
SDK پرداخت اندروید ir.bale.balestore:billing-sdk:1.0.0؛ API نزدیک به Poolakey تا مهاجرت چند ساعت طول بکشد.
سرویس AIDL پرداخت ir.bale.balestore.billing.IBillingService داخل بله (یا برنامهٔ نصب‌کنندهٔ مستقل)؛ SDK خودش به آن وصل می‌شود.
توکن خرید JWS فشرده با الگوریتم ES256 و کلید عمومی مخصوص هر برنامه.
API سرور به سرور زیر مسیر /s2s/، با OAuth2 client credentials.
Webhook رویدادهای خرید، بازپرداخت و اشتراک با امضای HMAC-SHA256.
ابزار balestore-proof ساخت و بررسی APK اثبات مالکیت.

قراردادهای عمومی API

  • همهٔ APIها JSON با کلیدهای camelCase و UTF-8 هستند. زمان‌ها رشتهٔ ISO-8601 به وقت UTC هستند (2026-11-19T08:00:00Z).

  • مبلغ همیشه عدد صحیح به ریال است (priceRials، amountRials). رابط کاربری تومان (ریال ÷ ۱۰) نشان می‌دهد.

  • خطاها همیشه این شکل را دارند و message فارسی و قابل نمایش به کاربر است:

    { "error": { "code": "UPPER_SNAKE", "message": "…", "details": { } } }
    
  • صفحه‌بندی: ?cursor=<opaque>&limit=<n> ← { "items": [...], "nextCursor": "…" | null } (پیش‌فرض ۲۰، حداکثر ۱۰۰).

  • درخواست‌های مالی سرسانی (mutating) سرآیند Idempotency-Key را می‌پذیرند؛ کلید یکسان با بدنهٔ یکسان همان پاسخ را برمی‌گرداند.

مقادیر قابل تنظیم و موارد باز

بعضی اعداد (نرخ کمیسیون، مهلت تأیید خرید، دورهٔ مهلت اشتراک، سقف حجم فایل، کف targetSdk و…) در پیکربندی بله‌استور تعریف می‌شوند و ممکن است تغییر کنند. در این مستندات هر جا عددی آمده، اگر «پیش‌فرض» یا «قابل تنظیم» گفته شده، مقدار فعلی را در کنسول ببینید. نشانی‌های نهایی دامنه‌ها (سایت، کنسول، API و CDN) در حال نهایی‌شدن است؛ در نمونه‌ها از https://api.<domain> استفاده شده است. در محیط توسعهٔ محلی، درگاه API روی http://localhost:18080 است.