OrcaTMS API Documentation

01ภาพรวม

OrcaTMS Integration API ออกแบบมาให้เชื่อมต่อระบบคลังสินค้า (WMS) หรือ ERP เข้ากับงานขนส่งได้อัตโนมัติ — สร้างงานจากคำสั่งซื้อ ติดตามสถานะจนส่งมอบ และรับหลักฐาน POD กลับไปยังระบบต้นทาง

• ทุกคำขอและคำตอบเป็น JSON
• ยืนยันตัวตนด้วย API key (ไม่ใช้ล็อกอินผู้ใช้) — ผูกกับองค์กร (tenant) จากตัวคีย์เอง
• สร้างงานแบบ idempotent ด้วย external_ref — ส่งซ้ำได้โดยไม่เกิดงานซ้ำ

02Base URL

ตัวอย่างในเอกสารนี้ใช้ตัวแปร {BASE} แทน base URL ด้านบน

03การยืนยันตัวตน (Authentication)

ส่ง API key มากับทุกคำขอผ่าน header (เลือกได้ 1 แบบ):

X-API-Key: tmsk_xxxxxxxx_yyyyyyyyyyyyyyyy
# หรือ
Authorization: Bearer tmsk_xxxxxxxx_yyyyyyyyyyyyyyyy

การสร้าง API key

ผู้ดูแลระบบสร้างคีย์ได้ที่ Dashboard → ตั้งค่า → การใช้งานระบบ → แท็บ “API ระบบภายนอก”

• เลือก scope ที่ต้องการ
• คีย์เต็มจะแสดงครั้งเดียวตอนสร้าง — เก็บให้ปลอดภัย (ระบบเก็บเฉพาะ hash)
• เพิกถอน (revoke) คีย์ได้ตลอดเวลา

04Scopes

05Rate limit

• อ่าน (public.read): 120 คำขอ/นาที ต่อคีย์
• เขียน (jobs.write): 120 คำขอ/นาที ต่อคีย์
• GPS ingest: 600 คำขอ/นาที ต่อคีย์
• เกินโควตา → 429 พร้อม header Retry-After, X-RateLimit-Remaining

06รูปแบบ Response

// สำเร็จ
{ "status": "success", "data": { ... } }
// ผิดพลาด
{ "status": "error", "message": "..." }

07สร้างงานขนส่ง

สร้างงานขนส่งใหม่จากคำสั่งของ WMS · idempotent ด้วย external_ref

Request body

{
  "external_ref": "WMS-ORD-100245",
  "customer": { "name": "บริษัท ลูกค้า จำกัด", "phone": "0891234567" },
  "pickup": { "name": "คลังสินค้า A แหลมฉบัง", "latitude": 13.0827, "longitude": 100.8836 },
  "deliveries": [
    { "name": "ห้างเซ็นทรัล ชลบุรี", "latitude": 13.3611, "longitude": 100.9847 },
    { "name": "โลตัส ระยอง", "latitude": 12.6807, "longitude": 101.2812 }
  ],
  "dest_province": "ชลบุรี",
  "booking_no": "BK-778", "requested_date": "2026-07-20"
}

Response 201

{ "status": "success", "data": { "id": 251, "job_number": "J26070001", "status": "confirmed" } }

08ค้นหา / รายการงาน

ดึงรายการงาน กรองด้วย query string ได้ เช่น ?status=on_trip, ?external_ref=WMS-ORD-100245, ?page=1

09รายละเอียด / สถานะงาน

คืนรายละเอียดงานพร้อมสถานะปัจจุบัน จุดรับ-ส่ง คนขับ/รถที่มอบหมาย และความคืบหน้า

10หลักฐานการส่ง (POD)

ดึงหลักฐานการส่งมอบ — ลายเซ็นผู้รับ รูปถ่าย ค่า SHA-256 เวลาส่ง และผู้รับแยกรายจุด (Multi-drop)

11ยกเลิกงาน

ยกเลิกงานที่ยังไม่ปิด · หากงานปิด/เสร็จแล้วจะได้ 409

{ "reason": "ลูกค้ายกเลิกคำสั่งซื้อ" }

12รถ & ตำแหน่ง

รายการรถขององค์กร และตำแหน่งล่าสุดของรถแต่ละคัน (ละติจูด/ลองจิจูด ความเร็ว เวลาที่อัปเดต)

13ส่งพิกัด GPS เข้าระบบ

รับพิกัดจากผู้ให้บริการ GPS ภายนอก (เช่น Cartrack) เข้าสู่ระบบติดตาม — ผูกกับองค์กรจากตัวคีย์ รองรับอัตราสูง

14สถานะงาน (status)

15Webhooks — รับการแจ้งเตือนกลับ WMS

ตั้งค่า Webhook URL ได้ที่ Dashboard → ตั้งค่า → Webhooks · ระบบจะยิง POST ไปยัง URL ของคุณเมื่อสถานะงานเปลี่ยน

POST <your-webhook-url>
X-TMS-Signature: sha256=...
{
  "event": "job.status_changed",
  "job_number": "J26070001",
  "external_ref": "WMS-ORD-100245",
  "status": "completed",
  "occurred_at": "2026-07-20T15:22:01Z"
}