API توسعه‌دهندگان کافه‌بازار

معرفی

API توسعه‌دهندگان کافه‌بازار یک وب‌سرویس مبتنی بر REST است که به شما امکان انجام خودکار برخی از کارهای مدیریت برنامه‌ها و محصولاتتان را می‌دهد. در حال حاضر شما می‌توانید با استفاده از این API، وضعیت خریدها و اشتراک‌های برنامه‌ها و محصولات خود را از طریق سرور شخصی‌تان (بدون نیاز به کلاینت بازار) بررسی کنید.

لازم به ذکر است که همهٔ توسعه‌دهندگان کافه‌بازار نیاز به استفاده از این API ندارند. در اکثر موارد شما می‌توانید به طور مستقیم از پنل توسعه‌دهندگان بازار برای مدیریت خریدهای کاربران و وضعیت اشتراک آن‌ها استفاده کنید. با این حال، اگر تعداد زیادی برنامه و محصول دارید، برای پیگیری این موارد، ممکن است این API برایتان سودمند باشد.

این API به شما این امکان را می‌دهد که با ارسال یک درخواست GET استاندارد از سمت سرور خود، جزئیات اشتراک‌ها و خریدهای درون‌برنامه‌ای خود را دریافت کنید. در این درخواست، شما اطلاعات یک خرید (نام بسته، شناسه محصول یا اشتراک و Token خرید) را ارسال می‌کنید و سرور با یک شئ از نوع JSON شامل جزئیات خرید (وضعیت سفارش، Developer Payload و اطلاعات دیگر) به درخواست شما پاسخ می‌دهد.

شما می توانید از این API در موارد مختلفی از جمله ایجاد گزارش، بررسی وضعیت یک خرید و یا برای تایید خریدها و انقضای اشتراک‌های محصولات خود استفاده کنید. همچنین می‌توانید این API را، برای شناسایی سفارشات لغو شده و تایید اینکه آیا محصول درون‌برنامه‌ای مصرف شده است یا خیر، به کار ببرید.

استفاده از API

کافه‌بازار برای فرآیند Authorization، از پروتکل OAuth 2.0 استفاده می‌کند. برای استفاده از API توسعه‌دهندگان شما باید ابتدا اقدام به ساخت Client در پنل پرداخت بازار کنید، و سپس با استفاده از اطلاعات Client خود، access_code دریافت کنید. access_code توکنی است که باید همراه با هر درخواست به API فرستاده شود.

برای استفاده از API، این مراحل را انجام دهید:

  1. برای استفاده از API ابتدا باید یک Client ایجاد کنید. هر Client شامل اطلاعاتی است که از طرف کافه‌بازار برای شناخته‌شدن یک کاربر API لازم است. برای ساخت Client به پنل پرداخت بازار مراجعه کنید، با استفاده از منوی سمت راست به صفحه‌ٔ «API توسعه‌دهنده» بروید و روی گزینهٔ «Client جدید» کلیک کنید.
  2. در پنجرهٔ باز شده، مقدار مورد نظر خود برای Redirect URI را وارد کنید. این آدرس، مشخص می‌کند که کافه‌بازار در پاسخ به درخواست اولیه شما برای دریافت Authorization Code، باید پاسخ را به چه آدرسی بفرستد.
  3. به آدرس زیر بروید:

    https://pardakht.cafebazaar.ir/auth/authorize/?response_type=code&access_type=offline&redirect_uri=<REDIRECT_URI>&client_id=<CLIENT_ID>
    

    دقت کنید که به جای <REDIRECT_URI> و <CLIENT_ID> باید مقادیر مربوط به Client که در مرحله قبلی ساخته‌اید را وارد کنید.

  4. در صفحهٔ جدید روی تأیید کلیک کنید.
  5. مرورگر، شما را به آدرسی که به عنوان Redirect URI وارد کرده‌اید، هدایت خواهد کرد. همراه با این آدرس، پارامتر code فرستاده می‌شود، که مقدار آن شبیه به affAKBEs80Yz1AjHXtoKHZnWj1UItfnKwp1b5FRg خواهد بود.
  6. با ارسال درخواستی از نوع POST به آدرس
    https://pardakht.cafebazaar.ir/auth/token/
    با این فیلد‌ها
    grant_type=authorization_code
    code=<کد دریافت شده در مرحلهٔ قبل>
    client_id=<شناسه‌ٔ مشخص شده در پنل توسعه‌دهندگان>
    client_secret=<عبارت رمز مشخص شده در پنل توسعه‌دهندگان>
    redirect_uri=<آدرس مشخص شده در پنل توسعه‌دهندگان>
    
    می‌توانید access_code و refresh_code را دریافت کنید.
    پاسخ موفق این درخواست در قالب JSON و به صورت زیر خواهد بود:
    {
       "access_token": "GWObRK06KHLr8pCQzDXJ9hcDdSC3eV",
       "token_type": "Bearer",
       "expires_in": 3600,
       "refresh_token": "yBC4br1l6OCNWnahJvreOchIZ9B6ze",
       "scope": "androidpublisher"
    }
  7. برای استفاده از API، سرور شما باید همراه هر درخواستی از API، پارامتر access_code را بفرستد:
    https://pardakht.cafebazaar.ir/api/<تابع مورد نظر و ورودی‌های آن>?access_token=<توکن دریافت شده در مرحلهٔ قبل>
  8. هر access_code تنها برای مدت محدودی معتبر است. پس از انقضای هر access_code سرور شما می‌تواند با استفاده از refresh_code دریافتی در مرحلهٔ ۶، access_code جدیدی درخواست کند. برای این کار درخواستی از نوع POST به آدرس
    https://pardakht.cafebazaar.ir/auth/token/
    با این فیلد‌ها
    grant_type=refresh_token
    client_id=<شناسه‌ٔ مشخص شده در پنل توسعه‌دهندگان>
    client_secret=<عبارت رمز مشخص شده در پنل توسعه‌دهندگان>
    refresh_token=<توکن دریافتی در مرحلهٔ ۶>
    
    بفرستید. پاسخ موفق این درخواست در قالب JSON و به صورت زیر خواهد بود:
    {
       "access_token": "uX5qC82EGWjkjjeyvTzTufHOM9HZfM",
       "token_type": "Bearer",
       "expires_in": 3600,
       "scope": "androidpublisher"
    }
    به این صورت، بدون نیاز به ورود به حساب کافه‌بازار، سرور شما می‌تواند به API توسعه‌دهندگان به صورت پیوسته دسترسی داشته باشد.

توابع پیاده‌سازی شده در API

تا به حال توابع زیر در API توسعه‌دهندگان کافه‌بازار پیاده‌سازی شده‌اند:

  1. تابع بررسی وضعیت خرید درون‌برنامه‌ای:
    این تابع وضعیت خرید و مصرف یک محصول درون‌برنامه‌ای را مشخص می‌کند.
    https://pardakht.cafebazaar.ir/api/validate/<package_name>/inapp/<product_id>/purchases/<purchase_token>/?access_token=<access_token>
    توجه کنید که مقادیری که داخل پرانتز شکسته – <> – قرار دارند را با توجه به درخواستتان پر کنید. نتیجه‌ٔ این تابع به این‌صورت خواهد بود:
    {
       "consumptionState": 1,
       "purchaseState": 0,
       "kind": "androidpublisher#inappPurchase",
       "developerPayload": "something",
       "purchaseTime": 1414181378566
    }
  2. تابع بررسی وضعیت اشتراک: این تابع وضعیت و تاریخ شروع و پایان یک اشتراک را مشخص می‌کند.
    https://pardakht.cafebazaar.ir/api/applications/<package_name>/subscriptions/<subscription_id>/purchases/<purchase_token>/?access_token=<access_token>
    نتیجه‌ٔ این تابع به این‌صورت خواهد بود:
    {
            "kind": "androidpublisher#subscriptionPurchase",
            "initiationTimestampMsec": 1414181378566,
            "validUntilTimestampMsec": 1435912745710,
            "autoRenewing": true,
    }
  3. تابع لغو اشتراک: این تابع اشتراک مورد نظر را لغو می‌کند.
    https://pardakht.cafebazaar.ir/api/applications/<package_name>/subscriptions/<subscription_id>/purchases/<purchase_token>/cancel/?access_token=<access_token>
    در صورت موفقیت در لغو اشتراک، بدنهٔ پاسخ این تابع خالی خواهد بود. این تابع تنها از پرداخت‌های بعدی جلوگیری خواهد کرد و پرداخت‌های انجام شده تا به حال برگشت داده نخواهند شد. همچنین اشتراک تا زمان انقضا برقرار خواهد ماند.