REST API v1พอร์ทัลลูกค้า

คู่มือ API — Finstrata Warehouse

ให้ระบบของเจ้าของสินค้า (ERP, ร้านออนไลน์, OMS) ส่งงานเข้าคลังและดึงข้อมูลอัตโนมัติ · รูปแบบ JSON · UTF-8 · เวลาเป็นเวลาไทย (UTC+7)

การยืนยันตัวตน

ใช้ API Key ของลูกค้าแต่ละราย (ดู/สร้างใหม่ได้ที่พอร์ทัลลูกค้า เมนู "เชื่อมต่อระบบ" หรือหลังบ้านคลัง หน้าลูกค้า › API / Webhook) ใส่ใน header X-API-Key ทุกคำขอ · ข้อมูลที่เห็นจะเป็นของลูกค้ารายนั้นเท่านั้น

curl https://warehouse.finstrata.io/api/v1/ping \
  -H "X-API-Key: fwk_xxxxxxxxxxxxxxxx"

{ "ok": true, "customer": "GADGET", "version": "1.0.0" }

ข้อผิดพลาด

400ข้อมูลไม่ถูกต้อง เช่น ไม่พบสินค้า จำนวนไม่ถูกต้อง เลขอ้างอิงซ้ำ — ดูข้อความใน error
401X-API-Key ไม่ถูกต้อง
402บัญชีคลังอยู่ในโหมดดูอย่างเดียว (อ่านข้อมูลได้ แต่สร้างงานไม่ได้)
404ไม่พบเอกสาร
{ "error": "เลขอ้างอิง WEB1001 มีอยู่แล้วในคำสั่ง SO2611-0012", "duplicate": "SO2611-0012" }

ดูสต็อก

GET/api/v1/stock

ยอดรวมต่อสินค้า · ?q= ค้นหา

[{ "sku": "GH-PWB-10K", "name": "พาวเวอร์แบงก์ 10000mAh", "uom": "ชิ้น",
   "on_hand": 1240, "available": 1180, "allocated": 60, "on_hold": 0, "nearest_expiry": null }]
GET/api/v1/stock/lots

แยกตาม Lot / วันหมดอายุ / สถานะ · ?expiring=30 เฉพาะที่หมดอายุภายใน 30 วัน

[{ "sku": "FM-MILK-1L", "lot_no": "L261118A", "expiry": "2026-12-02", "status": "AVAILABLE", "qty": 480, "allocated": 96, "warehouse": "BNA" }]

สินค้า (SKU)

GET/api/v1/skus
POST/api/v1/skus

สร้างหรืออัปเดต (ตามรหัส) ส่งได้ทีละรายการหรือเป็น array

[{ "code": "SKU-001", "name": "เสื้อยืด สีขาว M", "barcode": "8850001112223", "uom": "ตัว",
   "case_qty": 50, "pallet_qty": 1000, "weight_kg": 0.2, "cbm": 0.0008,
   "track_lot": false, "track_expiry": false, "min_qty": 100 }]

สร้าง ASN (แจ้งเข้าสินค้า)

POST/api/v1/asns
{
  "warehouse": "BNA",            // รหัสคลัง (ไม่ใส่ = คลังแรก)
  "ref_no": "PO-2611-0042",
  "supplier": "Shenzhen Tech Ltd.",
  "eta": "2026-11-25",
  "container_no": "TGHU8841207",
  "lines": [ { "sku_code": "GH-EARBUD-X", "qty": 600 },
             { "sku_code": "GH-CABLE-C", "qty": 2000, "lot_no": "", "expiry": "" } ]
}
→ { "asn_no": "ASN2611-0031", "status": "OPEN" }

ดูสถานะ ASN

GET/api/v1/asns/{asn_no หรือ ref_no}
{ "asn_no": "ASN2611-0031", "ref_no": "PO-2611-0042", "status": "CLOSED", "eta": "2026-11-25",
  "lines": [ { "sku": "GH-EARBUD-X", "expected": 600, "received": 600, "damaged": 0, "lot_no": "", "expiry": "" } ] }

สถานะ: OPEN (รอรับ) → RECEIVING (กำลังรับ) → RECEIVED (ปิดรับ รอจัดเก็บ) → CLOSED (จัดเก็บครบ) · CANCELLED

สร้างคำสั่งส่งสินค้า

POST/api/v1/orders
{
  "ref_no": "WEB100234",          // เลขออเดอร์ของคุณ (กันส่งซ้ำ)
  "ship_to_name": "คุณสมชาย ใจดี",
  "ship_to_phone": "0812345678",
  "ship_to_address": "99/1 ถ.สุขุมวิท แขวงคลองตัน เขตคลองเตย กรุงเทพฯ 10110",
  "required_date": "2026-11-22",
  "priority": "NORMAL",           // NORMAL | HIGH | URGENT
  "carrier": "Flash Express",
  "cod_amount": 0,
  "auto_allocate": true,          // จัดสรรสต็อกทันที (FEFO/FIFO ตามสินค้า)
  "lines": [ { "sku_code": "GH-PWB-10K", "qty": 2 }, { "sku_code": "GH-CABLE-C", "qty": 1 } ]
}
→ { "order_no": "SO2611-0418", "ref_no": "WEB100234", "status": "ALLOCATED" }

ดูสถานะคำสั่ง

GET/api/v1/orders/{order_no หรือ ref_no}
{ "order_no": "SO2611-0418", "ref_no": "WEB100234", "status": "SHIPPED", "shipped_at": "2026-11-22 15:41:08",
  "carrier": "Flash Express", "tracking_no": "TH01234567A", "pod_name": "คุณสมชาย", "pod_at": "2026-11-23 10:12:44",
  "lines": [ { "sku": "GH-PWB-10K", "ordered": 2, "picked": 2 } ] }

สถานะ: NEW → ALLOCATED → PICKING → PICKED → PACKED → SHIPPED · CANCELLED

ยกเลิกคำสั่ง

POST/api/v1/orders/{order_no หรือ ref_no}/cancel
{ "reason": "ลูกค้ายกเลิกออเดอร์" }

ถ้าหยิบสินค้าไปแล้ว คลังจะนำกลับเข้าตำแหน่งให้อัตโนมัติ · ส่งแล้วยกเลิกไม่ได้

Webhook

ตั้ง URL ที่พอร์ทัลลูกค้า › เชื่อมต่อระบบ · ระบบ POST JSON ไปที่ URL เมื่อเกิดเหตุการณ์ ตอบกลับ HTTP 2xx ภายใน 10 วินาที ถ้าไม่สำเร็จจะส่งซ้ำ (1 นาที, 5 นาที, 30 นาที, 2 ชม., 6 ชม.)

asn.receivedปิดรับสินค้า พร้อมจำนวนรับจริง/เสียหายต่อรายการ
order.statusคำสั่งจัดสรรครบ / ถูกยกเลิก
order.shippedส่งสินค้าแล้ว พร้อมขนส่ง Tracking และจำนวนที่ส่ง
order.deliveredผู้รับเซ็นรับสินค้า (POD)
invoice.issuedออกใบแจ้งหนี้ค่าบริการ
POST https://your-erp.example.com/hooks/warehouse
x-finstrata-event: order.shipped
x-finstrata-signature: sha256=5f1c…   // HMAC-SHA256(body, webhook_secret)

{ "event": "order.shipped", "created_at": "2026-11-22T08:41:08.000Z",
  "data": { "order_no": "SO2611-0418", "ref_no": "WEB100234", "carrier": "Flash Express", "tracking_no": "TH01234567A",
            "lines": [ { "sku": "GH-PWB-10K", "ordered": 2, "shipped": 2 } ] } }
// ตรวจลายเซ็น (Node.js)
const sig = 'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
if (sig !== req.headers['x-finstrata-signature']) return res.status(401).end();