1. معرفی

این API برای دریافت آخرین قیمت‌های بازار ParvazCoin استفاده می‌شود.
از طریق این API می‌توانید لیست قیمت همه آیتم‌ها یا قیمت یک آیتم مشخص را دریافت کنید.

تمام درخواست‌ها باید از طریق HTTPS ارسال شوند.

2. آدرس پایه

https://parvazcoin.com/api/v1/parvaz-prices.php

3. احراز هویت

برای استفاده از API، باید API Key اختصاصی خود را در Header درخواست ارسال کنید.

روش پیشنهادی

Authorization: Bearer YOUR_API_KEY

روش جایگزین

X-API-Key: YOUR_API_KEY

نمونه:

Authorization: Bearer customername_xxxxxxxxxxxxxxxxx

4. دریافت همه قیمت‌ها

Endpoint

GET https://parvazcoin.com/api/v1/parvaz-prices.php

Headers

Authorization: Bearer YOUR_API_KEY

نمونه درخواست با curl

curl -X GET “https://parvazcoin.com/api/v1/parvaz-prices.php” \

-H “Authorization: Bearer YOUR_API_KEY”

نمونه پاسخ موفق

{

  “success”: true,

  “service”: “ParvazCoin Market API”,

  “version”: “1.0”,

  “updated_at”: “2026-06-17T18:59:18+03:30”,

  “count”: 7,

  “data”: [

    {

      “id”: 2,

      “name”: “تمام سکه 86”,

      “buy_price”: 160350000,

      “sell_price”: 161850000,

      “base_price”: 161100000,

      “market_is_open”: true,

      “currency”: “IRT”

    },

    {

      “id”: 17,

      “name”: “گرم 18 عیار”,

      “buy_price”: 16110000,

      “sell_price”: 16161000,

      “base_price”: 16135000,

      “market_is_open”: true,

      “currency”: “IRT”

    }

  ]

}

5. دریافت قیمت یک آیتم مشخص

برای دریافت قیمت یک آیتم خاص، پارامتر id را به آدرس اضافه کنید.

Endpoint

GET https://parvazcoin.com/api/v1/parvaz-prices.php?id=17

Headers

Authorization: Bearer YOUR_API_KEY

نمونه درخواست با curl

curl -X GET “https://parvazcoin.com/api/v1/parvaz-prices.php?id=17” \

-H “Authorization: Bearer YOUR_API_KEY”

نمونه پاسخ موفق

{

  “success”: true,

  “service”: “ParvazCoin Market API”,

  “version”: “1.0”,

  “updated_at”: “2026-06-17T18:59:18+03:30”,

  “count”: 1,

  “data”: {

    “id”: 17,

    “name”: “گرم 18 عیار”,

    “buy_price”: 16110000,

    “sell_price”: 16161000,

    “base_price”: 16135000,

    “market_is_open”: true,

    “currency”: “IRT”

  }

}

6. توضیح فیلدهای پاسخ

فیلدهای داخل data

7. نکات مهم

قیمت‌ها لحظه‌ای هستند و ممکن است در هر به‌روزرسانی تغییر کنند.

برای ثبت معامله، همیشه باید آخرین قیمت را قبل از ارسال سفارش دریافت کنید.

اگر مقدار market_is_open  برابر false  باشد، بازار آن آیتم بسته است و نباید برای آن آیتم سفارش ارسال شود.

کلید API باید محرمانه نگهداری شود و نباید در سمت کاربر نهایی، مرورگر عمومی یا اپلیکیشن قابل مشاهده قرار گیرد.

ارسال API Key در Header توصیه می‌شود. قرار دادن API Key در URL پیشنهاد نمی‌شود.

8. خطاها

کلید نامعتبر یا ارسال‌نشده

کد وضعیت HTTP:

401 Unauthorized

نمونه پاسخ:

{

  “success”: false,

  “error”: {

    “code”: “unauthorized”,

    “message”: “Invalid API key.”

  }

}

آیتم پیدا نشد

کد وضعیت HTTP:

404 Not Found

نمونه پاسخ:

{

  “success”: false,

  “error”: {

    “code”: “item_not_found”,

    “message”: “Requested price item was not found.”

  }

}

اطلاعات قیمت در دسترس نیست

کد وضعیت HTTP:

503 Service Unavailable

نمونه پاسخ:

{

  “success”: false,

  “error”: {

    “code”: “prices_unavailable”,

    “message”: “Price data is not available yet.”

  }

}

خطای داخلی داده قیمت

کد وضعیت HTTP:

500 Internal Server Error

نمونه پاسخ:

{

  “success”: false,

  “error”: {

    “code”: “invalid_price_data”,

    “message”: “Stored price data is invalid.”

  }

}

9. نمونه استفاده در JavaScript

fetch(“https://parvazcoin.com/api/v1/parvaz-prices.php”, {

  method: “GET”,

  headers: {

    “Authorization”: “Bearer YOUR_API_KEY”

  }

})

  .then(response => response.json())

  .then(data => {

    console.log(data);

  })

  .catch(error => {

    console.error(“API Error:”, error);

  });

10. نمونه استفاده در PHP

<?php

$url = “https://parvazcoin.com/api/v1/parvaz-prices.php”;

$apiKey = “YOUR_API_KEY”;

$ch = curl_init($url);

curl_setopt_array($ch, [

    CURLOPT_RETURNTRANSFER => true,

    CURLOPT_HTTPHEADER => [

        “Authorization: Bearer ” . $apiKey

    ],

    CURLOPT_TIMEOUT => 20,

]);

$response = curl_exec($ch);

$error = curl_error($ch);

curl_close($ch);

if ($error) {

    echo “Curl Error: ” . $error;

    exit;

}

$data = json_decode($response, true);

print_r($data);

11. نمونه استفاده در Python

import requests

url = “https://parvazcoin.com/api/v1/parvaz-prices.php”

headers = {

    “Authorization”: “Bearer YOUR_API_KEY”

}

response = requests.get(url, headers=headers, timeout=20)

print(response.status_code)

print(response.json())

12. لیست Endpointها

13. ثبت درخواست

برای دریافت و پیگیری  API Key، درخواست خود را به ایمیل Email : api@parvazcoin.com ارسال نمائید.

1. معرفی

این API به صورت Server-to-Server طراحی شده است و باید فقط از سمت سرور مشتری فراخوانی شود.
استفاده مستقیم از این API در مرورگر، اپلیکیشن سمت کاربر نهایی یا کد JavaScript عمومی توصیه نمی‌شود، چون باعث افشای API Key خواهد شد.

قبل از ثبت هر سفارش، مشتری باید ابتدا آخرین قیمت‌ها را از API قیمت دریافت کند و مطمئن شود آیتم مورد نظر فعال است و بازار آن باز است.

2. آدرس ثبت سفارش

POST https://parvazcoin.com/api/v1/orders.php

3. احراز هویت

برای ثبت سفارش، مشتری باید API Key اختصاصی خود را در Header ارسال کند.

Authorization: Bearer YOUR_API_KEY

روش جایگزین

X-API-Key: YOUR_API_KEY

نمونه Headers

Authorization: Bearer customername_xxxxxxxxxxxxxxxxx

Content-Type: application/json

4. ثبت سفارش

Endpoint:

POST https://parvazcoin.com/api/v1/orders.php

Headers

Authorization: Bearer YOUR_API_KEY

Content-Type: application/json

Body:

{

  “client_order_id”: “order-1001”,

  “item_id”: 17,

  “side”: “buy”,

  “count”: 1

}

5. فیلدهای ورودی

6. قوانین فیلد Client_order _id

فیلد  client_order_id  باید توسط مشتری تولید شود و برای هر سفارش یکتا باشد.

باید اول نام آن با نام فروشگاه یا کسب و کار یکی باشد.

قوانین:

فرمت پیشنهادی

customer-YYYYMMDD-ORDERNUMBER

مثال

ali-20260617-000001

یا:

shopA-20260617-1001

7. جلوگیری از ثبت سفارش تکراری

اگر مشتری یک سفارش ارسال کرد و به هر دلیل پاسخ API را دریافت نکرد، نباید همان سفارش را با client_order_id  جدید دوباره ارسال کند.

روش درست:

الف) همان client_order_id  قبلی را نگه دارد.

ب) از API گزارش وضعیت سفارش، وضعیت همان سفارش را استعلام کند.

ج) فقط اگر مطمئن شد سفارش ثبت نشده، سفارش جدید ایجاد کند.

ارسال مجدد سفارش با client_order_id  جدید ممکن است باعث ثبت دوباره سفارش شود.

8. مقدار فیلد Side

فیلد side مشخص می‌کند مشتری قصد خرید دارد یا فروش.

9. منطق قیمت در سفارش

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

اگر Side = Buy

در صورتی که مشتری می‌خواهد از ParvazCoin خرید کند.

در این حالت سفارش با قیمت فروش ParvazCoin ثبت می‌شود:

fee = sell_price

اگر Side = Sell

در صورتی که مشتری می‌خواهد به ParvazCoin بفروشد.

در این حالت سفارش با قیمت خرید ParvazCoin ثبت می‌شود:

fee = buy_price

مشتری نباید مقدار fee  یا قیمت سفارش را در Body ارسال کند.
قیمت سفارش توسط سیستم ParvazCoin محاسبه و کنترل می‌شود.

10. اعتبار قیمت

سیستم قبل از ثبت سفارش بررسی می‌کند که آخرین قیمت ذخیره‌شده قدیمی نباشد.

اگر قیمت بیش از حد مجاز قدیمی باشد، سفارش ثبت نمی‌شود و خطای زیر برمی‌گردد:

{

  “success”: false,

  “error”: {

    “code”: “stale_price”,

    “message”: “Price data is too old. Please try again later.”

  },

  “price_age_seconds”: 861

}

در این حالت مشتری باید چند لحظه بعد دوباره قیمت جدید را دریافت کند و سپس سفارش را ثبت کند.

11. وضعیت بازار

اگر بازار آیتم مورد نظر بسته باشد، سفارش ثبت نمی‌شود.

نمونه خطا:

{

  “success”: false,

  “error”: {

    “code”: “market_closed”,

    “message”: “Market is closed for this item.”

  }

}

برای جلوگیری از این خطا، مشتری باید قبل از ثبت سفارش از API قیمت بررسی کند که فیلد زیر برای آیتم مورد نظر true باشد:

“market_is_open”: true

12. نمونه درخواست ثبت سفارش خرید

Request

POST https://parvazcoin.com/api/v1/orders.php

Authorization: Bearer ali_8f3a9c2d91

Content-Type: application/json

Body

{

  “client_order_id”: “ali-20260617-000001”,

  “item_id”: 17,

  “side”: “buy”,

  “count”: 1

}

معنی درخواست

در این مثال، مشتری با نام ali  درخواست خرید مقدار 1  از آیتم با شناسه 17  را ثبت می‌کند.

13. نمونه درخواست ثبت سفارش فروش

Request

POST https://parvazcoin.com/api/v1/orders.php

Authorization: Bearer ali_8f3a9c2d91

Content-Type: application/json

Body

{

  “client_order_id”: “ali-20260617-000002”,

  “item_id”: 17,

  “side”: “sell”,

  “count”: 1

}

معنی درخواست

در این مثال، مشتری با نام ali  درخواست فروش مقدار 1  از آیتم با شناسه 17  را ثبت می‌کند.

14. نمونه پاسخ موفق

{

  “success”: true,

  “message”: “درخواست 1 گرم گرم 18 عیار با مظنه 16,161,000 تومان ثبت شد”,

  “order”: {

    “client_order_id”: “ali-20260617-000001”,

    “server_order_id”: “PC-260617-4385380500”,

    “customer_name”: “ali”,

    “item_id”: 17,

    “name”: “گرم 18 عیار”,

    “side”: “buy”,

    “count”: 1,

    “buy_price”: 16110000,

    “sell_price”: 16161000,

    “fee”: 16161000,

    “fee_source”: “sell_price”,

    “order_type”: 0,

    “currency”: “IRT”,

    “price_age_seconds”: 3,

    “status”: “accepted”,

    “status_code”: 1,

    “provider_order_id”: “a56bb518-5e6a-f111-9a40-1402ec35ec5b”,

    “registered_at”: “2026-06-17T18:36:22.0152685+03:30”,

    “total_price”: 16161000

  }

}

15. فیلدهای پاسخ

16. فیلدهای داخل order

17. توضیح order_type

فیلد order_type  برای نمایش نوع سفارش در سیستم داخلی استفاده می‌شود.

18. توضیح fee_source

فیلد fee_source نشان می‌دهد قیمت سفارش از کدام قیمت گرفته شده است.

19. وضعیت های سفارش

20. سفارش Pending

اگر پاسخ سفارش دارای وضعیت زیر باشد:

“status”: “pending”,

“status_code”: 0

یعنی سفارش هنوز در صف بررسی است.

در این حالت مشتری باید حدود 10 تا 15 ثانیه بعد، وضعیت سفارش را از API گزارش وضعیت سفارش استعلام کند.

مشتری نباید بلافاصله همان سفارش را با client_order_id  جدید دوباره ثبت کند.

• سفارش Accepted

اگر پاسخ سفارش دارای وضعیت زیر باشد:

“status”: “accepted”,

“status_code”: 1

یعنی سفارش تایید شده و ثبت شده است.

22. سفارش Rejected

اگر پاسخ سفارش دارای وضعیت زیر باشد:

“status”: “rejected”,

“status_code”: 2

یعنی سفارش رد شده است.

در این حالت، علت رد سفارش معمولاً در فیلد message  برمی‌گردد.

نمونه:

{

  “success”: false,

  “message”: “درخواست رد شده است”,

  “order”: {

    “client_order_id”: “ali-20260617-000003”,

    “server_order_id”: “PC-260617-91ab82cd10”,

    “customer_name”: “ali”,

    “item_id”: 17,

    “name”: “گرم 18 عیار”,

    “side”: “buy”,

    “count”: 1,

    “fee”: 16161000,

    “status”: “rejected”,

    “status_code”: 2

  }

}

23. توضیح خطاها

23.1- متد اشتباه

اگر درخواست با متدی غیر از POST ارسال شود:

HTTP Status:

405 Method Not Allowed

Response:

{

  “success”: false,

  “error”: {

    “code”: “method_not_allowed”,

    “message”: “Only POST method is allowed.”

  }

}

23.2-کلید API  نامعتبر

HTTP Status:

401 Unauthorized

Response:

{

  “success”: false,

  “error”: {

    “code”: “unauthorized”,

    “message”: “Invalid API key.”

  }

}

23.3 – Json نامعتبر

HTTP Status:

400 Bad Request

Response:

{

  “success”: false,

  “error”: {

    “code”: “invalid_json”,

    “message”: “Invalid JSON body.”

  }

}

23.4- شناسه سفارش نامعتبر

HTTP Status:

400 Bad Request

Response:

{

  “success”: false,

  “error”: {

    “code”: “invalid_client_order_id”,

    “message”: “client_order_id is required and must contain only letters, numbers, underscore or dash.”

  }

}

23.5- شناسه آیتم

HTTP Status:

400 Bad Request

Response:

{

  “success”: false,

  “error”: {

    “code”: “invalid_item_id”,

    “message”: “item_id is required.”

  }

}

23.6- نوع سفارش نامعتبر

HTTP Status:

400 Bad Request

Response:

{

  “success”: false,

  “error”: {

    “code”: “invalid_side”,

    “message”: “side must be buy or sell.”

  }

}

23.7- مقدار سفارش نامعتبر

HTTP Status:

400 Bad Request

Response:

{

  “success”: false,

  “error”: {

    “code”: “invalid_count”,

    “message”: “count must be a positive number.”

  }

}

23.8- قیمت در دسترس نیست

HTTP Status:

503 Service Unavailable

Response:

{

  “success”: false,

  “error”: {

    “code”: “prices_unavailable”,

    “message”: “Price data is not available.”

  }

}

23.9- قیمت قدیمی است

HTTP Status:

503 Service Unavailable

Response:

{

  “success”: false,

  “error”: {

    “code”: “stale_price”,

    “message”: “Price data is too old. Please try again later.”

  },

  “price_age_seconds”: 861

}

23.10- اطلاعات قیمت نامعتبر است

HTTP Status:

500 Internal Server Error

Response:

{

  “success”: false,

  “error”: {

    “code”: “invalid_price_data”,

    “message”: “Stored price data is invalid.”

  }

}

23.11- آیتم پیدا نشد

HTTP Status:

404 Not Found

Response:

{

  “success”: false,

  “error”: {

    “code”: “item_not_found”,

    “message”: “Requested item was not found.”

  }

}

23.12- بازار بسته است

HTTP Status:

409 Conflict

Response:

{

  “success”: false,

  “error”: {

    “code”: “market_closed”,

    “message”: “Market is closed for this item.”

  }

}

23.13- قیمت معتبر برای سفارش وجود ندارد

HTTP Status:

409 Conflict

Response:

{

  “success”: false,

  “error”: {

    “code”: “invalid_fee”,

    “message”: “Selected item does not have a valid price for this side.”

  }

23.14- شناسه سفارش تکراری است

HTTP Status:

409 Conflict

Response:

{

  “success”: false,

  “error”: {

    “code”: “duplicate_client_order_id”,

    “message”: “This client_order_id has already been used.”

  },

  “client_order_id”: “ali-20260617-000001”

}

در این حالت مشتری نباید سفارش جدید بسازد.
باید وضعیت همین client_order_id  را از API گزارش وضعیت سفارش استعلام کند.

24. نمونه استفاده با Curl

curl -X POST “https://parvazcoin.com/api/v1/orders.php” \

  -H “Authorization: Bearer ali_8f3a9c2d91” \

  -H “Content-Type: application/json” \

  -d ‘{

    “client_order_id”: “ali-20260617-000001”,

    “item_id”: 17,

    “side”: “buy”,

    “count”: 1

  }’

25. نمونه استفاده در PHP

<?php

$url = “https://parvazcoin.com/api/v1/orders.php”;

$apiKey = “YOUR_API_KEY”;

$payload = [

    “client_order_id” => “ali-20260617-000001”,

    “item_id” => 17,

    “side” => “buy”,

    “count” => 1

];

$ch = curl_init($url);

curl_setopt_array($ch, [

    CURLOPT_POST => true,

    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),

    CURLOPT_HTTPHEADER => [

        “Authorization: Bearer ” . $apiKey,

        “Content-Type: application/json”

    ],

    CURLOPT_RETURNTRANSFER => true,

    CURLOPT_TIMEOUT => 40,

]);

$response = curl_exec($ch);

$error = curl_error($ch);

$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

curl_close($ch);

if ($error) {

    throw new Exception(“Curl Error: ” . $error);

}

$data = json_decode($response, true);

echo “HTTP Code: ” . $httpCode . PHP_EOL;

print_r($data);

26. نمونه استفاده در JavaScript سمت سرور

const response = await fetch(“https://parvazcoin.com/api/v1/orders.php”, {

  method: “POST”,

  headers: {

    “Authorization”: “Bearer YOUR_API_KEY”,

    “Content-Type”: “application/json”

  },

  body: JSON.stringify({

    client_order_id: “ali-20260617-000001”,

    item_id: 17,

    side: “buy”,

    count: 1

  })

});

const data = await response.json();

console.log(response.status);

console.log(data);

27. نمونه استفاده در Python

import requests

url = “https://parvazcoin.com/api/v1/orders.php”

headers = {

    “Authorization”: “Bearer YOUR_API_KEY”,

    “Content-Type”: “application/json”

}

payload = {

    “client_order_id”: “ali-20260617-000001”,

    “item_id”: 17,

    “side”: “buy”,

    “count”: 1

}

response = requests.post(url, json=payload, headers=headers, timeout=40)

print(response.status_code)

print(response.json())

28. راهنمای تست در Postman

Method

POST

URL

https://parvazcoin.com/api/v1/orders.php

Headers

Body

نوع Body را روی raw  و فرمت را روی JSON  قرار دهید.

{

  “client_order_id”: “postman-test-1001”,

  “item_id”: 17,

  “side”: “buy”,

  “count”: 1

}

برای هر تست جدید، مقدار client_order_id ب اید جدید باشد.

مثال:

postman-test-1001

postman-test-1002

postman-test-1003

29. ترتیب پیشنهادی پیاده سازی سمت مشتری
    • دریافت آخرین قیمت‌ها از API قیمت
    • انتخاب آیتم مورد نظر بر اساس item_id
    • بررسی market_is_open
    • ساخت client_order_id یکتا
    • ارسال سفارش به API ثبت سفارش
    • بررسی فیلد success
    • بررسی فیلدهای status و status_code
    • اگر سفارش pending بود، بعد از 10 تا 15 ثانیه وضعیت سفارش استعلام شود
    • اگر سفارش accepted بود، سفارش نهایی تلقی شود
    • اگر سفارش rejected بود، پیام خطا یا علت رد بررسی شود

30. نکات امنیتی

API Key  باید محرمانه بماند.

API Key  نباید در کد سمت مرورگر، اپلیکیشن عمومی یا URL قرار گیرد.

تمام درخواست‌ها باید از طریق HTTPS ارسال شوند.

برای هر مشتری باید API Key جداگانه صادر شود.

در صورت افشای API Key، باید کلید قبلی غیرفعال و کلید جدید صادر شود.

31. جمع بندی

برای ثبت سفارش، مشتری باید درخواست POST  به آدرس زیر ارسال کند:

POST https://parvazcoin.com/api/v1/orders.php

با Header:

Authorization: Bearer YOUR_API_KEY

Content-Type: application/json

و Body:

{

  “client_order_id”: “unique-order-id”,

  “item_id”: 17,

  “side”: “buy”,

  “count”: 1

}

موفق بودن سفارش فقط با فیلد success  مشخص نمی‌شود.
مشتری باید همیشه فیلدهای زیر را نیز بررسی کند:

“status”: “accepted”,

“status_code”: 1

اگر status_code  برابر صفر  بود، سفارش در وضعیت pending است و باید از API گزارش وضعیت سفارش استعلام شود.