API Reference
سفارشها
سفارش را از موجودی کیف پول ثبت کنید، تاریخچه را فیلتر کنید و اطلاعات تحویل نهایی را با شناسه عددی یا reference دریافت کنید.
POST
/api/v1/ordersثبت سفارش
قیمتهای فعلی را محاسبه، موجودی کیف پول را بررسی و سفارش را ثبت میکند. reference سفارشهای API با A شروع میشود.
پارامترها
5 مورد| نام | نوع | الزام | توضیحات |
|---|---|---|---|
products | array | الزامی | آرایه اقلام سفارش؛ حداقل یک محصول. |
products[].productId | number | الزامی | شناسه عددی محصول. |
products[].regionPropertyId | number | الزامی | شناسه پراپرتی قیمت از جزئیات محصول. |
products[].quantity | number | اختیاری | تعداد؛ مقدار پیشفرض ۱ است. |
requiredFields | object | اختیاری | فیلدهای الزامی هر محصول، با productId بهعنوان کلید. |
products- arrayالزامی
- آرایه اقلام سفارش؛ حداقل یک محصول.
products[].productId- numberالزامی
- شناسه عددی محصول.
products[].regionPropertyId- numberالزامی
- شناسه پراپرتی قیمت از جزئیات محصول.
products[].quantity- numberاختیاری
- تعداد؛ مقدار پیشفرض ۱ است.
requiredFields- objectاختیاری
- فیلدهای الزامی هر محصول، با productId بهعنوان کلید.
نمونه داده
Request bodyjson
{
"products": [
{
"productId": 123,
"regionPropertyId": 101,
"quantity": 1
}
],
"requiredFields": {
"123": [
{
"fieldId": 1,
"value": "customer@example.com"
}
]
}
}GET
/api/v1/ordersدریافت فهرست سفارشها
سفارشهای حساب API را از جدیدترین مورد با فیلتر، جستوجو و صفحهبندی برمیگرداند.
پارامترها
6 مورد| نام | نوع | الزام | توضیحات |
|---|---|---|---|
page | number | اختیاری | شماره صفحه؛ مقدار پیشفرض ۱ است. |
pageSize | number | اختیاری | تعداد سفارش در هر صفحه؛ مقدار پیشفرض ۱۰ است. |
status | string | اختیاری | فیلتر با یکی از وضعیتهای سفارش. |
dateFrom | string | اختیاری | تاریخ شروع با فرمت YYYY-MM-DD. |
dateTo | string | اختیاری | تاریخ پایان با فرمت YYYY-MM-DD؛ شامل کل روز. |
search | string | اختیاری | جستوجو در reference سفارش. |
page- numberاختیاری
- شماره صفحه؛ مقدار پیشفرض ۱ است.
pageSize- numberاختیاری
- تعداد سفارش در هر صفحه؛ مقدار پیشفرض ۱۰ است.
status- stringاختیاری
- فیلتر با یکی از وضعیتهای سفارش.
dateFrom- stringاختیاری
- تاریخ شروع با فرمت YYYY-MM-DD.
dateTo- stringاختیاری
- تاریخ پایان با فرمت YYYY-MM-DD؛ شامل کل روز.
search- stringاختیاری
- جستوجو در reference سفارش.
نمونه داده
Responsejson
{
"status": "success",
"code": 200,
"data": [
{
"id": 5678,
"reference": "A1234567",
"total": 490000,
"status": "COMPLETED",
"createdAt": "2026-07-24T08:30:00.000Z",
"items": [
{
"id": 9876,
"productId": 123,
"productName": "گیفت کارت استیم 10 دلاری",
"productImg": "https://gift30t.ir/products/steam.png",
"quantity": 1,
"totalAmount": 490000,
"fields": [
{
"name": "ایمیل",
"value": "customer@example.com"
}
]
}
]
}
],
"meta": {
"pagination": {
"total": 15,
"page": 1,
"pageSize": 10,
"totalPages": 2
}
}
}GET
/api/v1/orders/:idدریافت جزئیات سفارش
اطلاعات کامل سفارش، فیلدهای ثبتشده، تراکنش و داده تحویل هر آیتم را برمیگرداند.
پارامترها
1 مورد| نام | نوع | الزام | توضیحات |
|---|---|---|---|
id | number | string | الزامی | شناسه عددی orderId یا orderReference مانند A1234567. |
id- number | stringالزامی
- شناسه عددی orderId یا orderReference مانند A1234567.
نمونه داده
Responsejson
{
"status": "success",
"code": 200,
"data": {
"id": 5678,
"reference": "A1234567",
"total": 490000,
"status": "COMPLETED",
"createdAt": "2026-07-24T08:30:00.000Z",
"completedAt": "2026-07-24T08:32:10.000Z",
"items": [
{
"id": 9876,
"productId": 123,
"productName": "گیفت کارت استیم 10 دلاری",
"productImg": "https://gift30t.ir/products/steam.png",
"quantity": 1,
"totalAmount": 490000,
"fields": [
{
"name": "ایمیل",
"value": "customer@example.com"
}
],
"delivery": {
"voucherCode": "STEAM-XXXX-XXXX-XXXX",
"redeemGuide": "راهنمای فعالسازی"
}
}
],
"transaction": {
"trans_id": "API_A7654321",
"amount": 490000,
"status": "SUCCESS",
"createdAt": "2026-07-24T08:30:00.000Z"
}
}
}وضعیتهای سفارش
QUEUEDدر صف پردازش
ACTION_REQUIREDنیازمند اصلاح یا اقدام کاربر
PREPARINGدر حال آمادهسازی
PENDING_CONFIRMATIONدر انتظار تأیید
NEEDS_VERIFICATIONنیازمند تکمیل احراز هویت
COMPLETEDتکمیل شده
CANCELEDلغو شده
RETURNEDعودت شده
UNPAIDپرداخت نشده