Skip to content

External Integrations ​

ระบบ WMS รองรับ 3 รูปแบบการเชื่อมต่อกับระบบภายนอก: Push API, Webhooks, และ File Storage (R2)

1. Push Integration API ​

REST API ที่ให้ระบบภายนอก (ERP, e-commerce, marketplace, suppliers) push ข้อมูลเข้า WMS โดยตรง

Base URL: https://wms-api-dev-2w6s.onrender.com/api/v1/integration/v1Auth: X-API-Key: wms_... (SHA-256 hashed at rest)

Endpoints (16 ทั้งหมด) ​

จาก apps/api/src/modules/integration/integration.controller.ts:

Master Data (upsert pattern) ​

MethodPathScopeคำอธิบาย
POST/itemswriteupsert item (by tenantId + sku)
POST/items/bulkwritebulk upsert (max 500)
POST/partnerswriteupsert partner (by code)
POST/partners/bulkwritebulk (max 500)
POST/locationswriteupsert location (by warehouseCode + code)
POST/locations/bulkwritebulk (max 500)

Inbound ​

MethodPathScopeคำอธิบาย
POST/asnwritecreate ASN
POST/asn/bulkwritebulk ASN (max 100)
POST/grnwritereceive against ASN

Outbound ​

MethodPathScopeคำอธิบาย
POST/orderswritecreate sales order
POST/orders/bulkwritebulk orders (max 100)
POST/orders/:orderNo/cancelwritecancel by order number

LPN ​

MethodPathScopeคำอธิบาย
POST/lpnwritecreate license plate

Inquiry (read-only) ​

MethodPathScopeคำอธิบาย
GET/orders/:orderNoreadorder + lines + tasks + summary
GET/asn/:asnNoreadASN + lines + receivedQty + GRNs
GET/stockreadby sku + warehouseCode (+ lotNo)

ดูตัวอย่าง payload + response เต็ม: Push Integration API

Key features ​

  • Identifier resolution — ใช้ business key (sku, code, warehouseCode) ไม่ใช่ UUID — service auto-resolve เป็น UUID
  • Idempotency — header Idempotency-Key (TTL 24 ชม.) — ส่งซ้ำ body เดิม → replay
  • Bulk 207 Multi-Status — bulk endpoint อาจตอบ 207 ถ้ามีบาง item error
  • Tenant scoping — API Key ผูกกับ tenantId → จำกัดขอบเขตอัตโนมัติ

2. Security & Rate Limiting (per API Key) ​

ตั้งได้รายตัวใน Admin Portal → API Keys:

IP Whitelist ​

  • รับทั้ง exact IP (203.0.113.5) และ CIDR (203.0.113.0/24)
  • เช็คจาก X-Forwarded-For (Render ส่ง real IP)
  • ว่าง = อนุญาตทุก IP

Allowed Origins (CORS) ​

  • เช็ค Origin header
  • ถ้าไม่มี Origin (server-to-server) → อนุญาต
  • ถ้ามี + ไม่อยู่ใน list → 403

Rate Limit ​

  • req/min ต่อ key (sliding 60s window, in-memory)
  • 0 หรือว่าง = unlimited
  • เกิน → 429 + header Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining

Request Logging ​

  • ทุก request log async ลง api_key_request table
  • ใช้ในหน้า "API Key Stats" (Admin Portal)

3. Webhooks (Outbound) ​

ระบบ WMS push event ไปยัง URL ของ external system

Model: WebhookSubscription ​

typescript
{
  id: UUID;
  tenantId: UUID;
  url: string;              // your endpoint
  events: string[];         // ['order.shipped', 'asn.received', ...]
  secret: string;           // HMAC secret
  active: boolean;
  filters?: Json;           // optional event filter
}

Supported events ​

EventTrigger
asn.receivedGRN created against ASN
asn.completedASN fully received
order.allocatedStock allocated to order
order.releasedOrder released as pick tasks
order.shippedShipment dispatched
order.cancelledOrder cancelled
stock.adjustedStock adjustment posted
cyclecount.varianceVariance detected during count

Payload format ​

json
{
  "event": "order.shipped",
  "timestamp": "2026-06-15T10:30:00.000Z",
  "data": {
    "orderNo": "SO-20260615-0042",
    "shipmentNo": "SHIP-...",
    "trackingNo": "TH123..."
  }
}

Delivery tracking ​

WebhookDelivery model — บันทึกทุกครั้งที่ส่ง:

  • responseStatus, responseBody, attempts, nextRetryAt
  • status: pending / success / failed / dead_letter

Admin endpoints ​

MethodPathคำอธิบาย
GET/webhookslist subscriptions
POST/webhookscreate
PATCH/webhooks/:idupdate
DELETE/webhooks/:idremove
POST/webhooks/:id/testfire test event

4. File Storage — Cloudflare R2 ​

ใช้สำหรับ:

  • Shipping labels (PDF)
  • Generated reports (Excel/PDF)
  • Upload attachments (RMA photos, GRN docs)

Setup ​

S3-compatible — ใช้ @aws-sdk/client-s3 + @aws-sdk/s3-request-presigner ใน apps/api/src/modules/files/

Env vars:

bash
R2_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_BUCKET_NAME=wms-files

Upload pattern (presigned URL) ​

1. Client → POST /api/v1/files/presigned-upload
              { fileName, contentType }

2. API     → returns { uploadUrl, fileKey, expiresIn: 300 }

3. Client → PUT <uploadUrl> with file body (direct to R2)

4. Client → POST /api/v1/<resource> { fileKey: "..." }
              (เก็บ key ใน DB; access ภายหลังด้วย presigned GET URL)

ทำไม R2

  • ไม่มี egress fees (ต่าง S3 / GCS)
  • S3-compatible API → reuse SDK ได้
  • Cloudflare network → latency ต่ำ

5. Email (placeholder) ​

ตอนนี้ระบบ ยังไม่ wire email provider — code มี hook สำหรับ:

  • Welcome email (user create)
  • Password reset
  • Approval notifications

แนะนำ provider เมื่อพร้อม: Resend หรือ AWS SES (cheap, transactional)

ตำแหน่งที่จะใส่: สร้าง MailModule + service ใน apps/api/src/modules/mail/ — inject เข้า UsersService + ApprovalsService

Integration Best Practices ​

  1. Production keys ตั้ง IP whitelist เสมอ — ลดความเสียหายถ้า key รั่ว
  2. Rate limit ตามจริง — เช่น ERP: 120 req/min
  3. Allowed Origins เฉพาะ key สำหรับ browser — server-to-server ไม่ต้อง
  4. Rotate ทุก 90 วัน — สร้างใหม่ → verify → revoke เก่า
  5. แยก key ต่อ integration — ปิด/หมุนทีละตัว
  6. ใช้ Idempotency-Key ทุก POST — ป้องกัน duplicate จาก network retry
  7. Webhook endpoint ต้อง idempotent — เราจะ retry ถ้า fail

เผยแพร่ภายใต้ Digital Outsourcing