สร้างออเดอร์

POST/api/v1/orders

สิทธิ์ที่ต้องใช้:orders:write

ซื้อสินค้าหนึ่งชิ้นแล้วจ่ายด้วยเงินในกระเป๋าของคุณ · cdkey (คีย์เกม) กับ account1 (บัญชีเกมใหม่ที่ยังไม่เคยใช้) ได้รับสินค้าทันทีในคำขอนี้ · ส่วน account2 (บัญชีมือสอง) จะได้รับสินค้าทีหลังทาง callback หรือด้วยการอ่านออเดอร์ซ้ำ เพราะต้องเข้าไปตรวจสอบบัญชีก่อนซื้อ ซึ่งใช้เวลานานเกินกว่าจะรอจบในคำขอเดียว คำขอนี้จึงแค่รับเรื่องเข้าคิวไว้ · ทุกคำตอบมี order_id ติดมาด้วย เก็บไว้เสมอเพราะเป็นทางเดียวที่จะกลับมาดูออเดอร์นี้ได้ · ถ้าคำขอ timeout หรือคุณไม่แน่ใจว่ามันสำเร็จ ให้ส่งคำขอเดิมซ้ำด้วย request_id เดิม ห้ามเปลี่ยนเป็นค่าใหม่

request_id เดิม = ได้คำตอบเดิม ไม่ใช่ซื้อรอบสอง

ยิงซ้ำด้วย request_id เดิม และเนื้อคำขอเหมือนเดิมทุกฟิลด์ ได้ 200 พร้อมออเดอร์เดิม ไม่มีการสั่งซื้อรอบสอง · ยิงซ้ำด้วย request_id เดิม แต่ type / product_id / item_id / expected_price ต่างจากเดิม ได้ 409 idempotency_conflict และออเดอร์เดิมไม่ถูกแตะเลยสักฟิลด์ · สี่ฟิลด์นั้นคือทั้งหมดที่เราเอามาเทียบว่าเป็นคำขอเดียวกันหรือไม่ ฟิลด์อื่นในเนื้อคำขอไม่มีผล · เมื่อคำตอบหลุดกลางทาง ให้ยิงคำขอเดิมซ้ำแบบไม่แก้อะไรเลย นั่นคือเหตุผลทั้งหมดที่ฟิลด์นี้มีอยู่ — ผลที่เป็นไปได้มีแค่สองอย่างคือได้ออเดอร์เดิมกลับมา หรือออเดอร์เพิ่งถูกสร้างเป็นครั้งแรก · การเปลี่ยน request_id เพื่อลองใหม่คือการสั่งซื้อครั้งที่สอง ซึ่งหมายถึงจ่ายเงินสองรอบเมื่อครั้งแรกสำเร็จไปแล้วจริง

คำถามว่าจ่ายไปแล้วเท่าไหร่ มีคำตอบอยู่ที่ charged ที่เดียว

รหัสข้อผิดพลาดตัวเดียวกันมาถึงคุณได้จากหลายจังหวะ และแต่ละจังหวะเงินเดินไปไม่เท่ากัน ส่วน HTTP status ก็ไม่ได้บอกเรื่องนี้เลย — price_changed ที่ตอบสด ๆ ตอนสั่งเกิดขึ้นก่อนแตะเงิน แต่รหัสเดียวกันบนออเดอร์ account2 ที่จบเป็น failed เกิดหลังจากที่เงินถูกกันไว้แล้ว ส่วน supplier_failed ของไอดีมือสองมักเกิดตั้งแต่ตอนตรวจสอบบัญชี ซึ่งอยู่ก่อนขั้นตัดเงินทั้งหมด · อย่าเดาจากรหัสหรือจากสถานะ ให้กระทบยอดจาก charged ของออเดอร์นั้นอย่างเดียว — ค่านี้เป็น null เมื่อออเดอร์ยังไม่มีบันทึกการหักเงิน และเป็นอ็อบเจกต์เมื่อมีแล้ว

queued ไม่ได้รับประกันเวลา และตัวเลขข้างล่างเป็นของทั้งระบบรวมกัน

เราซื้อไอดีมือสองให้ ทีละหนึ่งออเดอร์ เรียงตามลำดับที่เข้ามา และเป็นคิวเดียวที่ทุก reseller ใช้ร่วมกัน ไม่ได้ซื้อพร้อมกันหลายออเดอร์ · ปกติออเดอร์หนึ่งจะรู้ผลในเวลาราวสองนาที เพราะการตรวจสอบบัญชี ครั้งแรก ของแต่ละออเดอร์กินเวลานานกว่าที่หนึ่งรอบทำงานจะทำจบได้ · เพดานที่เกิดขึ้นจริงคือราว 24 ออเดอร์ต่อชั่วโมงของทั้งระบบรวมกัน ไม่ใช่ต่อ reseller หนึ่งราย และไม่ใช่ตัวเลขกรณีดีที่สุด · คิวไม่มีช่องแยกให้รายใครและไม่มีเพดานความยาว การยิง account2 เข้ามาพร้อมกันทีละมาก ๆ ทำให้ออเดอร์ของทุกคนรวมทั้งของคุณเองช้าลง · ออเดอร์ที่ตรวจหรือซื้อไม่สำเร็จจะถูกลองใหม่ให้โดยเว้นช่วงห่างขึ้นเรื่อย ๆ สูงสุด 5 ครั้ง แล้วจึงจบเป็น failed · นับเป็นครั้งเฉพาะตอนที่เราลงมือทำกับออเดอร์นั้นจริง ตอนที่ออเดอร์ยังไม่ถึงคิวไม่นับ ดังนั้นเลข 5 ครั้งนี้ไม่ใช่ตัวบอกว่าออเดอร์หนึ่งจะรออยู่ในคิวได้นานแค่ไหน

การปฏิเสธที่ด่านยืนยันตัวตนเกิดกับเอนด์พอยต์นี้ด้วย

ห้ารหัสของด่านยืนยันตัวตน — invalid_key (401) · key_revoked (401) · insufficient_scope (403) · quota_exceeded (429) · too_many_inflight (429) — เกิดได้กับทุกเอนด์พอยต์ รวมทั้งเอนด์พอยต์นี้ เพราะถูกโยนตั้งแต่ก่อนคำขอจะเดินไปถึงตรรกะของหน้านี้เลยสักบรรทัด (scope ที่ต้องมีคือค่าที่ประกาศไว้หัวหน้านี้) · แท็บคำตอบด้านบนจึงไล่เฉพาะสิ่งที่เอนด์พอยต์นี้เองตอบ ไม่ได้แปลว่าห้ารหัสนั้นเกิดที่นี่ไม่ได้ · รายละเอียดครบทุกตัวอยู่ที่ หน้าเอนด์พอยต์ตัวตนที่ /developers/access/me ที่เดียว ทั้ง HTTP status ของแต่ละตัว · ตัวไหนกินโควตารายวันบ้าง · header อะไรกลับมาบ้าง · และทำไม 429 สองตัวต้องรับมือคนละแบบ — จงใจไม่คัดลอกมาไว้ทุกหน้า เพราะสำเนาที่สองคือที่ที่ลืมแก้ตามในวันที่กติกาเปลี่ยน

ข้อมูลที่ต้องส่ง

Request body

ชื่อ	ชนิด	วิธีใช้
typeบังคับ	`cdkey` · `account1` · `account2`	ประเภทสินค้าที่กำลังจะซื้อ และเป็นฟิลด์เดียวที่ตัดสินว่าคุณจะได้ของเมื่อไหร่ รายละเอียดและข้อควรระวัง `cdkey` กับ `account1` ซื้อจบในคำขอนี้ จึงตอบ `201` (รู้ผลแล้ว) หรือ `202` (หักเงินแล้ว ของตามมาในไม่กี่วินาที) `account2` ต้องตรวจสอบบัญชีก่อนซื้อ จึงตอบ `202` พร้อม `status` เป็น `queued` เสมอ แล้วส่งของให้ทีหลัง และเป็นประเภทเดียวที่ต้องแนบ `item_id` มาด้วย ค่าอื่นนอกจากสามค่านี้ถูกปฏิเสธทันที ค่าสตริงทุกตัวในคำขอถูกตัดช่องว่างหัวท้ายก่อนตรวจ และค่าที่ว่างหลังตัดแล้วถือว่าไม่ได้ส่งมา
product_idบังคับ	สตริง ยาวไม่เกิน 200 ตัวอักษร ใช้ได้เฉพาะ `A-Z a-z 0-9 _ -`	รหัสสินค้าที่ได้จากแคตตาล็อก คือค่าในฟิลด์ `id` ของสินค้าชิ้นนั้น · รูปที่ผิดกฎถูกปฏิเสธด้วย `bad_request` ตั้งแต่ก่อนแตะฐานข้อมูล
item_idไม่บังคับ	รูปแบบเดียวกับ `product_id`	บังคับเฉพาะ `account2` และไม่ใช้กับประเภทอื่นเลย คือบัญชีมือสองหนึ่งชิ้นที่คุณเลือกมาจาก `GET /api/v1/products/{product_id}/items` รายละเอียดและข้อควรระวัง สินค้า `account2` หนึ่งรายการมีบัญชีขายอยู่หลายชิ้น ราคาและของที่มีจริงอยู่ที่ระดับชิ้น ไม่ใช่ระดับสินค้า คุณจึงต้องบอกมาด้วยว่าจะเอาชิ้นไหน ถ้าแนบมากับ `cdkey` หรือ `account1` เรา ไม่สนใจมันเฉย ๆ ไม่ได้ปฏิเสธคำขอ และมันไม่นับเป็นส่วนหนึ่งของการเทียบว่าเป็นคำขอเดิมหรือไม่ (ดูคำเตือนเรื่อง `request_id`)
expected_priceบังคับ	ตัวเลข หรือสตริงตัวเลข (ไม่เกิน 40 ตัวอักษร)	ราคา หน่วยบาท ที่คุณยอมจ่าย คัดลอกมาจากคำตอบของแคตตาล็อกสำหรับสินค้าหรือบัญชีชิ้นเดียวกันนี้ เซิร์ฟเวอร์คิดราคาใหม่เองทุกครั้งแล้วเทียบกับค่านี้แบบตรงตัว ไม่ตรงเมื่อไหร่ก็ปฏิเสธด้วย `price_changed` แทนที่จะคิดเงินคุณที่ราคาอื่น รายละเอียดและข้อควรระวัง มันคือสิ่งที่ผูก ราคาที่คุณประกาศกับผู้ซื้อของคุณ เข้ากับ ราคาที่ถูกตัดจริง ค่าที่ถูกต้องมาจาก `GET /api/v1/products/{product_id}` สำหรับ `cdkey` และ `account1` และมาจากรายการเดี่ยวที่เลือกไว้สำหรับ `account2` หน้ารายการสินค้าข้ามราคาขั้นต่ำ ราคาที่นั่นจึงต่ำกว่าที่ระบบยอมรับได้
request_idบังคับ	สตริง ยาวไม่เกิน 200 ตัวอักษร	กุญแจกันสั่งซ้ำที่คุณเป็นคนตั้งเอง ใช้ค่าที่ไม่ซ้ำต่อหนึ่งคำสั่งซื้อจริง (เช่น UUID) แล้วเก็บไว้ฝั่งคุณ ส่งค่าเดิมซ้ำแล้วจะได้ออเดอร์เดิมที่มีอยู่แล้วกลับมา ไม่ใช่การซื้อรอบสอง รายละเอียดและข้อควรระวัง ค่านี้ไม่มีวันหมดอายุ และผูกกับ คีย์ API ที่ใช้ยิง ไม่ใช่กับบัญชีของคุณ ค่าเดียวกันที่ยิงจากคนละคีย์จึงกลายเป็นคนละออเดอร์

Header

ชื่อ	ชนิด	วิธีใช้
Authorizationบังคับ	string	คีย์ของคุณในรูป `Bearer <คีย์>` ต้องส่งมาทุกคำขอ · คีย์ที่มีแต่ `orders:write` สั่งซื้อได้แต่ตามผลไม่ได้ ให้ขอ `orders:read` มาด้วยเสมอ
Content-Typeบังคับ	string	ต้องเป็น `application/json` เพราะ body ที่ประกาศเป็นชนิดอื่นจะถูกอ่านเป็นข้อความล้วนหรือเป็นฟอร์ม แล้วตกเป็น 400 `bad_request` ทั้งที่ตัว JSON เขียนถูกทุกตัวอักษร รายละเอียดและข้อควรระวัง ระวัง `curl -d` เป็นพิเศษ มันประกาศชนิดเป็นฟอร์มให้เองเมื่อไม่ได้สั่งเป็นอย่างอื่น

ข้อมูลที่ได้รับ

ชื่อ	ชนิด	วิธีใช้
order_id	สตริง หรือ `null`	รหัสออเดอร์ ขึ้นต้นด้วย `ord_` ตามด้วยเลขฐานสิบหก 24 ตัว รายละเอียดและข้อควรระวัง คำนวณจากคีย์คู่กับ `request_id` แบบตายตัว ยิงคำขอเดิมซ้ำจึงได้ค่าเดิมเสมอ เก็บค่านี้ไว้ เพราะเป็นทางเดียวที่จะกลับมาดูออเดอร์นี้ได้โดยตรง
status	สตริง หรือ `null`	สถานะของออเดอร์ตอนนี้ รายละเอียดและข้อควรระวัง `queued` = รับเรื่องแล้ว รอเราไปซื้อให้ (มีเฉพาะ `account2`) `processing` = กำลังดำเนินการ ของยังมาไม่ถึง `completed` = ได้ของแล้ว ให้อ่าน `delivery` `failed` = ไม่สำเร็จ ให้อ่าน `error.code` `refunded` = ออเดอร์นี้ถูกคืนเงินภายหลัง ห้าค่านี้คือค่าที่มีอยู่วันนี้ ไม่ใช่ชุดปิด ให้เผื่อสาขาสำหรับค่าที่ไม่รู้จักไว้เสมอ และห้ามตีความค่าที่ไม่รู้จักว่าสำเร็จหรือล้มเหลว ความหมายเต็มของแต่ละค่า รวมทั้งค่าที่ค้างถาวรได้ อยู่ที่หน้าอ่านออเดอร์รายตัว (`/developers/orders/get`)
type	สตริง หรือ `null`	ประเภทที่สั่งไว้ — เป็นตัวบอกว่า `delivery` จะมารูปไหน
product_id	สตริง หรือ `null`	รหัสสินค้าที่สั่ง
price	ตัวเลข หรือ `null`	ราคาที่ตกลงกันไว้ หน่วยบาท เท่ากับ `expected_price` ที่ส่งมา
charged	อ็อบเจกต์ หรือ `null`	`{ amount, currency }` คือยอดที่หักจากกระเป๋าจริง และเป็นคำตอบ เดียว ของคำถามว่าออเดอร์นี้จ่ายไปแล้วหรือยัง รายละเอียดและข้อควรระวัง เป็น `null` ตราบใดที่ออเดอร์ยังไม่มีบันทึกการหักเงิน และเป็นอ็อบเจกต์เมื่อมีแล้ว `currency` คือ สกุลเงินของกระเป๋าคุณ ส่วน `price` เป็นบาทเสมอ สองค่านี้จึงไม่เท่ากันเมื่อกระเป๋าไม่ใช่บาท อย่ากระทบยอดด้วยการเทียบสองฟิลด์นี้ตรง ๆ ค่านี้จะปรากฏก็ต่อเมื่อบันทึกได้ครบทั้งจำนวนและสกุล มีมาครึ่งเดียวถือว่ายังไม่มี
delivery	อ็อบเจกต์ หรือ `null`	ตัวสินค้าที่ส่งมอบ มีค่าเฉพาะตอน `status` เป็น `completed` และมาได้ สองรูปที่ไม่มีฟิลด์ร่วมกันเลยสักตัว คือ `cdkey` กับ `account1` ได้ `{ keys: [{ serial }] }` ส่วน `account2` ได้ `login`, `password`, `email`, `email_password` และ `extra` รายละเอียดและข้อควรระวัง ให้แยกด้วยฟิลด์ `type` ของออเดอร์ตัวเดียวกันนี้เท่านั้น ห้ามเดาจากเนื้อข้างใน เพราะแยกผิดทางจะอ่านได้ `undefined` ทั้งก้อน ซึ่งหน้าตาเหมือนของยังไม่มาเป๊ะ รายละเอียดของทั้งสองรูปเป็นรายฟิลด์อยู่ที่หน้าอ่านออเดอร์รายตัว (`/developers/orders/get`)
error	อ็อบเจกต์ หรือ `null`	สาเหตุที่ไม่สำเร็จ มีค่าเฉพาะตอน `status` เป็น `failed` โดยมี `{ code, message }` อยู่ข้างใน รายละเอียดและข้อควรระวัง `code` ต้องอ่านคู่กับ `charged` เสมอ เพราะรหัสตัวเดียวกันเดินมาถึงคุณได้จากหลายจังหวะ บางจังหวะเงินยังไม่ออก บางจังหวะออกไปแล้วและคืนกลับมา รหัสเป็นชุดเดียวกับตารางสถานะข้างล่าง
created_at	สตริง ISO 8601 (UTC) หรือ `null`	เวลาที่ออเดอร์ถูกสร้าง
updated_at	สตริง ISO 8601 (UTC) หรือ `null`	เวลาที่ออเดอร์ถูกแก้ครั้งล่าสุด

สถานะที่อาจได้รับ

สถานะ	รหัส	ความหมาย
200	—	ยิงซ้ำ — ได้ออเดอร์เดิมกลับไป ไม่ได้ซื้อใหม่ คุณส่งคำขอเดิมซ้ำทุกฟิลด์ (เช่นตอนคำตอบครั้งแรกหลุดกลางทาง) จึงได้ออเดอร์เดิมกลับไปตามสถานะล่าสุดของมัน ซึ่งในตัวอย่างนี้คือออเดอร์ `account2` ที่เราซื้อสำเร็จไปแล้วระหว่างนั้น รายละเอียดและข้อควรระวัง ไม่มีการสั่งซื้อรอบสองเกิดขึ้นเลย และ `order_id` เป็นค่าเดิมเสมอ
201	—	ซื้อจบในคำขอนี้ — รู้ผลแล้ว ไม่ต้องรออะไรต่อ สั่งซื้อเสร็จสิ้นแล้วตั้งแต่ในคำขอนี้ คุณจึงอ่านผลได้จากคำตอบนี้เลย ไม่ต้องรอ callback และไม่ต้องเรียกอ่านออเดอร์ซ้ำ รายละเอียดและข้อควรระวัง `status` จะเป็น `completed` (ได้ของแล้ว อ่าน `delivery`) หรือ `failed` (ไม่สำเร็จ อ่าน `error.code`) หรือ `refunded` มีเฉพาะ `cdkey` กับ `account1` เท่านั้นที่ตอบแบบนี้ได้ เพราะเป็นสองประเภทที่ส่งของได้ทันที
202	—	หักเงินแล้ว แต่ของยังมาไม่ถึง — ให้อ่านออเดอร์ซ้ำ ออเดอร์นี้มี `charged` แล้วแต่ `delivery` ยังเป็น `null` แปลว่าเราตัดเงินและสั่งของไปแล้ว แต่คีย์ยังส่งมาไม่ทันในคำขอนี้ ซึ่ง เป็นเรื่องปกติ ไม่ใช่ความผิดพลาด รายละเอียดและข้อควรระวัง สิ่งที่ต้องทำคือเรียก `GET /api/v1/orders/{order_id}` ซ้ำเป็นระยะจนกว่า `status` จะเป็น `completed` แล้วอ่าน `delivery` และ ห้ามสั่งใหม่ ⚠️ การอ่านซ้ำไม่ได้รับประกันว่าออเดอร์จะขยับ ออเดอร์ `cdkey`/`account1` ค้างอยู่ที่ `processing` แบบไม่ขยับเองอีกเลยได้ ทั้งที่คุณจ่ายเงินแล้วและของอาจถึงมือเราเรียบร้อยแล้ว เจอแบบนี้ให้ติดต่อเราพร้อม `order_id` เหมือนกับออเดอร์ที่ `completed` ทั้งที่ `delivery.keys` ว่าง และ ยังห้ามสั่งใหม่อยู่ดี เพราะการสั่งใหม่คือการจ่ายเงินรอบสอง
202	—	กระเป๋าที่ไม่ใช่เงินบาท — `price` เป็นบาท ส่วน `charged` เป็นสกุลของกระเป๋า สถานการณ์เดียวกับแถวข้างบน แต่ยกมาให้ดูสำหรับคนที่กระเป๋าไม่ได้ถือเงินบาท รายละเอียดและข้อควรระวัง `price` คือราคาที่ตกลงกันไว้ ซึ่งเป็นเงินบาทเสมอไม่ว่ากระเป๋าคุณจะเป็นสกุลไหน ส่วน `charged` คือยอดที่หักออกจากกระเป๋าจริง จึงเป็นสกุลของกระเป๋าคุณ ในตัวอย่างนี้ `price` เป็น 450 บาท และ `charged` เป็น 12.86 USD ซึ่งเป็นเงินก้อนเดียวกัน แค่คนละหน่วย ไม่ใช่การคิดเงินสองครั้งและไม่ใช่ส่วนต่าง เวลากระทบยอดให้ใช้ `charged` อย่างเดียว อย่าเอา `price` มาลบกับ `charged`
202	—	เข้าคิวแล้ว — เราจะไปซื้อไอดีมือสองให้ แล้วแจ้งผลทีหลัง `account2` ตอบแบบนี้เสมอ พร้อม `status` เป็น `queued` เพราะไอดีมือสองต้องถูกตรวจสอบบัญชีก่อนซื้อ (ล็อกอินเข้าไปดูว่าบัญชียังใช้ได้จริงไหม) ซึ่งใช้เวลานานเกินกว่าจะรอจบในคำขอเดียว รายละเอียดและข้อควรระวัง ฝั่งคุณไม่ต้องทำอะไรเพิ่มนอกจากเก็บ `order_id` ไว้แล้วรอผล จะรอด้วยการตั้ง callback ไว้ให้เราแจ้งเมื่อจบ (`/developers/webhooks/callback`) หรือเรียก `GET /api/v1/orders/{order_id}` ซ้ำเป็นระยะก็ได้ เมื่อ `status` เป็น `completed` ข้อมูลบัญชีจะอยู่ใน `delivery` การหักเงินของประเภทนี้เกิดตอนที่เราซื้อจริง ไม่ใช่ที่คำขอนี้ ให้ดู `charged` ของออเดอร์เป็นคำตอบเสมอ ห้ามสั่งใหม่ระหว่างรอ และอย่าออกแบบระบบฝั่งคุณให้ยืนรอคำตอบแบบ synchronous
400	bad_request	เนื้อคำขอไม่ผ่านการตรวจ แก้คำขอแล้วส่งใหม่ด้วย `request_id` เดิมได้เลย รายละเอียดและข้อควรระวัง `message` เปลี่ยนไปตามฟิลด์ที่ผิดและมีได้หลายแบบ เช่น `Request body must be a JSON object` `request_id is required` `type must be one of: cdkey, account1, account2` `product_id is required` `product_id has an invalid format` `item_id has an invalid format` `expected_price is required and must be a number` แยกเคสด้วย `code` เท่านั้น รหัส `unsupported_type` ใช้ชุดข้อความเดียวกันแต่ ไม่ได้มาจากการสั่งซื้อ มันมาจากเอนด์พอยต์รายการบัญชีมือสองเมื่อสินค้าชิ้นนั้นไม่ใช่ `account2` `bad_request` ยังไปโผล่เป็น `error.code` ของออเดอร์ที่จบเป็น `failed` ได้ด้วย ซึ่งคนละเรื่องกับ 400 ที่คุณเห็นสด ๆ ตรงนี้ ที่คุณเห็นตรงนี้คือคำขอถูกปฏิเสธตั้งแต่ยังไม่ทันสร้างออเดอร์ จึงไม่มีออเดอร์เกิดขึ้นเลย ส่วนที่ไปโผล่บนออเดอร์เป็นของ `account2` ที่เข้าคิวไปแล้วแต่ตอนเราไปซื้อจริงกลับติดปัญหาเรื่องข้อมูลของออเดอร์นั้น ให้ดู `charged` ของออเดอร์เป็นคำตอบว่าจ่ายไปหรือยังเสมอ ไม่ใช่ดูจากรหัส
409	idempotency_conflict	ใช้ `request_id` เดิมกับคำขอที่ต่างออกไป คุณใช้ `request_id` ค่าเดิมกับคำขอที่มีเนื้อหาต่างจากครั้งแรก รายละเอียดและข้อควรระวัง ออเดอร์เดิมไม่ถูกแตะเลยสักฟิลด์ ให้อ่านออเดอร์เดิมก่อน แล้วค่อยตัดสินใจว่าจะสั่งออเดอร์ใหม่ด้วย `request_id` ค่าใหม่หรือไม่ รหัสนี้ไม่ไปโผล่บนออเดอร์
404	product_not_found	ไม่มีสินค้ารหัสนั้น หรือปิดขายแล้ว ขอแคตตาล็อกใหม่แล้วเลือกสินค้าชิ้นอื่น · สินค้าที่ปิดขายกับสินค้าที่ไม่เคยมีตอบเหมือนกันหมดโดยเจตนา · รหัสนี้ไปโผล่เป็น `error.code` ของออเดอร์ที่จบเป็น `failed` ได้ด้วย
404	item_not_found	รายการ `account2` ที่เลือกไม่อยู่ในตลาดแล้ว บัญชีชิ้นที่คุณเลือกถูกคนอื่นซื้อไปแล้วหรือถูกถอดออกจากตลาดแล้ว ให้ดึงรายการบัญชีรายชิ้นใหม่แล้วเลือกชิ้นอื่น รายละเอียดและข้อควรระวัง รหัสนี้ไม่ไปโผล่บนออเดอร์ เพราะคำขอถูกปฏิเสธตั้งแต่ยังไม่ทันสร้างออเดอร์
409	price_changed	ราคาไม่ตรงกับที่คุณส่งมา ราคาใหม่แนบมาให้ใน `data` แล้ว รายละเอียดและข้อควรระวัง เอา `price` ที่ได้มาส่งเป็น `expected_price` ของคำสั่งซื้อครั้งใหม่ และครั้งใหม่นั้นต้องใช้ `request_id` ค่าใหม่ เพราะคนละราคาถือเป็นคนละคำสั่งซื้อ รหัสเดียวกันนี้ยังโผล่เป็น `error.code` บนออเดอร์ `account2` ที่จบเป็น `failed` ได้ด้วย ซึ่งเป็นคนละจังหวะกัน (ราคาขยับตอนที่เราไปซื้อจริงให้) ดู `charged` ของออเดอร์นั้นเป็นคำตอบว่าเงินเดินไปถึงไหน
409	out_of_stock	ของหมด หรือถูกคนอื่นซื้อตัดหน้าไป เลือกสินค้าชิ้นอื่น · รหัสนี้ไปโผล่เป็น `error.code` ของออเดอร์ที่จบเป็น `failed` ได้ด้วย
409	price_unavailable	สินค้าชิ้นนั้นคิดราคาให้ไม่ได้ สินค้ามีอยู่จริงแต่ขายผ่าน API ไม่ได้ ให้ข้ามไปก่อนแล้วแจ้งเรา อย่าลบออกจากแคตตาล็อกของคุณ แบบที่ทำกับ `product_not_found` รายละเอียดและข้อควรระวัง ถ้าเป็น `account2` ที่บัญชีชิ้นนั้นคิดราคาไม่ได้ จะได้ก้อนเดียวกันแต่ `message` เป็น `Item is not available through the API` รหัสนี้ไม่ไปโผล่บนออเดอร์ เพราะเราคิดราคาก่อนสร้างออเดอร์เสมอ ตอนที่ตอบรหัสนี้จึงยังไม่มีออเดอร์เกิดขึ้น
409	agreed_price_invalid	ราคาที่ส่งมาใช้ไม่ได้ตอนจะคิดเงิน ขอราคาใหม่จากแคตตาล็อกแล้วสั่งใหม่ด้วย `request_id` ค่าใหม่ รายละเอียดและข้อควรระวัง ประโยคใน `message` อธิบายกรณีที่พบบ่อยที่สุดของรหัสนี้ เมื่อรหัสเดียวกันมาถึงคุณในรูปของ `error.code` บนออเดอร์ที่จบไปแล้ว ให้ถือว่าฟิลด์ `charged` ของออเดอร์นั้นเป็นคำตอบ ไม่ใช่ประโยคนั้น
404	wallet_not_found	ไม่พบกระเป๋าเงินของบัญชีนี้ ติดต่อเรา · รหัสนี้ไปโผล่เป็น `error.code` ของออเดอร์ที่จบเป็น `failed` ได้ด้วย
400	insufficient_points	ยอดในกระเป๋าไม่พอสำหรับออเดอร์นี้ เติมเงินแล้วสั่งใหม่ รายละเอียดและข้อควรระวัง ยอดคงเหลือปัจจุบันอ่านได้จาก `GET /api/v1/me` รหัสนี้ยังโผล่เป็น `error.code` บนออเดอร์ `account2` ที่จบเป็น `failed` ได้ด้วย (ยอดพอตอนสั่ง แต่ไม่พอแล้วตอนที่เราไปซื้อจริง) ให้ดู `charged` ของออเดอร์นั้นประกอบเสมอ
400	unsupported_currency	สกุลเงินของกระเป๋าใช้กับรายการนี้ไม่ได้ ติดต่อเรา · รหัสนี้ไปโผล่เป็น `error.code` ของออเดอร์ที่จบเป็น `failed` ได้ด้วย
502	supplier_failed	เราสั่งของกับต้นทางให้ไม่สำเร็จ ตรวจ `charged` ของออเดอร์ก่อนตัดสินใจสั่งซ้ำเสมอ · รหัสนี้ไปโผล่เป็น `error.code` ของออเดอร์ที่จบเป็น `failed` ได้ด้วย และมาถึงคุณได้ทั้งจากจังหวะที่มีเงินขยับและจังหวะที่ไม่มีเลย
500	order_save_failed	ซื้อของให้แล้วแต่เราบันทึกไม่สำเร็จ — รหัสเดียวที่ห้ามยิงซ้ำ เราหักเงินและสั่งของให้เรียบร้อยแล้ว แต่ขั้นตอนบันทึกผลลงออเดอร์ล้มเหลว รายละเอียดและข้อควรระวัง นี่คือรหัสเดียวในหน้านี้ที่ห้ามยิงซ้ำเด็ดขาด แม้จะเป็น 5xx ก็ตาม client ที่ตั้งให้ retry ทุก 5xx อัตโนมัติจึงต้องมีข้อยกเว้นให้รหัสนี้ ทางออกทางเดียวคือติดต่อเราพร้อม `order_id` รหัสนี้ไปโผล่เป็น `error.code` ของออเดอร์ที่จบเป็น `failed` ได้ด้วย และกฎห้ามยิงซ้ำใช้กับทางนั้นเหมือนกันทุกตัวอักษร คำขอนี้ใช้เวลาได้ถึงระดับสิบวินาที คำตอบ 500 จึงหลุดกลางทางได้ แล้วคุณจะมาเจอรหัสเดียวกันอีกครั้งตอนอ่านออเดอร์หรือตอน callback มาถึง กันเฉพาะตอนเห็นรหัสนี้สด ๆ อย่างเดียวไม่พอ คนที่ทำแบบนั้นจะสั่งซ้ำให้กับออเดอร์ที่จ่ายเงินและได้ของไปแล้วจริง ๆ และออเดอร์กลุ่มนี้คือข้อยกเว้นเดียวที่ `charged` ตอบคำถามเรื่องยอดให้ไม่ได้ สิ่งที่พังคือขั้นตอนบันทึกเอง `charged` จึงเป็น `null` ได้ทั้งที่เงินออกไปแล้วและของถูกซื้อไปแล้ว (ประโยคใน `message` ของรหัสนี้บอกไว้ตรง ๆ) ให้ติดต่อเราพร้อม `order_id` แล้วรอคำตอบ อย่ากระทบยอดเองจากออเดอร์นี้
500	unknown	ปิดด้วยสาเหตุที่เราไม่ได้จัดหมวดไว้ หยุดไว้ก่อนแล้วให้คนดู รายละเอียดและข้อควรระวัง ออเดอร์อาจถูกสร้างไว้แล้ว ให้อ่านด้วย `GET /api/v1/orders/{order_id}` หรือถ้าคำนวณ `order_id` ไม่ได้ให้ค้นจากลิสต์ออเดอร์ แล้วดู `charged` ก่อนตัดสินใจทุกครั้ง รหัสนี้ไปโผล่เป็น `error.code` ของออเดอร์ได้ด้วย และเป็นค่าที่เราใช้เมื่อจัดหมวดสาเหตุไม่ได้ จึงไม่ได้แปลว่าไม่มีอะไรเกิดขึ้น และไม่ได้แปลว่าไม่เคยมีเงินขยับ `message` ที่มากับทุกรหัสเป็นข้อความภาษาอังกฤษที่เราเขียนเองทั้งชุด อย่าแยกเคสด้วยการเทียบข้อความ ให้แยกด้วย `code` เท่านั้น เพราะข้อความแก้ไขได้ตลอดโดยที่รหัสยังเหมือนเดิม รหัสที่ไม่อยู่ในตารางนี้เป็นไปได้เสมอในอนาคต ให้โค้ดฝั่งคุณจัดการรหัสที่ไม่รู้จักแบบเดียวกับ `unknown` ไม่ใช่ยิงซ้ำอัตโนมัติ

คำขอ

คำขอ · ซื้อคีย์เกม

curl -X POST "https://www.naxset.com/api/v1/orders" \
  -H "Authorization: Bearer $NAXSET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "b1b7f0c6-6f4b-4f56-9a53-1f0a2c5d7e01",
    "type": "cdkey",
    "product_id": "5f2c1a9e4b7d3c0812ab34cd",
    "expected_price": 450
  }'

คำขอ · ซื้อไอดีมือสอง

curl -X POST "https://www.naxset.com/api/v1/orders" \
  -H "Authorization: Bearer $NAXSET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "d24c9f31-8f0e-4a77-9c31-77d0be5a4b12",
    "type": "account2",
    "product_id": "7ab4c2d19e0f5b3a6c8d24ef",
    "item_id": "912345678",
    "expected_price": 1012
  }'

สถานะที่อาจได้รับ

ยิงซ้ำ — ได้ออเดอร์เดิมกลับไป ไม่ได้ซื้อใหม่

200

{
  "order_id": "ord_89abcdef0123456789abcdef",
  "status": "completed",
  "type": "account2",
  "product_id": "7ab4c2d19e0f5b3a6c8d24ef",
  "price": 1012,
  "charged": { "amount": 1012, "currency": "THB" },
  "delivery": {
    "login": "example_login",
    "password": "example-password",
    "email": "[email protected]",
    "email_password": "example-mail-password",
    "extra": {
      "item_id": "912345678",
      "steam_level": 12,
      "steam_game_count": 34,
      "steam_country": "TH"
    }
  },
  "error": null,
  "created_at": "2026-09-07T04:20:00.000Z",
  "updated_at": "2026-09-07T04:26:40.000Z"
}

ซื้อจบในคำขอนี้ — รู้ผลแล้ว ไม่ต้องรออะไรต่อ

201

{
  "order_id": "ord_0123456789abcdef01234567",
  "status": "completed",
  "type": "cdkey",
  "product_id": "5f2c1a9e4b7d3c0812ab34cd",
  "price": 450,
  "charged": { "amount": 450, "currency": "THB" },
  "delivery": { "keys": [{ "serial": "AAAAA-BBBBB-CCCCC" }] },
  "error": null,
  "created_at": "2026-09-07T04:15:02.000Z",
  "updated_at": "2026-09-07T04:15:11.000Z"
}

หักเงินแล้ว แต่ของยังมาไม่ถึง — ให้อ่านออเดอร์ซ้ำ

202

{
  "order_id": "ord_0123456789abcdef01234567",
  "status": "processing",
  "type": "cdkey",
  "product_id": "5f2c1a9e4b7d3c0812ab34cd",
  "price": 450,
  "charged": { "amount": 450, "currency": "THB" },
  "delivery": null,
  "error": null,
  "created_at": "2026-09-07T04:15:02.000Z",
  "updated_at": "2026-09-07T04:15:09.000Z"
}

กระเป๋าที่ไม่ใช่เงินบาท — price เป็นบาท ส่วน charged เป็นสกุลของกระเป๋า

202

{
  "order_id": "ord_0123456789abcdef01234567",
  "status": "processing",
  "type": "cdkey",
  "product_id": "5f2c1a9e4b7d3c0812ab34cd",
  "price": 450,
  "charged": { "amount": 12.86, "currency": "USD" },
  "delivery": null,
  "error": null,
  "created_at": "2026-09-07T04:15:02.000Z",
  "updated_at": "2026-09-07T04:15:09.000Z"
}

เข้าคิวแล้ว — เราจะไปซื้อไอดีมือสองให้ แล้วแจ้งผลทีหลัง

202

{
  "order_id": "ord_89abcdef0123456789abcdef",
  "status": "queued",
  "type": "account2",
  "product_id": "7ab4c2d19e0f5b3a6c8d24ef",
  "price": 1012,
  "charged": null,
  "delivery": null,
  "error": null,
  "created_at": "2026-09-07T04:20:00.000Z",
  "updated_at": "2026-09-07T04:20:00.000Z"
}

เนื้อคำขอไม่ผ่านการตรวจ

400 · bad_request

{
  "error": true,
  "url": "https://www.naxset.com/api/v1/orders",
  "statusCode": 400,
  "statusMessage": "Server Error",
  "message": "item_id is required for account2 orders",
  "data": { "code": "bad_request" }
}

ใช้ request_id เดิมกับคำขอที่ต่างออกไป

409 · idempotency_conflict

{
  "error": true,
  "url": "https://www.naxset.com/api/v1/orders",
  "statusCode": 409,
  "statusMessage": "Server Error",
  "message": "request_id was reused with different order parameters",
  "data": { "code": "idempotency_conflict" }
}

ไม่มีสินค้ารหัสนั้น หรือปิดขายแล้ว

404 · product_not_found

{
  "error": true,
  "url": "https://www.naxset.com/api/v1/orders",
  "statusCode": 404,
  "statusMessage": "Server Error",
  "message": "Product not found",
  "data": { "code": "product_not_found" }
}

รายการ account2 ที่เลือกไม่อยู่ในตลาดแล้ว

404 · item_not_found

{
  "error": true,
  "url": "https://www.naxset.com/api/v1/orders",
  "statusCode": 404,
  "statusMessage": "Server Error",
  "message": "Item not found in the market listing",
  "data": { "code": "item_not_found" }
}

ราคาไม่ตรงกับที่คุณส่งมา

409 · price_changed

{
  "error": true,
  "url": "https://www.naxset.com/api/v1/orders",
  "statusCode": 409,
  "statusMessage": "Server Error",
  "message": "Product price has changed since it was quoted",
  "data": {
    "code": "price_changed",
    "price": 470,
    "discount_percent": 6
  }
}

ของหมด หรือถูกคนอื่นซื้อตัดหน้าไป

409 · out_of_stock

{
  "error": true,
  "url": "https://www.naxset.com/api/v1/orders",
  "statusCode": 409,
  "statusMessage": "Server Error",
  "message": "Product is currently out of stock.",
  "data": { "code": "out_of_stock" }
}

สินค้าชิ้นนั้นคิดราคาให้ไม่ได้

409 · price_unavailable

{
  "error": true,
  "url": "https://www.naxset.com/api/v1/orders",
  "statusCode": 409,
  "statusMessage": "Server Error",
  "message": "Product is not available through the API",
  "data": { "code": "price_unavailable" }
}

ราคาที่ส่งมาใช้ไม่ได้ตอนจะคิดเงิน

409 · agreed_price_invalid

{
  "error": true,
  "url": "https://www.naxset.com/api/v1/orders",
  "statusCode": 409,
  "statusMessage": "Server Error",
  "message": "The agreed order price failed validation. No payment was taken.",
  "data": { "code": "agreed_price_invalid" }
}

ไม่พบกระเป๋าเงินของบัญชีนี้

404 · wallet_not_found

{
  "error": true,
  "url": "https://www.naxset.com/api/v1/orders",
  "statusCode": 404,
  "statusMessage": "Server Error",
  "message": "Wallet not found for this account.",
  "data": { "code": "wallet_not_found" }
}

ยอดในกระเป๋าไม่พอสำหรับออเดอร์นี้

400 · insufficient_points

{
  "error": true,
  "url": "https://www.naxset.com/api/v1/orders",
  "statusCode": 400,
  "statusMessage": "Server Error",
  "message": "Wallet balance is insufficient for this order.",
  "data": { "code": "insufficient_points" }
}

สกุลเงินของกระเป๋าใช้กับรายการนี้ไม่ได้

400 · unsupported_currency

{
  "error": true,
  "url": "https://www.naxset.com/api/v1/orders",
  "statusCode": 400,
  "statusMessage": "Server Error",
  "message": "Wallet currency is not supported.",
  "data": { "code": "unsupported_currency" }
}

เราสั่งของกับต้นทางให้ไม่สำเร็จ

502 · supplier_failed

{
  "error": true,
  "url": "https://www.naxset.com/api/v1/orders",
  "statusCode": 502,
  "statusMessage": "Server Error",
  "message": "The order could not be placed with our supplier. Check the charged field on this order to see whether any payment was taken and refunded.",
  "data": { "code": "supplier_failed" }
}

ซื้อของให้แล้วแต่เราบันทึกไม่สำเร็จ — รหัสเดียวที่ห้ามยิงซ้ำ

500 · order_save_failed

{
  "error": true,
  "url": "https://www.naxset.com/api/v1/orders",
  "statusCode": 500,
  "statusMessage": "Server Error",
  "message": "The wallet was charged and the order was placed, but recording it failed. Contact support before retrying — do not submit the same order again.",
  "data": { "code": "order_save_failed" }
}

ปิดด้วยสาเหตุที่เราไม่ได้จัดหมวดไว้

500 · unknown

{
  "error": true,
  "url": "https://www.naxset.com/api/v1/orders",
  "statusCode": 500,
  "statusMessage": "Server Error",
  "message": "The order could not be completed.",
  "data": { "code": "unknown" }
}

อัปเดตล่าสุด 2026-09-07