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

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

ตรวจที่อยู่ น้ำหนัก และ COD ตั้งแต่ต้นทาง

เริ่มจากตารางจับคู่ฟิลด์ระหว่าง POS/ERP กับระบบจัดส่ง ระบุชนิดข้อมูล หน่วย และผู้รับผิดชอบการแก้ไข โดยแยกค่าที่ไม่มีออกจากค่าศูนย์ให้ชัด

สำหรับ address validation ไทย ควรแยกการตรวจว่าข้อมูลครบออกจากการตรวจว่าข้อมูลสอดคล้องกัน การมีรหัสไปรษณีย์ครบจำนวนหลักยังไม่ยืนยันว่าเข้ากับพื้นที่ที่เลือก และการจับคู่พื้นที่ได้ก็ไม่ได้ยืนยันว่าบ้านเลขที่มีผู้รับจริง AdapterShip ออกแบบให้มีการตรวจสอบที่อยู่ แต่ขอบเขตข้อมูลและกฎตรวจจริงต้องตกลงก่อนพัฒนา

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

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

กำหนดสถานะกลางโดยรักษาความหมายเดิม

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

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

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

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

แยกร้านค้า บัญชี และผู้มีสิทธิ์ดำเนินงาน

ผู้ให้บริการ POS/ERP ที่ดูแลหลายร้านควรวาดความสัมพันธ์ระหว่างบัญชีผู้ให้บริการ ร้านค้า ผู้ใช้ และบัญชีขนส่งให้ชัด แนวทางของ AdapterShip กล่าวถึงบัญชีหลักและ sub-account แต่รูปแบบต้องสอดคล้องกับนโยบายขนส่งและตกลงก่อนให้บริการ จึงยังไม่ควรถือว่าบัญชีเดียวมีสิทธิ์สร้างรายการแทนทุกร้านโดยอัตโนมัติ

ผูกคำขอกับร้านและตรวจสิทธิ์ฝั่งระบบก่อนอ่านหรือสร้างข้อมูล อย่ากรองเฉพาะหน้าจอ ทดสอบด้วยผู้ใช้ต่างร้านให้ครอบคลุมพัสดุ ที่อยู่ และข้อมูลการชำระเงิน

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

กระทบยอด Wallet แยกจากการรับเงิน COD

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

ข้อมูลกระทบยอดควรเชื่อมร้านค้า ออเดอร์ พัสดุ และรายการเงินเข้าด้วยกัน พร้อมประเภทการเคลื่อนไหวและเลขอ้างอิง อย่าถือว่าสถานะพัสดุเป็นหลักฐานการชำระครบ

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

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

ทดสอบข้อผิดพลาดพร้อมทางให้ทีมตามงานต่อ

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

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

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

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

สรุป

  • ทำข้อตกลงข้อมูลที่อยู่ น้ำหนัก COD และสถานะให้ชัด พร้อมทดสอบค่าที่หาย ผิดหน่วย และยังจับคู่ไม่ได้
  • แยกสิทธิ์และรายการเงินตามร้านค้า โดยยืนยันรูปแบบ sub-account และเงื่อนไข Wallet ก่อนกำหนดกฎระบบ
  • ทดสอบรายการซ้ำ ผลที่ไม่แน่นอน และการกระทบยอดร่วมกับทีมใช้งานจริง โดยไม่ใช้ Preview เป็นหลักฐานความพร้อมของบริการ