KabyTech + CargoWise: คู่มือเชื่อมต่อทางเทคนิคสำหรับตัวแทนขนส่งสินค้าไทย

CargoWise One เป็นระบบจัดการขนส่งสินค้าที่ใช้กันมากที่สุดในบรรดาตัวแทนขนส่งสินค้าไทยขนาดกลางถึงใหญ่ AWB Intelligence API ของ KabyTech ถูกออกแบบมาเพื่อส่งข้อมูล AWB ที่มีโครงสร้างเข้า CargoWise โดยตรง ไม่ต้องกรอกข้อมูลด้วยมือและลดข้อผิดพลาดในการประมวลผล คู่มือนี้แนะนำขั้นตอนการเชื่อมต่อทั้งหมด ตั้งแต่การสร้าง API key จนถึงท่อส่ง webhook สำหรับการใช้งานจริง

คู่มือนี้สมมติว่าคุณมี: บัญชี KabyTech ในแผน Professional ขึ้นไป, CargoWise One instance ที่มี eHub หรือ eAdapter access และความเข้าใจพื้นฐานเกี่ยวกับ webhook และ REST API หากการตั้งค่า CargoWise ของคุณใช้ middleware สำหรับการเชื่อมต่อจากบุคคลที่สาม (เช่น Chain.io หรือ Youredi) แนวคิดเหมือนกันแต่ขั้นตอนการกำหนดค่าเฉพาะจะแตกต่างกัน

1 สร้างข้อมูลรับรอง KabyTech API

เข้าสู่ระบบ Operations Portal ของ KabyTech ที่ portal.kabytech.ai ไปที่ Settings > API Keys > Create New Key ตั้งชื่อ key ให้สื่อความหมาย (เช่น "CargoWise Production") และเลือกขอบเขตต่อไปนี้:

• awb:parse — จำเป็น อนุญาตให้ส่งเอกสารเพื่อแยกวิเคราะห์
• awb:read — จำเป็น อนุญาตให้ดึงผลลัพธ์ที่แยกวิเคราะห์แล้ว
• webhook:manage — จำเป็น อนุญาตให้ลงทะเบียนและจัดการ webhook endpoint
• field-map:read — ไม่บังคับแต่แนะนำ อนุญาตให้ดึงการกำหนดค่าการแมปฟิลด์ผ่าน API

คัดลอก API key และ secret ตัว secret จะแสดงเพียงครั้งเดียว เก็บไว้ในระบบจัดการความลับขององค์กรคุณ — ไม่ใช่ใน spreadsheet หรืออีเมลที่ใช้ร่วมกัน

2 กำหนดค่า webhook endpoint

KabyTech ใช้ webhook เพื่อส่งข้อมูล AWB ที่แยกวิเคราะห์แล้วไปยังระบบของคุณแบบเรียลไทม์ เมื่อเอกสารถูกแยกวิเคราะห์ ผลลัพธ์ JSON ที่มีโครงสร้างจะถูก POST ไปยัง endpoint ที่คุณกำหนด สำหรับการเชื่อมต่อ CargoWise endpoint นี้มักเป็น:

• CargoWise eHub endpoint — หาก CargoWise instance ของคุณเปิดใช้ eHub คุณสามารถกำหนดค่า Universal Event ขาเข้าที่รับ webhook payload ของ KabyTech โดยตรง
• ชั้นแปลงข้อมูล middleware — บริการขนาดเล็ก (AWS Lambda, Azure Function หรือเซิร์ฟเวอร์เชื่อมต่อเฉพาะ) ที่รับ JSON payload ของ KabyTech แปลงเป็นรูปแบบ Universal XML ของ CargoWise แล้ว POST ไปยัง eAdapter

ตัวแทนขนส่งไทยส่วนใหญ่ใช้วิธี middleware เพราะให้การควบคุมมากขึ้นในการแมปฟิลด์และการจัดการข้อผิดพลาด นี่คือวิธีลงทะเบียน webhook ใน KabyTech:

POST https://api.kabytech.ai/v1/webhooks
Authorization: Bearer YOUR_API_KEY

{
  "url": "https://your-middleware.example.com/kabytech-webhook",
  "events": ["awb.parsed", "awb.validation_failed"],
  "secret": "your-webhook-signing-secret",
  "active": true
}

event awb.parsed จะทำงานเมื่อเอกสารถูกแยกวิเคราะห์สำเร็จ event awb.validation_failed จะทำงานเมื่อการแยกวิเคราะห์สำเร็จแต่การตรวจสอบข้ามตรวจพบความไม่สอดคล้อง (เช่น ยอดรวม RTD ไม่ตรงกับ PPD/COL) คุณควรจัดการทั้งสอง event — ความล้มเหลวในการตรวจสอบยังคงมีข้อมูลที่ดึงได้ แต่มีสัญญาณระบุว่าฟิลด์ใดต้องตรวจสอบ

3 แมปฟิลด์ KabyTech ไปยัง CargoWise

นี่คือขั้นตอนที่ละเอียดที่สุด JSON output ของ KabyTech ประกอบด้วยทั้ง 29 ส่วน FWB เป็น object ที่มีโครงสร้าง CargoWise คาดหวังข้อมูลในรูปแบบ Universal Shipment XML ตารางด้านล่างแมปฟิลด์สำคัญ:

ฟิลด์การขนส่งหลัก

• awb.prefix + awb.serial → Shipment/SubShipmentCollection/SubShipment/WaybillNumber
• routing.origin → Shipment/OrganizationAddressCollection[AddressType="ConsignorPickupDeliveryAddress"]/Port/Code
• routing.destination → Shipment/OrganizationAddressCollection[AddressType="ConsigneePickupDeliveryAddress"]/Port/Code
• flight_bookings[0].flight_number → Shipment/SubShipmentCollection/SubShipment/TransportLegCollection/TransportLeg/VoyageFlightNo
• flight_bookings[0].date → TransportLeg/EstimatedDeparture

ผู้ส่งและผู้รับสินค้า

• shipper.name → OrganizationAddressCollection[AddressType="ConsignorDocumentaryAddress"]/CompanyName
• shipper.address → .../Address1, .../Address2
• shipper.city → .../City
• shipper.country → .../Country/Code
• shipper.contact.phone → .../Phone
• shipper.contact.email → .../Email
• consignee.* → โครงสร้างเดียวกันด้วย AddressType="ConsigneeDocumentaryAddress"

Rate Description (RTD) ไปยัง charge line

• rate_description[n].pieces → PackingLineCollection/PackingLine/PackQty
• rate_description[n].rate_class → PackingLine/RateClass/Code
• rate_description[n].commodity_code → PackingLine/Commodity/Code
• rate_description[n].chargeable_weight → PackingLine/ChargeableWeight
• rate_description[n].rate → PackingLine/RateCharge
• rate_description[n].total → PackingLine/TotalCharge
• rate_description[n].nature_of_goods → PackingLine/GoodsDescription

ค่าใช้จ่ายและมูลค่า

• charge_declarations.prepaid_collect_indicator → Shipment/ChargeCollection/Charge/PrepaidCollectIndicator
• charge_declarations.declared_value_carriage → Shipment/DeclaredValueForCarriage
• charge_declarations.declared_value_customs → Shipment/DeclaredValueForCustoms
• prepaid_summary.weight_charge → ChargeCollection/Charge[ChargeType="WeightCharge"]/Amount
• other_charges[n].code + .amount → ChargeCollection/Charge[ChargeType="OtherCharge"]/ChargeCode + /Amount

การจัดการพิเศษและกฎระเบียบ

• special_handling_codes[] → Shipment/NoteCollection/Note[NoteType="SpecialHandling"]
• oci[n].country_code + oci[n].information_id + oci[n].data → Shipment/CustomsEntryCollection/CustomsEntry/CustomsReferenceCollection
• hts_codes[] → CustomsEntry/TariffCollection/Tariff/TariffCode
• agent.iata_code → Shipment/AgentReference

4 สร้างชั้นแปลงข้อมูล

บริการ middleware ต้องทำงาน 3 อย่าง:

งาน A: รับและตรวจสอบ webhook

เมื่อ KabyTech ส่ง webhook จะมี header X-KabyTech-Signature ที่ประกอบด้วย HMAC-SHA256 signature ของ request body ที่ลงนามด้วย webhook secret ของคุณ ตรวจสอบ signature นี้ทุกครั้งก่อนประมวลผล payload เพื่อป้องกัน request ปลอมจากการสร้างการขนส่งใน CargoWise instance ของคุณ

งาน B: แปลง JSON เป็น Universal XML

แมปฟิลด์ JSON ของ KabyTech ไปยัง CargoWise Universal Shipment XML โดยใช้ตารางการแมปฟิลด์ด้านบน ข้อพิจารณาสำคัญสำหรับตัวแทนขนส่งไทย:

• การเข้ารหัสอักขระไทย: KabyTech ส่งคืนข้อความเข้ารหัส UTF-8 ตรวจสอบให้แน่ใจว่าการแปลงของคุณรักษาการเข้ารหัส UTF-8 จนถึง CargoWise ชื่อผู้ส่ง/ผู้รับภาษาไทยต้องไม่ถูกทำให้เสียหายระหว่างการสร้าง XML
• รูปแบบวันที่: KabyTech ใช้ ISO 8601 (2026-03-20T14:30:00+07:00) CargoWise คาดหวัง yyyy-MM-ddTHH:mm:ss ตัด timezone offset ออกระหว่างการแปลง
• หน่วยน้ำหนัก: KabyTech ส่งคืนน้ำหนักในหน่วยที่ระบุใน AWB เสมอ (มักเป็น KG สำหรับสินค้าไทย) ตรวจสอบว่าตรงกับการตั้งค่าหน่วยน้ำหนักเริ่มต้นของ CargoWise
• RTD หลายบรรทัด: แต่ละบรรทัด RTD จะกลายเป็น element PackingLine แยกกันใน Universal XML รักษาลำดับไว้ — CargoWise ใช้ packing line แรกเป็นคำอธิบายสินค้าหลัก

งาน C: ส่งไปยัง CargoWise eAdapter

ส่ง XML ที่แปลงแล้วไปยัง CargoWise eAdapter endpoint eAdapter จะสร้างหรืออัปเดตรายการการขนส่ง กำหนดค่า eAdapter ให้ส่งคืนหมายเลขอ้างอิงการขนส่ง CargoWise เมื่อสำเร็จ และบันทึกข้อมูลนี้ร่วมกับ KabyTech AWB ID สำหรับวัตถุประสงค์การตรวจสอบ

การจัดการข้อผิดพลาดและการตรวจสอบ

การเชื่อมต่อสำหรับการใช้งานจริงต้องมีการจัดการข้อผิดพลาดที่แข็งแกร่ง เราแนะนำสิ่งต่อไปนี้:

• ตรรกะการลองซ้ำ webhook: KabyTech ลองส่ง webhook ที่ล้มเหลวซ้ำสูงสุด 5 ครั้งด้วย exponential backoff (1s, 4s, 16s, 64s, 256s) หากการลองซ้ำทั้งหมดล้มเหลว event จะถูกบันทึกใน Operations Portal สำหรับการกระตุ้นซ้ำด้วยมือ
• คิวจดหมายตาย: หาก middleware ของคุณล้มเหลวในการแปลง payload (เช่น รูปแบบฟิลด์ที่ไม่คาดคิด) ให้เก็บ payload ดิบในคิวจดหมายตายแทนที่จะทิ้งไป ซึ่งช่วยให้คุณสืบสวนและประมวลผลซ้ำได้โดยไม่สูญเสียข้อมูล
• การตรวจจับซ้ำของ CargoWise: ใช้หมายเลข AWB เป็น key ตรวจสอบการซ้ำในการกำหนดค่า eAdapter ของคุณ หาก AWB เดียวกันถูกแยกวิเคราะห์สองครั้ง (เช่น เนื่องจากการลองซ้ำ webhook) CargoWise ควรอัปเดตรายการที่มีอยู่แทนที่จะสร้างรายการซ้ำ
• การแจ้งเตือน: ตั้งค่าการแจ้งเตือนสำหรับ: ความล้มเหลวในการส่ง webhook ข้อผิดพลาดในการแปลง การปฏิเสธจาก CargoWise eAdapter และ AWB ที่ถูกตั้งค่าสถานะสำหรับการตรวจสอบ พอร์ทัลของ KabyTech รองรับการแจ้งเตือนผ่าน Slack และอีเมลสำหรับทั้งหมดนี้

การทดสอบการเชื่อมต่อ

ก่อนเริ่มใช้งานจริง ให้ทดสอบท่อส่งทั้งหมดด้วยสถานการณ์ต่อไปนี้:

1. AWB มาตรฐาน: การขนส่งแบบง่ายที่มี 1 บรรทัด RTD ค่าใช้จ่ายชำระล่วงหน้า ต้นทาง BKK ตรวจสอบว่าทุกฟิลด์ถูกกรอกอย่างถูกต้องใน CargoWise
2. RTD หลายบรรทัด: AWB ที่มี 5+ บรรทัด RTD และประเภทอัตราผสม ตรวจสอบว่าแต่ละบรรทัดสร้าง packing line แยกใน CargoWise
3. ข้อมูล OCI: AWB ที่มีบรรทัด OCI ตรวจสอบว่าแมปไปยังรายการอ้างอิงศุลกากรใน CargoWise
4. ภาษาไทย: AWB ที่มีอักขระไทยในชื่อผู้ส่ง/ผู้รับ ตรวจสอบว่าไม่มีการเข้ารหัสเสียหาย
5. ความล้มเหลวในการตรวจสอบ: อัปโหลดเอกสารที่ไม่ชัดเจนโดยเจตนา ตรวจสอบว่า webhook validation-failed ทำงานและฟิลด์ที่ถูกตั้งค่าสถานะถูกระบุอย่างถูกต้อง
6. การจัดการซ้ำ: ส่ง AWB เดียวกันสองครั้ง ตรวจสอบว่า CargoWise อัปเดตแทนที่จะสร้างรายการซ้ำ

KabyTech จัดเตรียมสภาพแวดล้อม sandbox พร้อม API key ทดสอบเพื่อจุดประสงค์นี้ ผลลัพธ์ที่แยกวิเคราะห์ใน sandbox ใช้ JSON schema เดียวกับการใช้งานจริงแต่ไม่ถูกนับรวมในโควตารายเดือนของคุณ

รายการตรวจสอบสำหรับการเริ่มใช้งานจริง

• ขอบเขต API key ถูกตรวจสอบแล้วและ secret ถูกเก็บอย่างปลอดภัย
• Webhook endpoint ลงทะเบียนแล้วและการตรวจสอบ signature ยืนยันแล้ว
• การแมปฟิลด์ทดสอบแล้วสำหรับทั้ง 29 ส่วน FWB
• การเข้ารหัส UTF-8 ถูกรักษาตลอดท่อส่งการแปลง
• การตรวจจับซ้ำของ eAdapter กำหนดค่าแล้ว
• การจัดการข้อผิดพลาดและคิวจดหมายตายพร้อมแล้ว
• การแจ้งเตือนกำหนดค่าแล้วสำหรับความล้มเหลวและการตรวจสอบ
• ผ่านสถานการณ์ทดสอบ 6 สถานการณ์ใน sandbox
• วางแผนการทำงานคู่ขนาน (ด้วยมือ + อัตโนมัติ) สำหรับสัปดาห์แรก

บทความที่เกี่ยวข้อง