06.03 Request Payload

---

📌 At a Glance

รายการ	รายละเอียด
Topic	Request Payload
Endpoint	POST /order-checkings
Method	POST
Authentication	API Key
Difficulty	⭐⭐⭐ Intermediate
Reading Time	12 นาที
Target	Developer

---

🎯 Learning Objectives

หลังจากศึกษาหัวข้อนี้แล้ว ผู้อ่านจะสามารถ

• เข้าใจโครงสร้าง Request Payload ของ Order Checking API
• ระบุ Required Fields และ Optional Fields ได้
• อ้างอิงข้อมูลจาก Master Data APIs ได้ถูกต้อง
• เตรียม JSON Payload สำหรับเรียก API ได้อย่างถูกต้อง

---

Overview

Order Checking API รับข้อมูลในรูปแบบ JSON Request Payload

Payload ถูกออกแบบให้เรียบง่าย ประกอบด้วยข้อมูลระดับเอกสาร และรายการสินค้า โดยอ้างอิงข้อมูลจาก Master Data APIs ที่ได้ Synchronize ไว้ก่อนหน้า

ก่อนเรียกใช้งาน API ควรตรวจสอบว่าได้ Synchronize

• Products API
• Units API
• Receivers API

เรียบร้อยแล้ว

---

Figure 6-3 Request Payload Structure

Figure 6-3 แสดงโครงสร้าง Request Payload ของ Create Order Checking API และความสัมพันธ์ระหว่างข้อมูลระดับเอกสารกับรายการสินค้า

---

Complete Request Example

✅ Production Example (SISAHYGO API v1.1)

{
  "client_reference_no": "{{client_reference_no}}",
  "customer_rec_id": 1657281,
  "remark": "ทดสอบ API",
  "items": [
    {
      "product_id": 6639,
      "unit_id": 10,
      "amount": 300,
      "remark": "100 แผ่น",
      "client_line_id": "985421",
      "client_item_no": "ITEM001",
      "client_product_code": "FG001"
    }
  ]
}

---

Payload Structure

Order Checking Request

│

├── client_reference_no

├── customer_rec_id

├── remark

└── items[]

        │

        ├── product_id

        ├── unit_id

        ├── amount

        ├── remark

        ├── client_line_id

        ├── client_item_no

        └── client_product_code

---

Top-level Fields

Field	Type	Required	Description
client_reference_no	String	✅	เลขอ้างอิงจาก Client System ต้องไม่ซ้ำกัน
customer_rec_id	Integer	✅	รหัสผู้รับสินค้า
remark	String	Optional	หมายเหตุของรายการ
items	Array	✅	รายการสินค้า อย่างน้อย 1 รายการ

---

Item Fields

Field	Type	Required	Description
product_id	Integer	✅	รหัสสินค้า
unit_id	Integer	✅	รหัสหน่วยนับ
amount	Decimal	✅	จำนวนสินค้า
remark	String	Optional	หมายเหตุของรายการสินค้า
client_line_id	String	Optional	เลขอ้างอิงรายการจาก Client
client_item_no	String	Optional	รหัสรายการสินค้าในระบบลูกค้า
client_product_code	String	Optional	รหัสสินค้าของลูกค้า

---

Master Data References

Request Payload มีการอ้างอิงข้อมูลจาก Master Data ดังนี้

Request Field	Source API	Description
customer_rec_id	GET /receivers	รหัสผู้รับสินค้า
product_id	GET /products	รหัสสินค้า
unit_id	GET /units	รหัสหน่วยนับ

---

Required Fields

Fields ที่ระบบต้องได้รับทุกครั้ง

client_reference_no

customer_rec_id

items[]

items.product_id

items.unit_id

items.amount

หากข้อมูลเหล่านี้ไม่ครบ ระบบจะไม่สามารถสร้าง Order Checking ได้

---

Business Rules

• หนึ่ง Request สามารถสร้างได้หนึ่ง Order Checking
• ภายใน Request สามารถมีรายการสินค้าได้หลายรายการ
• client_reference_no ต้องไม่ซ้ำกันในระบบของลูกค้า
• product_id ต้องอ้างอิงจาก Products API
• unit_id ต้องอ้างอิงจาก Units API
• customer_rec_id ต้องอ้างอิงจาก Receivers API

---

Design Principles

Request Payload ถูกออกแบบตามหลักการดังต่อไปนี้

• Simple JSON Structure
• Business-oriented Design
• Extensible สำหรับการเพิ่มฟิลด์ในอนาคต
• Backward Compatible
• รองรับหลายรายการสินค้าในหนึ่ง Order

---

Implementation Notes

• ใช้ UTF-8 Encoding
• ส่งข้อมูลในรูปแบบ JSON เท่านั้น
• ใช้ HTTP POST
• ใช้ HTTPS ทุกครั้ง
• กำหนด Header Content-Type: application/json
• กำหนด Header X-API-Key

---

Best Practices

• Validate Payload ฝั่ง Client ก่อนส่ง
• ตรวจสอบ Required Fields ทุกครั้ง
• ใช้ข้อมูลจาก Master Data APIs เท่านั้น
• ไม่ควรส่งรายการสินค้าที่ซ้ำกันภายใน Request เดียว
• เก็บ client_reference_no ไว้สำหรับตรวจสอบและอ้างอิงภายหลัง

---

Related APIs

• GET /products
• GET /units
• GET /receivers
• POST /order-checkings

---

Summary

Request Payload เป็นข้อมูลที่ Client System ใช้สร้าง Order Checking ใน SISAHYGO Integration Platform โดยประกอบด้วยข้อมูลระดับเอกสารและรายการสินค้า ซึ่งอ้างอิงจาก Master Data APIs ที่ Synchronize ไว้ก่อนหน้า การจัดเตรียม Payload ให้ถูกต้องตั้งแต่ต้นจะช่วยลด Validation Error และทำให้กระบวนการตรวจรับเป็นไปอย่างรวดเร็ว

---

Next Step

➡️ 06.04 Request Field Reference