สร้างคำสั่งซื้อ

สร้าง order ใหม่และระบบจะดำเนินการประมวลผลโดยอัตโนมัติ

Endpoint

POST /v1/orders

Authentication

ต้องส่ง X-API-Key header ทุก request — ดู Authentication

Request Body

{
    "reference_id": "ref_abc123",
    "user_id": "user_001",
    "server_id": "server_th01",
    "character_id": "char_123",
    "items": [
        {
            "sku": "DIAMOND_100",
            "quantity": 5
        }
    ]
}

Parameters

Field	Type	Required	Description
reference_id	string	✅	Reference ID จากระบบของ Merchant (ต้องไม่ซ้ำกัน)
user_id	string	✅	User ID ของลูกค้า (ผู้รับสินค้า)
items	array	✅	รายการสินค้าที่ต้องการสั่งซื้อ (อย่างน้อย 1 รายการ)
server_id	string	❌	Server ID ของเกม (ถ้ามี)
character_id	string	❌	Character ID ของเกม (ถ้ามี)

Items Object

Field	Type	Required	Description
sku	string	✅	Product SKU ของสินค้า เช่น DIAMOND_100
quantity	integer	❌	จำนวนที่ต้องการ (default: 1, ขั้นต่ำ: 1)

reference_id

reference_id คือ ID จากระบบของ Merchant ใช้สำหรับ idempotency และการ query order ภายหลัง ต้องไม่ซ้ำกันในแต่ละ order

Response

200 — Order Created Successfully

{
    "order_number": "ord_abc123",
    "reference_id": "ref_abc123",
    "user_id": "user_001",
    "server_id": "server_th01",
    "character_id": "char_123",
    "status": "pending",
    "subtotal_amount": "500.00",
    "discount_amount": "0.00",
    "total_amount": "500.00",
    "source_type": "api",
    "created_by": {
        "id": 0,
        "name": "API"
    },
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "failure_code": null,
    "failure_message": null,
    "items": [
        {
            "sku": "DIAMOND_100",
            "quantity": 5,
            "completed_quantity": 0,
            "failed_quantity": 0,
            "status": "pending",
            "subtotal_amount": "500.00",
            "discount_amount": "0.00",
            "total_amount": "500.00",
            "failure_code": null,
            "failure_message": null
        }
    ]
}

Response Fields

Field	Type	Description
order_number	string	Order ID ที่ระบบ GameSO ออกให้
reference_id	string	Reference ID ที่ Merchant ส่งมา
status	string	สถานะ order: pending, processing, completed, failed
total_amount	string	ยอดรวมทั้งหมด (THB)
items	array	รายละเอียดแต่ละ item
items[].completed_quantity	integer	จำนวนที่เติมสำเร็จแล้ว
items[].failed_quantity	integer	จำนวนที่เติมล้มเหลว

Error Responses

400 — Bad Request

{
    "status": 400,
    "code": "BAD_REQUEST",
    "message": "reference_id is required"
}

401 — Unauthorized

{
    "status": 401,
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
}

503 — Insufficient Balance

{
    "status": 503,
    "code": "SERVICE_UNAVAILABLE",
    "message": "Insufficient wallet balance"
}

ยอดเงินไม่พอ

หากกระเป๋าเงินมียอดไม่เพียงพอ ระบบจะตอบกลับ 503 Service Unavailable order จะไม่ถูกสร้าง

ตัวอย่างการใช้งาน

cURL

curl -X POST https://api.gameso.io/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "reference_id": "POS-20250115-001",
    "user_id": "player_12345",
    "server_id": "TH01",
    "items": [
      { "sku": "DIAMOND_100", "quantity": 3 },
      { "sku": "DIAMOND_500", "quantity": 1 }
    ]
  }'

JavaScript

const response = await fetch("https://api.gameso.io/v1/orders", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.GAMESO_API_KEY,
    },
    body: JSON.stringify({
        reference_id: "POS-20250115-001",
        user_id: "player_12345",
        server_id: "TH01",
        items: [
            { sku: "DIAMOND_100", quantity: 3 },
            { sku: "DIAMOND_500", quantity: 1 },
        ],
    }),
});

const order = await response.json();
console.log("Order created:", order.order_number);
console.log("Status:", order.status);

Python

import requests
import os

response = requests.post(
    'https://api.gameso.io/v1/orders',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['GAMESO_API_KEY'],
    },
    json={
        'reference_id': 'POS-20250115-001',
        'user_id': 'player_12345',
        'server_id': 'TH01',
        'items': [
            {'sku': 'DIAMOND_100', 'quantity': 3},
            {'sku': 'DIAMOND_500', 'quantity': 1},
        ],
    }
)

order = response.json()
print(f"Order created: {order['order_number']}")
print(f"Status: {order['status']}")

PHP

<?php
$data = [
    'reference_id' => 'POS-20250115-001',
    'user_id'      => 'player_12345',
    'server_id'    => 'TH01',
    'items'        => [
        ['sku' => 'DIAMOND_100', 'quantity' => 3],
        ['sku' => 'DIAMOND_500', 'quantity' => 1],
    ],
];

$ch = curl_init('https://api.gameso.io/v1/orders');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($data),
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-API-Key: ' . getenv('GAMESO_API_KEY'),
    ],
]);

$response = json_decode(curl_exec($ch), true);
echo "Order: " . $response['order_number'];

หลังจากสร้าง Order

Order ที่สร้างใหม่จะมีสถานะ pending และระบบจะประมวลผลโดยอัตโนมัติ Merchant สามารถ:

1. ติดตามสถานะ — ใช้ GET /v1/orders/{reference_id} เพื่อดูสถานะล่าสุด
2. รับ Webhook — ตั้งค่า Webhook เพื่อรับการแจ้งเตือนเมื่อ order เสร็จ