Supplier Track API v1.1 vs SCE-TMS Web Service API v1.8

1. สองตัวนี้คืออะไร

2. สถาปัตยกรรม / ทิศทางข้อมูล

จุดต่างที่ใหญ่ที่สุดมี 2 เรื่อง: ① ทิศทาง — 🅰 ยิงข้อมูลเข้า Maersk ฝ่ายเดียว แต่ 🅱 เป็นสองทาง (ฝั่งเราต้องเปิด endpoint รับคำสั่ง pairing จาก Maersk ด้วย) และ ② แหล่งข้อมูล order — 🅰 ข้อมูล Work Order/เลขตู้ไม่ไหลผ่าน API เลย (ไปทางบริษัทรถ เราต้องหาทางเอามาเอง) แต่ 🅱 Maersk ป้อนข้อมูล shipment เข้าระบบเราให้เองผ่าน pairDevice

🅰 Supplier Track API — ทางเดียว (push อย่างเดียว)

                    ┌─── Work Order + เลขตู้ ส่งให้บริษัทรถ ───┐
                    │    (ช่องทางจองงานปกติ — ไม่ผ่าน API นี้!)  │
                    ▼                                        │
  ┌──────────────┐  ❓ mapping                ┌───────────────┴──┐
  │ Carrier      │ ─── รถ↔WO↔ตู้ ───►  ???    │      Maersk      │
  │ (บริษัทรถ)    │  (GPS provider ต้องออกแบบ  │      Inland      │
  └──────────────┘   ช่องทางรับเอง — จุดอ่อน!) │                  │
                                    │         │                  │
  ┌──────────────┐                  ▼         │                  │
  │ GPS Provider │   POST /vendor/positions   │                  │
  │ (เรา)         │ ─────────────────────────► │                  │
  └──────────────┘   บังคับแนบ WO + เลขตู้      └──────────────────┘
                     ทุก payload ← ถ้าไม่มี = ไม่ผ่าน validation


🅱 SCE-TMS API — สองทาง (ต้องมี endpoint ทั้งสองฝั่ง)

  ┌──────────────────┐   POST pairDevice / unpairDevice  ┌────────────┐
  │ Mappoint /       │ ◄──────────────────────────────── │   Maersk   │
  │ GPS Provider     │   ★ ข้อมูลทริปมาทางนี้เอง:          │  SCE TMS   │
  │                  │   Shipment ↔ Truck + จุดจอด        │  (WGCL)    │
  │ ต้องเปิด endpoint  │   + geofence + ETA/ETD            │            │
  │ ให้ Maersk ยิงเข้า │                                   │            │
  │                  │   POST insertHeartbeat /          │            │
  │                  │ ────────────────────────────────► │            │
  └──────────────────┘   insertEvent — echo ShipmentRefNo │            │
                         ที่ได้รับมา (ไม่ต้องหา order เอง)  └────────────┘
    

3. ตารางเปรียบเทียบหลัก

4. เทียบ Endpoint ต่อ Endpoint

5. ประเด็นสำคัญ: GPS Provider "ไม่มีข้อมูล Order / เลขตู้" — ต่างกันคนละโลก

ข้อกังวลหลักของผู้ให้บริการ GPS คือ มีแค่ทะเบียนรถ + พิกัด + เวลา แต่ไม่มีข้อมูล order/ตู้/ทริป — สอง API นี้จัดการเรื่องนี้ต่างกันโดยสิ้นเชิง:

เส้นทางข้อมูล order ของ Supplier Track (ถ้าจำเป็นต้องต่อตัวนี้)

Maersk ──① Transport/Work Order──► Carrier (บริษัทรถ) ★ คนเดียวที่มีข้อมูลครบ
                                     │  ในใบงานมี: เลข WO, booking, จุดรับ-ส่ง
                                     ▼
                          ② จ่ายงาน: "ทะเบียน กข-1234 วิ่ง WO นี้"
                                     ▼
                          ③ คนขับรับตู้ที่ท่า → เลขตู้ยืนยันแน่นอน
                             (พ่นข้างตู้ + ใบ EIR)
                                     ▼
                    ★ จุดที่ข้อมูลต้องไหลเข้าระบบ GPS ของเรา ★
    

6. เทียบ Payload ส่งตำแหน่ง GPS

{
  "uniqueIdentifier": "3",
  "latitude": 59.515137,
  "longitude": 17.674397,
  "timestamp": "2024-03-03T07:45:00+01:00",
  "workOrderNumber": "67000009954",
  "bookingNumber": "1",
  "containerNumber": "BMOU2430595",
  "event": ""
}

{
  "TransID": "123345",
  "AccountID": "SCE123",
  "Data": [{
    "Country": "THA", "TenantID": "0",
    "Type": "Shipment",
    "Heartbeat": {
      "DeviceID": "S8788M",
      "TimeStamp": "20240101123456",
      "ShipmentRefNo": "otmshipmentID1",
      "Latitude": 28.544663,
      "Longitude": 77.119275,
      "Address": "reverse geocoded address",
      "Speed": 25.0, "Course": 320.0,
      "IgnitionStatus": true,
      "Temperature": 28.2
    }
  }]
}

7. สิ่งที่ SCE-TMS ต้องการเพิ่มจากฝั่งเรา (ไม่มีใน Supplier Track)

• เปิด endpoint ฝั่ง Mappoint รับ pairDevice / unpairDevice — พร้อมระบบ authentication ให้ Maersk ขอ token จากเราได้
• เก็บสถานะ pairing — รถ 1 คันอาจถูก pair หลาย shipment (คนละ ETA) ต้อง route heartbeat ให้ถูก shipment
• Reverse geocoding — field Address เป็น required ใน heartbeat
• ข้อมูล telematics เพิ่มเติม — Speed, Course, IgnitionStatus (required) และ Temperature (optional, ใหม่ใน v1.8)
• Exception detection — ตรวจจับขับเร็ว/เบรกแรง/เร่งแรง แล้วยิง insertEvent
• Retry logic — ทั้งสองฝั่งใช้กติกา retrigger สูงสุด 3 ครั้งเมื่อ Success=false หรือไม่ตอบ
• Encoding layer — ทุก request ต้องห่อ JSON เป็น Base64 + URLEncode (ต่างจาก REST JSON ปกติ)

8. จุดที่เหมือนกัน

• เป็นของ Maersk ทั้งคู่ และใช้ OAuth 2.0 ผ่าน Apigee เป็นแกน authentication ขาเข้า Maersk
• เป้าหมายเดียวกันเชิงธุรกิจ: visibility ของการขนส่งทางบกแบบเรียลไทม์
• ส่งตำแหน่งเป็นรอบเวลาสม่ำเสมอ (10–15 นาที vs heartbeat interval)
• มี staging/UAT environment ให้ทดสอบก่อนขึ้น production ทั้งคู่
• ใช้ HTTP POST เป็นหลักทั้งคู่

9. ข้อสรุปสำหรับโปรเจกต์ WGCL (Mappoint Asia)

Supplier Track API (🅰) เป็นของหน่วยธุรกิจ Ocean/Inland คนละส่วนกัน — ไม่เกี่ยวกับ scope งาน WGCL แต่รู้ไว้มีประโยชน์: ถ้าในอนาคต Maersk ฝั่ง Ocean ต้องการข้อมูลตู้คอนเทนเนอร์จากรถที่ Mappoint track อยู่ อาจถูกขอให้ integrate ตัวนี้เพิ่ม ซึ่งเป็น integration แยกอีกชุด (คนละ credential, คนละ host, คนละ data model) — และถ้าถึงวันนั้นจริง ให้กลับไปดูหัวข้อ 5 ก่อน: เราไม่มีข้อมูล order/เลขตู้ ทางที่คุ้มที่สุดคือเจรจาทาง A ให้ Maersk มาดึงพิกัดจาก API เราแทน ไม่ใช่รับภาระหา order มายิงเอง

งานหลักที่ต้อง estimate สำหรับ SCE-TMS

1. Inbound endpoint ฝั่ง Mappoint (pairDevice / unpairDevice) + auth service ให้ Maersk
2. Pairing state management (shipment ↔ truck, รองรับ pairing ซ้อน)
3. Outbound: insertHeartbeat scheduler (ตาม pairing ที่ active) + Base64 encoding layer
4. Outbound: insertEvent สำหรับ exception (SPD/HBK/HAC/SAC/SSR)
5. Consolidation layer รับ GPS จาก provider อื่น (~300 คัน: หัว 270 + หาง 75) ตาม scope ประชุม
6. Retry + monitoring (retrigger ≤ 3, error S01–S04)