API Reference Overview

ภาพรวม REST API — endpoint groups, auth schemes, response conventions

เอกสารแบบ interactive

หน้านี้คือ overview — สำหรับ schema + try-it-now ของแต่ละ endpoint ให้ดู Swagger UI: https://wms-api-dev-2w6s.onrender.com/api/v1/docs (non-prod เท่านั้น)

Base URL

Env	URL
Development	https://wms-api-dev-2w6s.onrender.com/api/v1
Local	http://localhost:3000/api/v1

Global prefix /api/v1 ตั้งใน main.ts:

app.setGlobalPrefix('api/v1');

Auth Schemes

ระบบรองรับ 2 auth scheme พร้อมกันบน API เดียว:

Scheme	Header	ใช้กับ	บทบาท
JWT Bearer	Authorization: Bearer <jwt>	endpoint ปกติ	end-user (operator/admin) จาก Main WMS หรือ Admin Portal
API Key	X-API-Key: wms_… (หรือ Authorization: ApiKey …)	/integration/v1/*	external system (ERP, e-commerce)

ดูรายละเอียด: Authentication · Authorization

Swagger UI

URL: /api/v1/docs — เปิด เฉพาะ เมื่อ NODE_ENV !== 'production'

จาก main.ts:

if (nodeEnv !== 'production') {
  const swaggerConfig = new DocumentBuilder()
    .setTitle('WMS API')
    .setVersion('1.0')
    .addBearerAuth()
    .addApiKey({ type: 'apiKey', name: 'X-API-Key', in: 'header' }, 'api-key')
    .build();
  SwaggerModule.setup('api/v1/docs', app, document);
}

Endpoint Groups

จาก @Controller('…') ของทุก module:

Prefix	Module	Auth	Purpose
/auth	auth	none + JWT	login, register, me, change-password
/users	users	JWT + admin/role	user CRUD + permission management
/health	health	none	/live, /ready, /stats
/items	master-data/items	JWT	items CRUD
/locations	master-data/locations	JWT	locations CRUD (20+ fields)
/uoms	master-data/uoms	JWT	UoM CRUD + conversions
/partners	master-data/partners	JWT	suppliers/customers/carriers
/warehouses	master-data/warehouses	JWT	warehouse CRUD
/asn	inbound/asn	JWT	ASN create + lines + status
/grn	inbound/grn	JWT	GRN (receive against ASN)
/putaway	inbound/putaway	JWT	putaway tasks lifecycle
/putaway-rules	inbound/putaway	JWT	rule engine config
/stock	inventory/stock	JWT	inquiry by item/location/lot
/movements	inventory (via stock)	JWT	movement ledger query
/adjustments	inventory/adjustments	JWT	stock correction
/cycle-counts	inventory/cycle-counts	JWT	count CRUD + variance
/orders	outbound/orders	JWT	sales order CRUD + cancel
/waves	outbound/waves	JWT	wave plan + release
/pick-tasks	outbound/pick-tasks	JWT	pick lifecycle
/shipments	outbound/shipments	JWT	shipment + packages + label
/rma	returns/rma	JWT	return authorization + receipt
/lpn	lpn	JWT	license plate CRUD + nest/split/movements
/replenishment	replenishment	JWT	rules + tasks
/approvals	approvals	JWT	pending queue + approve/reject
/audit	audit	JWT + admin	audit log search
/announcements	announcements	JWT (admin write)	banner messages
/api-keys	api-keys	JWT + admin	key CRUD + stats + requests log
/webhooks	webhook	JWT + admin	subscription CRUD + test fire
/config	config	JWT + admin	system config keys (WMS settings 8 tabs)
/files	files	JWT	R2 presigned upload URLs
/reports	reports	JWT + role	22 aggregated reports (see below)
/integration/v1/*	integration	API Key	push API (items, partners, locations, asn, grn, orders, lpn, stock)

ดูรายละเอียด method+path ต่อ module: Module Reference

Reports Endpoints (22)

ทั้งหมดอยู่ใต้ /reports/* — ทุก endpoint รับ filter querystring (warehouseId, dateFrom, dateTo, …)

Group	Endpoints
Inventory	/inventory/stock-snapshot, /movements, /adjustments, /aging, /low-stock, /cycle-count-variance
Receiving	/receiving/asn-summary, /grn-summary, /by-sku, /putaway-summary
Outbound	/outbound/order-fulfillment, /pick-tasks, /cycle-time, /by-customer
Delivery	/delivery/shipments, /by-carrier
Users	/users/activity, /login-history, /productivity

Response Format Conventions

Paginated list (default)

{
  "data": [ /* array of records */ ],
  "total": 142,
  "page": 1,
  "limit": 20,
  "totalPages": 8
}

Query params: ?page=1&limit=20&search=…&sort=…&order=asc|desc

Single record

{ "id": "uuid", "field": "…" }

Mutation success (POST/PATCH/DELETE)

ส่วนใหญ่ตอบ record ที่ updated/created กลับ:

{ "id": "uuid", "field": "new value" }

Integration API envelope

ต่างกับ endpoints ปกติ — มี wrapper { status, data, requestId }:

{
  "status": "success",
  "data": { "item": { ... } },
  "requestId": "uuid-v4"
}

Bulk:

{
  "status": "partial",
  "total": 3,
  "created": 2,
  "errors": [ { "index": 1, "error": "..." } ],
  "data": [ ... ],
  "requestId": "uuid-v4"
}

HTTP 207 ถ้ามี errors

ดูเต็ม: Push Integration API

Error format

NestJS default — มาจาก HttpException:

{
  "statusCode": 400,
  "message": ["email must be an email", "password must be longer than 8"],
  "error": "Bad Request"
}

หรือ object ตรง ๆ (auth error):

{ "statusCode": 401, "message": "Invalid email or password" }

Special Headers

Header	ใช้กับ	คำอธิบาย
Authorization: Bearer <jwt>	endpoint ปกติ	JWT auth
X-API-Key: wms_…	integration	API Key auth
Authorization: ApiKey wms_…	integration	alt format
Idempotency-Key: <id>	integration POST	24h replay protection
Idempotent-Replay: true	response	บอกว่า response เป็น cached replay
X-RateLimit-Limit	integration response	req/min ของ API key
X-RateLimit-Remaining	integration response	คงเหลือใน window
Retry-After	429 response	วินาทีที่ต้องรอ

CORS

จาก main.ts:

• อนุญาต *.pages.dev ทุก subdomain (สำหรับ Cloudflare Pages preview deploys)
• บวก origin list จาก CORS_ORIGIN env (comma-separated)
• credentials: true — ส่ง cookie/Authorization ข้าม origin ได้
• No-origin request (server-to-server, curl) → อนุญาตเสมอ