مدیریت محصولات درون‌برنامه‌ای با API

با APIهای زیر می‌توانید محصولات برنامه را از سرور خود دریافت، ایجاد یا ویرایش کنید. این سرویس‌ها فقط باید به‌صورت Server to Server فراخوانی شوند.

امنیت

درخواست‌ها باید از سرور شما ارسال شوند. توکن X-Access-Token را در برنامهٔ کلاینت قرار ندهید؛ افشای آن می‌تواند امکان سوءاستفاده از دسترسی برنامه را فراهم کند.

احراز هویت

در همهٔ درخواست‌ها، توکن صحت‌سنجی برنامه را از پنل توسعه‌دهندگان دریافت و در هدر X-Access-Token ارسال کنید. در مثال‌ها، {PACKAGE_NAME} نام پکیج برنامه است.

دریافت فهرست محصولات

cURL

curl --request GET \
  'https://developer.myket.ir/api/partners/applications/{PACKAGE_NAME}/products?limit=10&offset=0' \
  --header 'X-Access-Token: {ACCESS_TOKEN}'

Python

import requests

package_name = "org.example.app"
url = f"https://developer.myket.ir/api/partners/applications/{package_name}/products"
headers = {"X-Access-Token": "YOUR_ACCESS_TOKEN"}
params = {"limit": 10, "offset": 0}

response = requests.get(url, headers=headers, params=params)
print(response.status_code, response.json())

• limit: تعداد محصولات در پاسخ؛ پیش‌فرض 100 و حداکثر 1000 است.
• offset: شمارهٔ صفحه؛ پیش‌فرض 0 و برابر با صفحهٔ اول است.

نمونهٔ پاسخ:

{
  "skus": [
    {
      "skuId": "GEM1",
      "farsiTitle": "الماس مرحله اول",
      "price": 10000,
      "creationDate": "2024-07-27T00:00:05.41",
      "isActive": true
    }
  ],
  "totalCount": 1
}

ایجاد محصول

برای ایجاد محصول درون‌برنامه‌ای از نوع مصرف‌شدنی، درخواست POST زیر را ارسال کنید:

cURL

curl --request POST \
  'https://developer.myket.ir/api/partners/applications/{PACKAGE_NAME}/products' \
  --header 'X-Access-Token: {ACCESS_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "skuId": "100GOLD2000",
    "farsiTitle": "صد طلا",
    "price": 20000,
    "isActive": false
  }'

Python

import requests

package_name = "org.example.app"
url = f"https://developer.myket.ir/api/partners/applications/{package_name}/products"
headers = {"X-Access-Token": "YOUR_ACCESS_TOKEN"}
payload = {
    "skuId": "100GOLD2000",
    "farsiTitle": "صد طلا",
    "price": 20000,
    "isActive": False,
}

response = requests.post(url, headers=headers, json=payload)
print(response.status_code, response.json())

ایجاد گروهی محصولات

با این سرویس می‌توانید حداکثر ۲۰۰ محصول درون‌برنامه‌ای را در یک درخواست ایجاد کنید. اطلاعات محصولات باید مستقیماً به‌صورت یک آرایهٔ JSON ارسال شوند.

آدرس سرویس

POST https://developer.myket.ir/api/partners/applications/{PACKAGE_NAME}/products/batch

مقدار {PACKAGE_NAME} را با نام پکیج برنامه جایگزین کنید.

ساختار درخواست

هدرهای درخواست:

X-Access-Token: {ACCESS_TOKEN}
Content-Type: application/json

بدنهٔ درخواست باید مستقیماً آرایه‌ای از محصولات باشد:

[
  {
    "skuId": "COINS_100",
    "farsiTitle": "بسته ۱۰۰ سکه",
    "price": 10000,
    "isActive": true
  },
  {
    "skuId": "COINS_500",
    "farsiTitle": "بسته ۵۰۰ سکه",
    "price": 50000,
    "isActive": false
  }
]

نیازی به ارسال AccountId یا نام پکیج در بدنه نیست. حساب توسعه‌دهنده از توکن دسترسی و نام پکیج از مسیر درخواست مشخص می‌شود.

فیلدهای هر محصول

فیلد	نوع	الزامی	توضیح
skuId	string	بله	شناسهٔ یکتای محصول در برنامه؛ حداکثر ۱۰۰ کاراکتر
farsiTitle	string	بله	عنوان فارسی محصول؛ حداکثر ۱۵۰ کاراکتر
price	عدد صحیح	بله	قیمت به ریال؛ حداقل ۱۰۰۰ و حداکثر ۲٬۰۰۰٬۰۰۰٬۰۰۰ ریال
isActive	boolean	خیر	وضعیت فعال‌بودن محصول؛ در صورت ارسال‌نشدن، مقدار false در نظر گرفته می‌شود

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

cURL

curl --request POST \
  'https://developer.myket.ir/api/partners/applications/{PACKAGE_NAME}/products/batch' \
  --header 'X-Access-Token: {ACCESS_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "skuId": "COINS_100",
      "farsiTitle": "بسته ۱۰۰ سکه",
      "price": 10000,
      "isActive": true
    },
    {
      "skuId": "COINS_500",
      "farsiTitle": "بسته ۵۰۰ سکه",
      "price": 50000,
      "isActive": false
    }
  ]'

Python

import requests

package_name = "org.example.app"
access_token = "YOUR_ACCESS_TOKEN"

url = (
    "https://developer.myket.ir/api/partners/applications/"
    f"{package_name}/products/batch"
)

headers = {
    "X-Access-Token": access_token,
}

products = [
    {
        "skuId": "COINS_100",
        "farsiTitle": "بسته ۱۰۰ سکه",
        "price": 10000,
        "isActive": True,
    },
    {
        "skuId": "COINS_500",
        "farsiTitle": "بسته ۵۰۰ سکه",
        "price": 50000,
        "isActive": False,
    },
]

response = requests.post(
    url,
    headers=headers,
    json=products,
    timeout=30,
)

print(response.status_code)
print(response.text)

محدودیت‌ها و اعتبارسنجی

• هر درخواست باید حداقل یک و حداکثر ۲۰۰ محصول داشته باشد. برای ایجاد تعداد بیشتر، محصولات را در چند درخواست جداگانه ارسال کنید.
• شناسهٔ محصولات در آرایه نباید تکراری باشد. در بررسی تکرار داخل آرایه، بزرگی و کوچکی حروف تفاوتی ندارد؛ برای مثال COINS_100 و coins_100 تکراری محسوب می‌شوند.
• هیچ‌یک از شناسه‌ها نباید از قبل برای برنامه ثبت شده باشند؛ محصولات غیرفعال نیز در این بررسی لحاظ می‌شوند.
• همهٔ محصولات باید شرایط جدول فیلدها را داشته باشند. عضو null در آرایه پذیرفته نمی‌شود.
• این سرویس برای ایجاد محصولات جدید است. برای تغییر محصول موجود، از سرویس ویرایش محصول استفاده کنید.

اعتبار اطلاعات محصولات و تکراری‌نبودن شناسه‌ها پیش از درج SKUها بررسی می‌شود. اگر حتی یک محصول نامعتبر باشد یا با محصول موجود تداخل داشته باشد، کل درخواست رد می‌شود و هیچ‌یک از محصولات جدید آن درخواست ثبت نمی‌شوند.

برای مثال، اگر از ۱۰ محصول ارسالی، شناسهٔ محصول آخر از قبل ثبت شده باشد، ۹ محصول دیگر نیز ایجاد نمی‌شوند.

پاسخ موفق

در صورت ایجاد موفق محصولات، سرویس وضعیت 200 OK و پیام موفقیت برمی‌گرداند. برای مشاهدهٔ محصولات ثبت‌شده، می‌توانید از سرویس دریافت فهرست محصولات استفاده کنید:

GET https://developer.myket.ir/api/partners/applications/{PACKAGE_NAME}/products

خطاهای احتمالی

وضعیت HTTP	کد خطا	علت
400	SkuListIsRequired	لیست محصولات خالی است
400	SkuBatchLimitExceeded	بیش از ۲۰۰ محصول ارسال شده است
400	SkuIdIsDuplicate	شناسه‌ای در آرایه تکراری است یا از قبل برای برنامه ثبت شده است
400	SkuIdIsRequired	شناسهٔ محصول ارسال نشده یا خالی است
400	SkuIdMaxLengthExceeded	شناسهٔ محصول بیشتر از ۱۰۰ کاراکتر است
400	SkuTitleIsRequired	عنوان فارسی ارسال نشده یا خالی است
400	SkuTitleMaxLengthExceeded	عنوان فارسی بیشتر از ۱۵۰ کاراکتر است
400	SkuPriceMinValueNotReached	قیمت کمتر از ۱۰۰۰ ریال است یا ارسال نشده است
400	SkuPriceMaxValueExceeded	قیمت بیشتر از ۲ میلیارد ریال است
400	InValidSkuFormat	اطلاعات محصول معتبر نیست؛ برای مثال، یک عضو آرایه null است
401	—	توکن معتبر نیست یا به برنامهٔ موردنظر دسترسی ندارد
500	—	خطای داخلی هنگام پردازش درخواست رخ داده است

بدنهٔ غیر JSON یا ساختار ناسازگار با آرایهٔ محصولات نیز با خطای 400 پاسخ داده می‌شود.

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

ویرایش محصول

برای ویرایش محصول، شناسهٔ آن را در مسیر قرار دهید و فقط فیلدهایی را که قصد تغییرشان را دارید در بدنه بفرستید:

cURL

curl --request PUT \
  'https://developer.myket.ir/api/partners/applications/{PACKAGE_NAME}/products/{SKU_ID}' \
  --header 'X-Access-Token: {ACCESS_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
    "farsiTitle": "صد طلا",
    "price": 20000,
    "isActive": true
  }'

Python

import requests

package_name = "org.example.app"
sku_id = "100GOLD2000"
url = (
    f"https://developer.myket.ir/api/partners/applications/{package_name}"
    f"/products/{sku_id}"
)
headers = {"X-Access-Token": "YOUR_ACCESS_TOKEN"}
payload = {
    "farsiTitle": "صد طلا",
    "price": 20000,
    "isActive": True,
}

response = requests.put(url, headers=headers, json=payload)
print(response.status_code, response.json())

فیلدهای محصول

فیلد	توضیح
skuId	شناسهٔ یکتای محصول؛ هنگام ایجاد اجباری و حداکثر ۱۰۰ کاراکتر
farsiTitle	عنوان فارسی؛ هنگام ایجاد اجباری و حداکثر ۱۵۰ کاراکتر
price	قیمت به ریال؛ هنگام ایجاد اجباری و حداقل ۱۰۰۰ ریال
isActive	فعال یا غیرفعال بودن محصول؛ مقدار پیش‌فرض هنگام ایجاد false است

در پاسخ موفق، API کد 200 و پیام موفقیت برمی‌گرداند. توکن یا نام پکیج نامعتبر می‌تواند باعث خطای 401 Unauthorized شود. درخواست نامعتبر، شناسهٔ تکراری یا مقادیر خارج از محدودیت‌ها نیز با خطا پاسخ داده می‌شود.