Getting Started (Integration Quickstart)

Base conventions

• Base API prefix: /api/v1
• Primary response envelope: ApiResponse<T>
• JSON style: camelCase bodies; some query params are snake_case where explicitly mapped.

Auth modes

• JWT (frontend clients): Authorization: Bearer <token>
• API key (server-to-server integrations): X-API-Key: <keyId.secret>
• OAuth 2.0 Bearer (MCP / AI agent clients): Authorization: Bearer <oauth_access_token> — issued via PKCE authorization code flow at POST /api/v1/oauth/token. See 03-integrations/store-mcp-server.md.

Address reference dependency

Store and ecommerce order creation flows require:

• addressProvinceCode
• addressAreaId

Resolve from public endpoints:

• GET /api/v1/address-reference/provinces
• GET /api/v1/address-reference/provinces/{code}/areas

Role + permission rule

For JWT routes, successful access generally requires both:

1. Matching route role gate ([Authorize(Roles = ...)])
2. Matching permission gate ([HasPermission(...)])

Store e-commerce modules (JWT)

The store backend includes 13 dedicated management modules accessible via JWT under /api/v1/store/. All require store_owner or store_staff role plus a module-specific store.* permission.

Module	Base path	Permission prefix
Product Categories	/api/v1/store/categories	store.product_categories.*
Customers	/api/v1/store/customers	store.customers.*
Suppliers	/api/v1/store/suppliers	store.suppliers.*
Purchase Orders	/api/v1/store/purchase-orders	store.purchase_orders.*
Expenses	/api/v1/store/expenses	store.expenses.*
Cashier / POS	/api/v1/store/cashier	store.cashier.*
Discount Rules	/api/v1/store/discounts/rules	store.discounts.*
Discount Codes	/api/v1/store/discounts/codes	store.discounts.*
Shipping Rules	/api/v1/store/shipping/rules	store.shipping.*
Package Sizes	/api/v1/store/package-sizes	store.package_sizes.*
Print Templates	/api/v1/store/print-templates	store.print_templates.*
Store Settings	/api/v1/store/settings	store.settings.*
Analytics	/api/v1/store/analytics	store.analytics.view

Call POST /api/v1/store/settings once on store creation before using most e-commerce features.

Order create: required fields

• addressProvinceCode, addressAreaId — from address reference API
• payment_method — required (was previously optional; now returns 400 if absent)
• items[].sku must be unique within the request (duplicate SKUs return 400)

Ticket fields (enums)

Ticket status, category, and priority are now enum types:

• status: Open, Pending, InProgress, New, Closed, Resolved
• category: Unspecified, Driver, Delivery, LastMile, Logistics, Store, Inventory, Merchant, Catalog, Channel, Api, Other

First validation pass for any client

1. Authenticate and call GET /api/v1/auth/me
2. Call one list endpoint in your client surface
3. Validate required headers, scopes, and role/permission mapping
4. If 403, inspect role gate and permission gate separately