معرفی

به مستندات API کینگارو خوش آمدید. این راهنما به شما کمک می‌کند تا با API ما یکپارچه شوید و برنامه‌های فوق‌العاده بسازید. API کینگارو از اصول RESTful پیروی می‌کند و پاسخ‌های JSON برمی‌گرداند. تمام درخواست‌ها باید شامل هدرهای احراز هویت مناسب باشند. ما فروشگاهمون تحویل محصولاتش به صورت آنی است.

احراز هویت

تمام درخواست‌های API نیاز به احراز هویت با استفاده از توکن دارند. توکن خود را در هدر X-API-Token قرار دهید:

درخواست

X-API-Token: YOUR_API_TOKEN

آدرس پایه

تمام نقاط دسترسی API نسبت به آدرس پایه زیر هستند:

https://kingaro.com/api/v1/

GET /products

دریافت لیست محصولات با قابلیت صفحه‌بندی.

GET

/api/v1/products/

پارامترها

پارامتر	نوع	اجباری	توضیحات
`page`	integer	خیر	شماره صفحه برای صفحه‌بندی (پیش‌فرض: 1)
`per_page`	integer	خیر	تعداد محصولات در هر صفحه (پیش‌فرض: 20)

مثال درخواست

cURL

curl -X GET "https://kingaro.com/api/v1/products/?page=1&per_page=20" \
  -H "X-API-Token: YOUR_API_TOKEN"

const axios = require('axios');

const response = await axios.get('https://kingaro.com/api/v1/products/', {
  params: {
    page: 1,
    per_page: 20
  },
  headers: {
    'X-API-Token': 'YOUR_API_TOKEN'
  }
});

console.log(response.data);

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://kingaro.com/api/v1/products/?page=1&per_page=20');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Token: YOUR_API_TOKEN'
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
?>

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Token' => 'YOUR_API_TOKEN'
])->get('https://kingaro.com/api/v1/products/', [
    'page' => 1,
    'per_page' => 20
]);

$data = $response->json();

import requests

url = 'https://kingaro.com/api/v1/products/'
headers = {
    'X-API-Token': 'YOUR_API_TOKEN'
}
params = {
    'page': 1,
    'per_page': 20
}

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

$response = wp_remote_get('https://kingaro.com/api/v1/products/', [
    'headers' => [
        'X-API-Token' => 'YOUR_API_TOKEN'
    ],
    'body' => [
        'page' => 1,
        'per_page' => 20
    ]
]);

$data = json_decode(wp_remote_retrieve_body($response), true);

مثال پاسخ

پاسخ

{
  "success": true,
  "data": [
    {
      "id": 123,
      "name": "بازی Grand Theft Auto VI",
      "name_en": "Grand Theft Auto VI",
      "slug": "grand-theft-auto-vi",
      "price": 1500000,
      "stock": 45
    },
    {
      "id": 124,
      "name": "بازی Call of Duty: Modern Warfare III",
      "name_en": "Call of Duty: Modern Warfare III",
      "slug": "call-of-duty-modern-warfare-iii",
      "price": 2200000,
      "stock": 32
    },
    {
      "id": 125,
      "name": "بازی FIFA 26",
      "name_en": "FIFA 26",
      "slug": "fifa-26",
      "price": 1800000,
      "stock": 0
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total": 156,
    "last_page": 8
  }
}

GET /products/search

جستجوی محصولات بر اساس کلمه کلیدی.

GET

/api/v1/products/search/

پارامترها

پارامتر	نوع	اجباری	توضیحات
`q`	string	بله	کلمه کلیدی برای جستجو
`page`	integer	خیر	شماره صفحه

مثال درخواست

cURL

curl -X GET "https://kingaro.com/api/v1/products/search/?q=بازی" \
  -H "X-API-Token: YOUR_API_TOKEN"

const axios = require('axios');

const response = await axios.get('https://kingaro.com/api/v1/products/search/', {
  params: { q: 'بازی' },
  headers: { 'X-API-Token': 'YOUR_API_TOKEN' }
});

console.log(response.data);

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://kingaro.com/api/v1/products/search/?q=بازی');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Token: YOUR_API_TOKEN']);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
?>

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Token' => 'YOUR_API_TOKEN'
])->get('https://kingaro.com/api/v1/products/search/', [
    'q' => 'بازی'
]);

$data = $response->json();

import requests

url = 'https://kingaro.com/api/v1/products/search/'
headers = { 'X-API-Token': 'YOUR_API_TOKEN' }
params = { 'q': 'بازی' }

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

$response = wp_remote_get('https://kingaro.com/api/v1/products/search/', [
    'headers' => [
        'X-API-Token' => 'YOUR_API_TOKEN'
    ],
    'body' => [
        'q' => 'بازی'
    ]
]);

$data = json_decode(wp_remote_retrieve_body($response), true);

مثال پاسخ

پاسخ

{
  "success": true,
  "data": [
    {
      "id": 123,
      "name": "بازی Grand Theft Auto VI",
      "name_en": "Grand Theft Auto VI",
      "slug": "grand-theft-auto-vi",
      "price": 1500000,
      "stock": 45
    },
    {
      "id": 456,
      "name": "بازی GTA VI",
      "name_en": "GTA VI",
      "slug": "gta-vi",
      "price": 1500000,
      "stock": 12
    }
  ],
  "count": 2
}

GET /products/{id}

دریافت اطلاعات یک محصول خاص با استفاده از ID.

GET

/api/v1/products/{id}/

مثال درخواست

cURL

curl -X GET "https://kingaro.com/api/v1/products/1/" \
  -H "X-API-Token: YOUR_API_TOKEN"

const axios = require('axios');

const response = await axios.get('https://kingaro.com/api/v1/products/1/', {
  headers: { 'X-API-Token': 'YOUR_API_TOKEN' }
});

console.log(response.data);

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://kingaro.com/api/v1/products/1/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Token: YOUR_API_TOKEN']);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
?>

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Token' => 'YOUR_API_TOKEN'
])->get('https://kingaro.com/api/v1/products/1/');

$data = $response->json();

import requests

url = 'https://kingaro.com/api/v1/products/1/'
headers = { 'X-API-Token': 'YOUR_API_TOKEN' }

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

$response = wp_remote_get('https://kingaro.com/api/v1/products/1/', [
    'headers' => [
        'X-API-Token' => 'YOUR_API_TOKEN'
    ]
]);

$data = json_decode(wp_remote_retrieve_body($response), true);

مثال پاسخ

پاسخ

{
  "success": true,
  "data": {
    "id": 123,
    "name": "بازی Grand Theft Auto VI",
    "name_en": "Grand Theft Auto VI",
    "slug": "grand-theft-auto-vi",
    "description": "بازی Grand Theft Auto VI جدیدترین نسخه از سری محبوب GTA است که در شهر Vice City جریان دارد.",
    "image_v": "https://kingaro.com/files/123456/248_v_product.jpg",
    "image_h": "https://kingaro.com/files/123456/320_h_product.jpg",
    "approved": true,
    "allow_instant_delivery": true,
    "offers": [
      {
        "price_id": 501,
        "price": 1500000,
        "stock": 25,
        "is_available": true,
        "price_avs": [
          {
            "attribute_id": 1,
            "attribute_name": "پلتفرم",
            "attribute_value_id": 10,
            "attribute_value_name": "استیم",
            "attribute_value_name_en": "Steam"
          },
          {
            "attribute_id": 2,
            "attribute_name": "نوع",
            "attribute_value_id": 20,
            "attribute_value_name": "اکانت",
            "attribute_value_name_en": "Account"
          }
        ],
        "provider_title": "Steam Account",
        "description": "اکانت استیم با بازی GTA VI",
        "discount": 0
      },
      {
        "price_id": 502,
        "price": 1800000,
        "stock": 20,
        "is_available": true,
        "price_avs": [
          {
            "attribute_id": 1,
            "attribute_name": "پلتفرم",
            "attribute_value_id": 11,
            "attribute_value_name": "اپیک گیمز",
            "attribute_value_name_en": "Epic Games"
          },
          {
            "attribute_id": 2,
            "attribute_name": "نوع",
            "attribute_value_id": 20,
            "attribute_value_name": "اکانت",
            "attribute_value_name_en": "Account"
          }
        ],
        "provider_title": "Epic Games Account",
        "description": "اکانت اپیک گیمز با بازی GTA VI",
        "discount": 10
      }
    ]
  }
}

GET /products/{id}/stock

استعلام موجودی یک محصول.

GET

/api/v1/products/{id}/stock/

مثال درخواست

cURL

curl -X GET "https://kingaro.com/api/v1/products/1/stock/" \
  -H "X-API-Token: YOUR_API_TOKEN"

const axios = require('axios');

const response = await axios.get('https://kingaro.com/api/v1/products/1/stock/', {
  headers: { 'X-API-Token': 'YOUR_API_TOKEN' }
});

console.log(response.data);

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://kingaro.com/api/v1/products/1/stock/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Token: YOUR_API_TOKEN']);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
?>

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Token' => 'YOUR_API_TOKEN'
])->get('https://kingaro.com/api/v1/products/1/stock/');

$data = $response->json();

import requests

url = 'https://kingaro.com/api/v1/products/1/stock/'
headers = { 'X-API-Token': 'YOUR_API_TOKEN' }

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

$response = wp_remote_get('https://kingaro.com/api/v1/products/1/stock/', [
    'headers' => [
        'X-API-Token' => 'YOUR_API_TOKEN'
    ]
]);

$data = json_decode(wp_remote_retrieve_body($response), true);

مثال پاسخ

پاسخ

{
  "success": true,
  "data": {
    "product_id": 123,
    "product_name": "بازی Grand Theft Auto VI",
    "stock": [
      {
        "price_id": 501,
        "inventory_count": 25,
        "is_available": true,
        "price": 1500000
      },
      {
        "price_id": 502,
        "inventory_count": 20,
        "is_available": true,
        "price": 1800000
      },
      {
        "price_id": 503,
        "inventory_count": 0,
        "is_available": false,
        "price": 2200000
      }
    ]
  }
}

POST /orders

ثبت سفارش جدید.

POST

/api/v1/orders/

بدنه درخواست

JSON

{
  "product_id": 1,
  "quantity": 2,
  "customer_name": "نام مشتری",
  "customer_phone": "09123456789"
}

مثال درخواست

cURL

curl -X POST "https://kingaro.com/api/v1/orders/" \
  -H "X-API-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 1,
    "quantity": 2,
    "customer_name": "نام مشتری",
    "customer_phone": "09123456789"
  }'

const axios = require('axios');

const response = await axios.post('https://kingaro.com/api/v1/orders/', {
  product_id: 1,
  quantity: 2,
  customer_name: 'نام مشتری',
  customer_phone: '09123456789'
}, {
  headers: {
    'X-API-Token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  }
});

console.log(response.data);

<?php
$data = [
    'product_id' => 1,
    'quantity' => 2,
    'customer_name' => 'نام مشتری',
    'customer_phone' => '09123456789'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://kingaro.com/api/v1/orders/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Token: YOUR_API_TOKEN',
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Token' => 'YOUR_API_TOKEN'
])->post('https://kingaro.com/api/v1/orders/', [
    'product_id' => 1,
    'quantity' => 2,
    'customer_name' => 'نام مشتری',
    'customer_phone' => '09123456789'
]);

$data = $response->json();

import requests

url = 'https://kingaro.com/api/v1/orders/'
headers = {
    'X-API-Token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'product_id': 1,
    'quantity': 2,
    'customer_name': 'نام مشتری',
    'customer_phone': '09123456789'
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

$data = [
    'product_id' => 1,
    'price_id' => 501,
    'quantity' => 2,
    'customer_name' => 'نام مشتری',
    'customer_phone' => '09123456789'
];

$response = wp_remote_post('https://kingaro.com/api/v1/orders/', [
    'headers' => [
        'X-API-Token' => 'YOUR_API_TOKEN',
        'Content-Type' => 'application/json'
    ],
    'body' => json_encode($data)
]);

$result = json_decode(wp_remote_retrieve_body($response), true);

مثال پاسخ

پاسخ

{
  "success": true,
  "message": "سفارش با موفقیت ثبت شد",
  "data": {
    "order_id": 78901,
    "order_token": "ord_abc123def456ghi789",
    "status": "pending",
    "total_price": 3000000
  }
}

GET /orders/{order_id}

دریافت نتیجه ثبت سفارش با استفاده از شماره سفارش.

GET

/api/v1/orders/{order_id}/

مثال درخواست

cURL

curl -X GET "https://kingaro.com/api/v1/orders/12345/" \
  -H "X-API-Token: YOUR_API_TOKEN"

const axios = require('axios');

const response = await axios.get('https://kingaro.com/api/v1/orders/12345/', {
  headers: { 'X-API-Token': 'YOUR_API_TOKEN' }
});

console.log(response.data);

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://kingaro.com/api/v1/orders/12345/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Token: YOUR_API_TOKEN']);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
?>

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Token' => 'YOUR_API_TOKEN'
])->get('https://kingaro.com/api/v1/orders/12345/');

$data = $response->json();

import requests

url = 'https://kingaro.com/api/v1/orders/12345/'
headers = { 'X-API-Token': 'YOUR_API_TOKEN' }

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

$response = wp_remote_get('https://kingaro.com/api/v1/orders/12345/', [
    'headers' => [
        'X-API-Token' => 'YOUR_API_TOKEN'
    ]
]);

$data = json_decode(wp_remote_retrieve_body($response), true);

مثال پاسخ

پاسخ

{
  "success": true,
  "data": {
    "order_id": 78901,
    "order_token": "ord_abc123def456ghi789",
    "status": "paid",
    "status_text": "پرداخت شده",
    "price": 3000000,
    "is_paid": true,
    "is_delivered": false,
    "lines": [
      {
        "id": 101,
        "product_id": 123,
        "product_name": "بازی Grand Theft Auto VI",
        "quantity": 2,
        "status": "pending"
      }
    ],
    "created_at": "2024-12-20T14:15:00",
    "updated_at": "2024-12-20T14:25:00"
  }
}

GET /seller/balance

دریافت موجودی حساب فروشنده.

GET

/api/v1/seller/balance/

مثال درخواست

cURL

curl -X GET "https://kingaro.com/api/v1/seller/balance/" \
  -H "X-API-Token: YOUR_API_TOKEN"

const axios = require('axios');

const response = await axios.get('https://kingaro.com/api/v1/seller/balance/', {
  headers: { 'X-API-Token': 'YOUR_API_TOKEN' }
});

console.log(response.data);

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://kingaro.com/api/v1/seller/balance/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Token: YOUR_API_TOKEN']);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
?>

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Token' => 'YOUR_API_TOKEN'
])->get('https://kingaro.com/api/v1/seller/balance/');

$data = $response->json();

import requests

url = 'https://kingaro.com/api/v1/seller/balance/'
headers = { 'X-API-Token': 'YOUR_API_TOKEN' }

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

$response = wp_remote_get('https://kingaro.com/api/v1/seller/balance/', [
    'headers' => [
        'X-API-Token' => 'YOUR_API_TOKEN'
    ]
]);

$data = json_decode(wp_remote_retrieve_body($response), true);

مثال پاسخ

پاسخ

{
  "success": true,
  "data": {
    "balance": 5000000,
    "balance_formatted": "5,000,000 تومان",
    "currency": "IRR",
    "updated_at": "2024-12-20T14:15:00"
  }
}