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

AdapterShip เป็นแนวคิดแพลตฟอร์มในสถานะ Preview ที่ออกแบบให้ใช้ REST API, MCP Server และ Dashboard บนแนวทางข้อมูลเดียวกัน รวมถึงการตรวจสอบที่อยู่และ Wallet บทความนี้อธิบายสิ่งที่ร้านค้าออนไลน์และนักพัฒนาอิสระควรเตรียมก่อนเชื่อมต่อ ส่วนตัวอย่างบนเว็บไซต์เป็นการจำลองในเบราว์เซอร์ ไม่ใช่การสร้างพัสดุผ่านระบบขนส่งจริง

ทำไมการเชื่อมต่อขนส่งแต่ละเจ้าจึงต่างกัน

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

ตัวอย่างสมมติ ขนส่ง A รับน้ำหนักเป็นกิโลกรัม ส่วนขนส่ง B รับเป็นกรัม พัสดุหนัก 1.5 กิโลกรัมจึงต้องส่งค่า 1.5 หรือ 1500 ตามข้อกำหนดของแต่ละฝั่ง ความต่างนี้ไม่ได้จบที่การคูณตัวเลข นักพัฒนายังต้องตัดสินใจว่าจะรับทศนิยมกี่ตำแหน่ง ตรวจค่าที่หายไปอย่างไร และแสดงหน่วยให้พนักงานเห็นตรงไหน ตัวอย่าง A/B/C ใช้แทนระบบที่ต่างกัน ไม่ใช่รายชื่อพันธมิตร

สถานะก็มีปัญหาคล้ายกัน คำตอบว่าได้รับคำขอแล้วอาจหมายถึงเพียงสร้างรายการสำเร็จ ยังไม่ใช่ขนส่งรับพัสดุ หากร้านนำไปแสดงว่าเริ่มจัดส่ง ลูกค้าและทีมแพ็กของจะเข้าใจคนละอย่าง การเชื่อมต่อจึงต้องตกลงความหมายของข้อมูล รวมถึงวิธีจัดการสถานะที่ไม่รู้จักตั้งแต่ต้น

API กลางควรทำข้อมูลให้ตรงกันตรงไหน

แนวคิด multi-carrier API ไทย คือให้ร้านส่งข้อมูลตามสัญญาข้อมูลกลาง แล้วให้ชั้นเชื่อมต่อรับผิดชอบความต่างของแต่ละขนส่ง AdapterShip ออกแบบให้มีการแปลงรูปแบบข้อมูล การตรวจสอบที่อยู่ และสถานะมาตรฐาน งานฝั่งร้านจึงควรเริ่มจากการจับคู่ข้อมูลออเดอร์กับฟิลด์กลางให้ชัด ก่อนคิดถึงการเปลี่ยนขนส่ง

ตัวอย่างคำขอสำหรับ POST /v1/shipments ตามเดโมใช้ carrier เลือกขนส่ง เก็บข้อมูลผู้รับใน to ระบุน้ำหนักด้วย weight_kg และยอดเก็บเงินปลายทางด้วย cod ชื่อที่สื่อหน่วยช่วยให้คนอ่านโค้ดตรวจความหมายได้ แต่ยังต้องตรวจชนิดข้อมูลและเงื่อนไขที่ยอมรับด้วย

{
  "carrier": "carrier_a",
  "to": {
    "name": "สมชาย ใจดี",
    "phone": "0812345678",
    "postcode": "30000"
  },
  "weight_kg": 1.5,
  "cod": 590
}

ข้อมูลข้างต้นเป็นตัวอย่างสมมติจากเดโม และย่อรายละเอียดที่อยู่เพื่ออธิบายโครงสร้าง จึงไม่ควรถือเป็นรายการฟิลด์ครบถ้วนสำหรับจัดส่งจริง นักพัฒนาต้องตรวจข้อกำหนดฉบับที่จะใช้ก่อนเชื่อมต่อ รวมถึงที่อยู่ต้นทางและปลายทาง ข้อมูลบังคับ และเงื่อนไขของบริการที่เลือก

ผลลัพธ์ตัวอย่างมีเลขพัสดุ TH0123456789 ค่า price_thb เท่ากับ 32 บาท และสถานะ created ทั้งเลขพัสดุและค่าจัดส่งเป็นข้อมูลจำลอง ตัวเลขไม่ได้คำนวณจากน้ำหนักหรือที่อยู่ที่กรอก ส่วน label_url ในเดโมเป็นค่าประกอบตัวอย่าง ไม่ใช่ใบปะหน้าจริง ลองตรวจรูปแบบได้ที่ API Playground สำหรับคำขอและผลลัพธ์จำลอง

แม้เปลี่ยนค่า carrier ในโครงสร้างเดียวกันได้ตามแนวคิด ก็ยังต้องตรวจว่าขนส่งที่เลือกยอมรับพัสดุและบริการนั้นหรือไม่ มาตรฐานกลางช่วยจัดระเบียบข้อมูล แต่ไม่ได้ยกเลิกข้อกำหนดเฉพาะของขนส่ง ร้านควรเก็บเหตุผลที่รายการถูกปฏิเสธให้ทีมดูแลเข้าใจได้ด้วย

เตรียมร้านให้พร้อมตั้งแต่พัสดุชิ้นแรก

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

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

Wallet ตามข้อเสนอใช้สำหรับชำระค่าขนส่งและค่าบริการล่วงหน้า ร้านจึงควรวางแผนวิธีดูยอดที่ใช้ได้และการติดตามรายการหักเงิน อย่านำยอด COD มารวมกับยอดคงเหลือเพื่อประเมินเงินพร้อมใช้ เพราะเป็นข้อมูลคนละประเภท รายละเอียดการหัก คืน หรือปรับยอดต้องยืนยันก่อนนำไปใช้กับบัญชีจริง

ตรวจ ข้อมูลแพ็กเกจและแนวทางการชำระเงิน ก่อนประเมินต้นทุน โดยเอกสารยังไม่ได้ระบุอัตราค่าบริการต่อรายการและราคา Business จึงไม่ควรใช้ค่าจัดส่งจำลองเป็นฐานคำนวณ

ตรวจความครบถ้วนก่อนเขียนงานเชื่อมต่อ

เลือกออเดอร์สมมติหนึ่งรายการ แล้วไล่ข้อมูลจากหน้าร้านไปถึงผลลัพธ์ที่พนักงานต้องเห็น เพื่อหาฟิลด์ที่ขาดและตกลงวิธีแปลงข้อมูล

  • ตรวจที่อยู่: แยกข้อมูลเท่าที่จำเป็น ตรวจความสอดคล้องของพื้นที่กับรหัสไปรษณีย์ และเปิดทางให้ผู้ใช้แก้ข้อมูลโดยเห็นค่าต้นฉบับ
  • ตรวจน้ำหนักและ COD: แสดงหน่วยในฟอร์ม กำหนดความต่างระหว่างค่าศูนย์กับค่าที่ยังไม่กรอก และห้ามเติมตัวเลขโดยเดา
  • ตรวจสถานะ: กำหนดข้อความที่ลูกค้าเห็นแยกจากรายละเอียดที่ทีมดูแลใช้ พร้อมทางออกเมื่อพบสถานะที่ยังจับคู่ไม่ได้
  • ตรวจคำขอซ้ำ: ตกลงวิธีอ้างอิงออเดอร์และตรวจผลเดิมก่อนส่งใหม่ เมื่อผู้ใช้กดซ้ำหรือการเชื่อมต่อขาดช่วง

รายการเหล่านี้เป็นข้อแนะนำสำหรับการออกแบบระบบร้านค้า ไม่ใช่การยืนยันว่า AdapterShip มีรายละเอียดการทำงานครบแล้ว หากดูแลหลายร้านหรือมีงานบัญชีร่วมด้วย ให้ใช้ เช็กลิสต์เชื่อมต่อ POS/ERP กับขนส่ง ช่วยกำหนดขอบเขตที่ละเอียดขึ้น และอ่าน แนวทางความร่วมมือและบัญชีร้านค้า ก่อนเลือกโครงสร้างบัญชี

ทดลองให้เห็นทั้งผลสำเร็จและจุดที่ต้องหยุด

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

ให้ทีมแพ็กของลองอ่านผลลัพธ์และตามรายการที่ยังไม่ทราบผลด้วย พร้อมเก็บเลขออเดอร์กับเลขพัสดุให้ค้นหาคู่กันได้

หากร้านรับคำสั่งผ่านบทสนทนา การใช้ผู้ช่วย AI เป็นอีกแนวทางหนึ่ง แต่ยังต้องตรวจข้อมูลชุดเดียวกัน อ่าน MCP Server กับการให้ AI สร้างรายการจัดส่ง เพื่อแยกหน้าที่ของผู้ช่วยออกจากการตรวจสอบฝั่งระบบ สำหรับออเดอร์ที่มีโครงสร้างแน่นอนอยู่แล้ว REST API เป็นทางเลือกที่ควบคุมลำดับงานได้ตรงไปตรงมา

สรุป

  • API ขนส่งกลางควรทำให้ชื่อฟิลด์ หน่วย และความหมายของสถานะตรงกัน โดยยังเคารพข้อกำหนดของแต่ละขนส่ง
  • เตรียมข้อมูลร้าน ผู้รับ น้ำหนัก COD และขั้นตอน Wallet ให้ชัด ก่อนเริ่มเชื่อมจากออเดอร์ตัวอย่างหนึ่งรายการ
  • ใช้ Preview เพื่อทำความเข้าใจแนวทาง แล้วตรวจข้อกำหนดบริการจริงและวิธีจัดการข้อผิดพลาดก่อนใช้งานกับลูกค้า