คีย์ API

API Keys ใช้สำหรับให้ระบบภายนอก (ERP, Carrier, Mobile App) เรียก API ของ WMS

คืออะไร?

API Key เป็น "ตั๋วเข้า" สำหรับเรียก API โดยไม่ต้อง Login เป็น User — เหมาะกับ machine-to-machine integration

เมื่อไหร่ใช้?

• เชื่อม ERP push Order มา WMS
• เชื่อม Carrier ส่ง Tracking กลับ
• Mobile app ของบริษัท
• Reporting tool (Power BI, Looker)

วิธีเข้าหน้า API Keys

Sidebar (Admin) → API Keys

สร้าง API Key

1. กด + Generate Key
2. กรอกส่วน ข้อมูลพื้นฐาน:
   • Key Name — ชื่อสื่อความหมาย เช่น ERP_Integration_PROD
   • Description — บันทึกเจ้าของ / ระบบที่เชื่อม / ผู้ติดต่อ
   • Scopes — เลือก permissions เช่น read, write, orders, inventory
   • Expires At — วันหมดอายุ (แนะนำตั้งไว้)
   • Tenant Binding — ถ้าระบุ UUID จะจำกัด key ให้ใช้ได้กับ tenant เดียว (เว้นว่าง = cross-tenant)
3. เปิดส่วน ความปลอดภัย (collapsible) เพื่อตั้ง:
   • IP Whitelist — ใส่ IP/CIDR ละบรรทัด เช่น

     203.0.113.5
     198.51.100.0/24

     ว่าง = อนุญาตทุก IP
   • Allowed Origins (CORS) — ถ้าใช้จากเบราว์เซอร์ ใส่ origin เต็มเช่น https://app.example.com ว่าง = อนุญาตทุก origin (server-to-server)
   • Rate Limit — requests ต่อนาที (0 = ไม่จำกัด)
4. กด Generate
5. ระบบจะแสดง Raw Key ครั้งเดียว — Copy เก็บทันที!

Secret โชว์ครั้งเดียว

ถ้าหาย → ต้องสร้าง Key ใหม่ และ revoke ของเก่า (ลด security risk)

ดูรายละเอียด Key

กดที่แถวของ Key ในตาราง → modal รายละเอียดจะแสดง:

• Settings ทั้งหมด (read-only)
• Request Stats — request count 7 วัน / 24 ชม., error rate, avg response time
• Recent Requests — log ล่าสุด 50 รายการ (timestamp, endpoint, method, IP, status, response time)
• ปุ่ม Edit เพื่อแก้ไข
• ปุ่ม Revoke เพื่อปิดการใช้งาน

แก้ไข Key

เปิด detail → กด Edit → ปรับ scopes / IP whitelist / allowed origins / rate limit / expiry → Save

Key ที่ถูก revoke แล้วสามารถ Activate กลับได้จาก detail modal

การใช้งาน

ส่ง Header กับทุก request:

POST /api/v1/integration/v1/orders
X-API-Key: wms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

หรือใช้รูปแบบ Authorization:

Authorization: ApiKey wms_xxxxxxxx...

Revoke / Disable

หาก Key รั่ว:

1. เปิด Key → กด Revoke
2. ภายในไม่กี่วินาที — Request ทั้งหมดจะถูกปฏิเสธด้วย 401 Invalid, revoked, or expired API key
3. สร้าง Key ใหม่ + อัปเดตใน Integration

Security Checks ที่ระบบบังคับ

Check	Trigger	Response เมื่อไม่ผ่าน
Key valid + active + not expired	ทุก request	401 Unauthorized
IP Whitelist	ipWhitelist ไม่ว่าง	403 Forbidden
Allowed Origins	allowedOrigins ไม่ว่าง + มี Origin header	403 Forbidden
Rate Limit	rateLimitPerMinute > 0	429 + Retry-After header
Scope	endpoint ระบุ @ApiKeyScopes()	401 (admin scope bypass)

ดู Push Integration API → Security & Rate Limiting สำหรับ payload ของแต่ละ error

ดู Usage

แต่ละ Key แสดงใน Detail modal:

• Total requests 7d / 24h
• Avg response time
• Error rate (status ≥ 400)
• Top recent requests (50)

Rotate Key

แนะนำหมุน Key ทุก 90 วัน:

1. สร้าง Key ใหม่ (ใช้ scopes / IP whitelist / rate limit ชุดเดียวกัน)
2. อัปเดต Integration ให้ใช้ Key ใหม่
3. Verify ใช้งานปกติ (ดู Recent Requests ของ Key ใหม่)
4. Revoke Key เก่า

Best Practices

1. ใช้ Key แยกสำหรับแต่ละ Integration — ปิดได้ทีละตัว
2. Scope ให้แคบที่สุด — ERP ต้อง Read Items? แค่ read ไม่ต้อง write
3. Whitelist IP สำหรับ production keys เสมอ — Integration อยู่ Server คงที่
4. Expiration — ตั้งวันหมดอายุเสมอ (เช่น 90 วัน)
5. Rate Limit — กำหนดให้สูงพอแต่ป้องกัน abuse (เช่น 120/min)
6. Description — บันทึก owner + contact ในช่อง description จะช่วยตอนสอบสวน incident
7. Allowed Origins — ตั้งเฉพาะ key ที่เรียกจากเบราว์เซอร์เท่านั้น

Audit

ทุกการใช้ API Key ถูกบันทึกใน api_key_request (และดูได้ใน Detail modal) รวมถึง Audit Log สำหรับการ create/update/revoke (ดู Audit Logs)

หน้าที่เกี่ยวข้อง

• Webhooks
• Audit Logs
• Push Integration API