ข้อมูลอ้างอิงชนิดข้อมูล

ข้อบกพร่องส่วนใหญ่ในการเชื่อมต่อ API นี้ไม่ใช่ข้อผิดพลาดเชิงตรรกะ แต่เป็นข้อผิดพลาดเรื่องรูปแบบข้อมูล หน้านี้รวบรวมทุกรูปแบบไว้ในที่เดียว

วันที่และเวลา

มีสามรูปแบบที่ใช้งาน และรูปแบบที่ต้องใช้ขึ้นอยู่กับกลุ่ม endpoint

สองความไม่สมมาตรที่ควรจดไว้ก่อนเริ่มงาน

1. รายการบัญชีรับเป็นสตริงวันที่แต่คืนเป็น Unix seconds ส่ง "2026-09-30" แล้วอ่านกลับได้ 1759190400
2. ฝั่งขายใช้สตริงวันที่ ฝั่งซื้อใช้ timestamp ทั้งสองเป็น endpoint ที่อยู่ข้างกัน แต่ใช้รูปแบบต่างกัน ฟังก์ชันช่วยจัดการวันที่ในไคลเอนต์ของคุณควรรับกลุ่ม endpoint เป็นพารามิเตอร์

timestamp เป็นหน่วย วินาที ไม่ใช่มิลลิวินาที ในภาษา JavaScript

// ตอนอ่าน response
const createdAt = new Date(body.createdAt * 1000);

// ตอนส่งวันที่ของเอกสารซื้อ ให้เป็นเที่ยงคืนตามโซนเวลาขององค์กร
const docDate = Math.floor(new Date("2026-09-08T00:00:00+07:00").getTime() / 1000);

วันที่ที่ไม่มีเวลากำกับจะถูกตีความตามโซนเวลาขององค์กร ให้อ่านค่าจากฟิลด์ timezone ของ GET /company องค์กรในกรุงเทพฯ จะเป็น Asia/Bangkok (UTC+7) ดังนั้นการสร้าง timestamp จากเที่ยงคืน UTC จะทำให้เอกสารไปลงวันก่อนหน้า

จำนวนเงิน

• เป็นตัวเลข JSON ธรรมดา ไม่ใช่สตริง เช่น 3210, 26750.5
• ทศนิยมสองตำแหน่งสำหรับสกุลบาท ไม่ควรส่งความละเอียดเกินกว่าที่สกุลเงินนั้นมี
• ไม่มีการใช้หน่วยย่อยแฝง ค่า 300 หมายถึง 300 บาท ไม่ใช่ 3.00 บาท
• currency / currencyCode เป็นรหัส ISO 4217 สามตัวอักษร (สามตัวพอดี) เอกสารขายที่ไม่ส่งค่านี้จะใช้สกุลเงินขององค์กร แต่เอกสารซื้อและรายการค่าใช้จ่ายบังคับต้องส่ง

ยอดรวมเป็นค่าที่ระบบคำนวณ ไม่ใช่ค่าที่รับเข้า ให้ส่ง quantity, unitPrice, ส่วนลด และ vatRate แล้วอ่าน subtotalAmount, vatAmount, grandTotal, outstandingAmount กลับมา อย่าคำนวณยอดฝั่งไคลเอนต์แล้วคาดว่าเซิร์ฟเวอร์จะได้ค่าเดียวกัน เพราะกฎการปัดเศษอยู่ฝั่งเซิร์ฟเวอร์

หากระบบของคุณเก็บจำนวนเงินเป็นชนิด decimal ให้แปลงเฉพาะตอนแปลงเป็น JSON และหลีกเลี่ยงการคำนวณด้วย floating point

รหัสอ้างอิง

• ฟิลด์ id ทุกตัวเป็นจำนวนเต็มบวก (unsigned 32-bit) ไม่ซ้ำภายในตารางของตนเอง แต่ไม่ได้ไม่ซ้ำข้ามตาราง — ผู้ติดต่อ 12 กับสินค้า 12 ไม่เกี่ยวข้องกัน
• id มีความหมายเฉพาะภายในองค์กรที่คีย์สังกัด ไม่มี id ที่ข้ามองค์กร
• เลขที่เอกสารไม่ใช่ id IV-2026-0001 คือ documentNumber ส่วน id คือ 41 พารามิเตอร์ใน path ต้องการ id เสมอ
• รหัสต่าง ๆ (CUST-001, WID-001, รหัสบัญชี 5810) เป็นค่าที่คนใช้อ้างอิงและคงที่ จึงเหมาะกับการกระทบยอดกับระบบของคุณ ส่วน id ควรเก็บควบคู่ไว้ใช้เรียก API

ค่า boolean

ใน body เป็น boolean ของ JSON จริง (true / false) แต่ใน query string เป็นสตริง true / false

?isActive=true&isDeleted=false

การไม่ส่งตัวกรอง boolean ไม่เท่ากับการส่ง false — การไม่ส่งหมายถึง "ค่าใดก็ได้"

สตริงและความยาวสูงสุด

การตรวจสอบใช้จำนวนตัวอักษร และค่าที่ยาวเกินจะได้ 400 ไม่ใช่การตัดข้อความให้เงียบ ๆ ค่าที่พบบ่อย

ข้อความเป็น UTF-8 ทั้งระบบ ภาษาไทยไม่ต้อง escape เพิ่ม แต่โปรดจำว่าสตริงภาษาไทยยาวกว่าเมื่อวัดเป็นไบต์ ให้นับเป็นตัวอักษรเหมือนที่ API นับ

ค่า enum

ค่า enum ใช้ตัวพิมพ์เล็กคั่นด้วยขีดล่าง (bank_transfer, head_office, personal_card) โดยมีข้อยกเว้นสองกลุ่ม กลุ่มแรกเป็น camelCase เพราะอธิบายการจัดการภาษีของสินค้า (vatExclusive, vatInclusive, zeroVat, noVat, nonInventory) และอีกกลุ่มเป็นตัวพิมพ์ใหญ่ทั้งหมด (accountType: ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE)

รหัสชนิดเอกสารเป็นตัวพิมพ์ใหญ่: QT, SO, IV, RE, CS, CN, DN, PR, PO, GR, PI, PV

ค่า enum ที่ระบบไม่รู้จักจะได้ 400 พร้อมชื่อฟิลด์ที่ผิดใน errorValidation ให้ยึดรายการในคู่มือนี้เป็นสัญญาการใช้งาน และกลับไปอ่านAPI Reference เมื่อพบค่าใหม่ เพราะการเพิ่มค่าใน enum ทำได้โดยไม่ต้องขึ้นเวอร์ชันใหม่ ไคลเอนต์ที่ล้มทันทีเมื่อพบค่าที่ไม่รู้จักจะพังก่อนไคลเอนต์ที่บันทึก log แล้วข้ามไป

ค่า null และฟิลด์ที่ไม่ปรากฏ

• null ใน response หมายถึง "ยังไม่ได้ตั้งค่า" ซึ่งไม่ใช่สิ่งเดียวกับสตริงว่าง และทั้งสองแบบเกิดขึ้นได้
• ใน PATCH การ ไม่ส่ง ฟิลด์จะคงค่าเดิม แต่การส่งค่าว่างจะล้างค่านั้น นี่คือความต่างที่ต้องระวังเมื่อซิงก์เฉพาะฟิลด์ที่เปลี่ยน
• pagination.previousPage และ pagination.nextPage เป็น null เมื่อถึงต้นหรือปลายช่วง
• ฟิลด์ที่ฝั่งเซิร์ฟเวอร์กำหนดเป็น omitempty จะหายไปจาก JSON ทั้งคีย์เมื่อไม่มีค่า ไม่ได้ปรากฏเป็น null จึงไม่ควรสมมติว่าคีย์นั้นมีอยู่ ให้เขียน body.items?.length ?? 0 ไม่ใช่ body.items.length

สรุปรูปแบบการห่อข้อมูลอีกครั้ง

ในหน้าข้อผิดพลาดและการแบ่งหน้า มีฟังก์ชัน unwrap ที่รองรับสองแบบแรกได้ โดยที่คุณไม่ต้องจำว่ากลุ่มไหนเป็นแบบไหน

ไปที่ไหนต่อ

• API Reference — ทุก path พารามิเตอร์ และโมเดล สร้างจากโค้ดที่ทำงานอยู่จริง
• รุ่นที่ปล่อยแล้ว — สิ่งที่เปลี่ยนในแต่ละรุ่น
• ประกาศ — ประกาศที่มีผลต่อระบบที่เชื่อมต่อ