v5 Dynamic Document API

API v5 แบบ dynamic สำหรับอ่าน/บันทึกข้อมูล SML โดยไม่ต้องสร้าง Java model class ตามโครงสร้าง table ทุกครั้ง

แนวคิดหลัก

• ใช้ JSON root items เหมือนกันทุก module
• รูปแบบ POST และ GET ต้องเป็น shape เดียวกัน
• field ที่ส่งเข้ามาจะถูกตรวจจาก schema จริงของฐานข้อมูล
• ถ้า field ไม่มีจริงใน table จะ error ทันที
• client ไม่สามารถระบุ table เองได้ ต้องใช้ module ที่ระบบ allowlist ไว้เท่านั้น

แยกประเภท API

v5 dynamic document แยกคู่มือเป็น 2 ฝั่งหลัก เพื่อไม่ให้สับสนระหว่างข้อมูลพื้นฐานกับเอกสาร transaction

Type	ใช้กับ	ตัวอย่าง module	ลักษณะข้อมูล
Master	ข้อมูลตั้งต้น/แฟ้มหลัก	ar.customer, ic.inventory	header/detail ไม่ซับซ้อน, key หลักมักเป็น code
Transaction	เอกสารเคลื่อนไหว	sale.invoice	มีหลาย table, มี trans_flag, detail, payment, shipment, hook หลังบันทึก

URL กลาง

POST /SMLJavaRESTService/v5/api/documents/{module}
GET  /SMLJavaRESTService/v5/api/documents/{module}/{key}

JSON Shape กลาง

{
  "items": [
    {
      "header": {},
      "details": []
    }
  ]
}

transaction module สามารถมี section เสริมได้ เช่น:

{
  "items": [
    {
      "header": {},
      "details": [],
      "shipment": {},
      "payment": {
        "detail": []
      }
    }
  ]
}

Header Request

Field	Description
GUID	ใช้ smlx
provider	provider code
databaseName	database เป้าหมาย
configFIleName	ชื่อ config file ตามระบบเดิม

Response Error

Field Name	Description	Example
success	false เมื่อ error	false
error	true เมื่อ error	true
code	error code	FIELD_NOT_FOUND
message	รายละเอียด error	Field not found: ar_customer.foo_bar

ตัวอย่าง field ไม่มีจริง

{
  "success": false,
  "error": true,
  "code": "FIELD_NOT_FOUND",
  "message": "Field not found: ar_customer.foo_bar"
}

Module Guides

• Master: ลูกหนี้
• Master: สินค้า
• Transaction: ใบขายสินค้า

หมายเหตุการใช้งาน

• Master module ควรมี rule น้อยกว่า transaction และไม่ควรมีผลต่อ stock/account โดยตรง
• Transaction module ต้องคุม trans_flag, trans_type, relation, payment, shipment และ hook หลังบันทึกผ่าน manifest
• field ที่เป็น read-only หรือ field คำนวณ เช่น cust_name, billing_status, value_balance ไม่ควรส่งใน POST
• แต่ละ item ถูกบันทึกใน DB transaction ของตัวเอง ถ้า section ใด error จะ rollback item นั้น