--- openapi: 3.0.0 paths: "/products": get: operationId: ProductController_findList parameters: - name: page required: false in: query description: Trang, bắt đầu từ 1 schema: minimum: 1 default: 1 type: number - name: page_size required: false in: query description: Số bản ghi mỗi trang schema: minimum: 1 maximum: 500 default: 20 type: number - name: search required: false in: query description: Tìm theo tên hoặc SKU schema: type: string - name: is_active required: false in: query description: Chỉ lấy sản phẩm đang bán schema: type: boolean - name: sort_by required: false in: query description: Cột sắp xếp schema: type: string enum: - name - sku - retail_price - available_quantity - created_at - updated_at - name: sort_order required: false in: query description: Chiều sắp xếp schema: type: string enum: - asc - desc responses: '200': description: '' tags: - Product "/shipping/address/{carrier}/provinces": get: operationId: AddressController_listProvinces parameters: - name: carrier required: true in: path schema: type: number responses: '200': description: '' tags: - Address "/shipping/address/{carrier}/districts": get: operationId: AddressController_listDistricts parameters: - name: carrier required: true in: path schema: type: number - name: provinceId required: true in: query schema: type: number responses: '200': description: '' tags: - Address "/shipping/address/{carrier}/wards": get: operationId: AddressController_listWards parameters: - name: carrier required: true in: path schema: type: number - name: districtId required: true in: query schema: type: number responses: '200': description: '' tags: - Address "/orders": get: description: Paginated, filterable. operationId: DealerOrderController_listOrders parameters: - name: page required: false in: query description: Trang, bắt đầu từ 1 schema: minimum: 1 default: 1 type: number - name: page_size required: false in: query description: Số bản ghi mỗi trang schema: minimum: 1 maximum: 500 default: 20 type: number - name: search required: false in: query description: Free-text search across tracking_number / customer_name / customer_phone schema: maxLength: 100 type: string - name: status required: false in: query description: Filter by OrderStatus code schema: type: number enum: - -1 - 0 - 1 - 16 - 17 - 18 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 - 14 - 15 - 99 - name: category required: false in: query description: Dashboard status bucket (timestamp-driven). Applies the cutover floor date. schema: type: string enum: - today - shipped_today - in_transit - returned - need_print - awaiting_ship - cancelled - name: statuses required: false in: query description: Lọc nhiều trạng thái cùng lúc (OR). Kết hợp AND với `status` nếu gửi cả hai. schema: type: array items: type: number enum: - -1 - 0 - 1 - 16 - 17 - 18 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 - 14 - 15 - 99 - name: from_date required: false in: query description: Ngày tạo từ (YYYY-MM-DD, giờ Việt Nam) schema: type: string - name: to_date required: false in: query description: Ngày tạo đến (YYYY-MM-DD, giờ Việt Nam, bao gồm cả ngày) schema: type: string - name: carrier required: false in: query description: Lọc theo hãng vận chuyển schema: type: number enum: - 0 - 1 - 2 - 3 - 4 - 99 - name: source required: false in: query description: Nguồn đơn (dealer_app | pancake | ...) schema: maxLength: 40 type: string - name: product required: false in: query description: Lọc theo tên sản phẩm trong đơn schema: maxLength: 100 type: string - name: cod_from required: false in: query description: COD tối thiểu (NUMERIC dạng chuỗi) schema: type: string - name: cod_to required: false in: query description: COD tối đa (NUMERIC dạng chuỗi) schema: type: string responses: '200': description: Paginated order list with `{ data, meta }` security: - session: [] summary: List orders for current dealer tags: - Dealer Self — Orders post: description: Single entry point for dealer-app order creation (VTP, GHTK, J&T, Grab). Gọi bằng API key bị giới hạn 1 đơn / 2 phút mỗi đại lý (429 kèm `Retry-After`); phiên đăng nhập trên app không bị siết. operationId: DealerOrderController_createOrder parameters: [] requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/CreateDealerOrderDto" responses: '201': description: Order created with tracking number '429': description: Vượt hạn mức tạo đơn qua API key — `ORDER_CREATE_RATE_LIMIT_EXCEEDED` security: - session: [] summary: Create dealer order tags: - Dealer Self — Orders "/orders/summary": get: description: Order counts per timestamp-driven status bucket, since the cutover floor date. operationId: DealerOrderController_getOrderSummary parameters: [] responses: '200': description: Counts keyed by DealerOrderCategory security: - session: [] summary: Dashboard status-bucket counts tags: - Dealer Self — Orders "/orders/{id}": get: operationId: DealerOrderController_getOrder parameters: - name: id required: true in: path description: Order id schema: type: string responses: '200': description: Order detail security: - session: [] summary: Get dealer order by id (scoped to current dealer) tags: - Dealer Self — Orders "/orders/{id}/breakdown": get: description: Retail vs dealer buy price per line, order profit (COD − cost), and upline dealers. operationId: DealerOrderController_getOrderBreakdown parameters: - name: id required: true in: path description: Order id schema: type: string responses: '200': description: Order profit breakdown security: - session: [] summary: Profit breakdown for a dealer order tags: - Dealer Self — Orders "/customers": get: description: Paginated, searchable by name or phone. Ranked by most-recent order. operationId: DealerCustomerController_listCustomers parameters: - name: page required: false in: query description: Trang, bắt đầu từ 1 schema: minimum: 1 default: 1 type: number - name: page_size required: false in: query description: Số bản ghi mỗi trang schema: minimum: 1 maximum: 500 default: 20 type: number - name: search required: false in: query description: Free-text search across name / phone schema: maxLength: 100 type: string responses: '200': description: Paginated customer list with `{ data, meta }` security: - session: [] summary: List customers for current dealer tags: - Dealer Self — Customers "/customers/search": get: description: Autocomplete for dealer app order form. Returns up to 10 matches ordered by most-recent order. Empty when phone < 3 chars. operationId: DealerCustomerController_searchByPhone parameters: - name: phone required: false in: query description: Phone prefix (≥3 chars) schema: type: string responses: '200': description: Array of dealer-scoped customer matches security: - session: [] summary: Search customers by phone (prefix) tags: - Dealer Self — Customers "/senders": get: operationId: DealerSenderController_list parameters: [] responses: '200': description: Array of sender profiles owned by current dealer security: - session: [] summary: List dealer sender profiles tags: - Dealer Self — Senders "/wallet/me": get: description: Main wallet + commission wallet + commission accrued this month. operationId: DealerWalletSelfController_getMyWallet parameters: [] responses: '200': description: Wallet snapshot for the logged-in dealer security: - session: [] summary: Get current dealer wallet snapshot tags: - Dealer Self — Wallet "/wallet/transactions": get: description: Unified, paginated feed across trading + commission wallet ledgers. operationId: DealerWalletSelfController_listTransactions parameters: - name: page required: false in: query description: Trang, bắt đầu từ 1 schema: minimum: 1 default: 1 type: number - name: page_size required: false in: query description: Số bản ghi mỗi trang schema: minimum: 1 maximum: 500 default: 20 type: number - name: wallet required: false in: query description: 'Wallet filter: ''all'' merges both ledgers, else a single wallet' schema: type: string enum: - all - goods - commission - name: type required: false in: query description: Filter by TransactionType code schema: type: number enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 - 14 - name: search required: false in: query description: Free-text search across reference_id / description schema: maxLength: 100 type: string responses: '200': description: Paginated transaction feed with `{ data, meta }` security: - session: [] summary: List wallet transactions for current dealer tags: - Dealer Self — Wallet info: title: DILIM — API Đại lý description: 'API dành cho đại lý DILIM tích hợp hệ thống riêng: tạo đơn, tra cứu đơn, sản phẩm, khách hàng và ví. Xác thực bằng API key (`X-Api-Key`) tạo trong app đại lý — Cài đặt → Kết nối. Key hết hạn sau 90 ngày. Tạo đơn giới hạn 1 đơn / 120 giây mỗi đại lý; vượt hạn mức trả 429 kèm `Retry-After`.' version: '1.0' contact: {} tags: [] servers: - url: https://api-dealer.dilisupplement.com/api description: Production components: securitySchemes: api-key: type: apiKey in: header name: X-Api-Key schemas: CreateDealerOrderDto: type: object properties: sender_id: type: string description: Dealer sender profile UUID. Optional for PICKUP_AT_COMPANY (sender may be empty); required for other carriers. customer_name: type: string description: Customer full name. Skipped for PICKUP_AT_COMPANY (backend fills from dealer). maxLength: 255 customer_phone: type: string description: Customer phone. Skipped for PICKUP_AT_COMPANY. example: '0912345678' maxLength: 20 customer_address: type: string description: Customer street address. Skipped for PICKUP_AT_COMPANY. maxLength: 500 receiver_province_id: type: number description: VTP receiver province id receiver_district_id: type: number description: VTP receiver district id receiver_ward_id: type: number description: VTP receiver ward id receiver_province: type: string description: Receiver province name maxLength: 100 receiver_district: type: string description: Receiver district name maxLength: 100 receiver_ward: type: string description: Receiver ward name maxLength: 100 items: description: Order line items (≥1) type: array items: "$ref": "#/components/schemas/DealerOrderItemDto" carrier: type: number enum: - 0 - 1 - 2 - 3 - 4 - 99 description: Shipping carrier. Defaults to VTP for backward compatibility. order_service: type: string description: Carrier service code (e.g., VTP service) order_payment: type: number enum: - 1 - 2 - 3 - 4 description: Who pays ship fee product_weight: type: number description: Product weight in grams minimum: 1 money_collection: type: number description: COD money to collect on delivery minimum: 0 prepaid_amount: type: string description: Prepaid amount (decimal string) example: '0.00' notes: type: string description: Internal note maxLength: 500 order_service_add: type: string description: Extra carrier service options is_draft: type: boolean description: Save as draft (skip carrier API submit) default: false is_use_carton: type: boolean description: Đơn có dùng thùng carton hay không. Bỏ trống → suy ra từ carrier (Grab / lấy tại công ty = không dùng). required: - items - order_service - order_payment - product_weight - money_collection DealerOrderItemDto: type: object properties: kind: type: string enum: - product - combo description: Line kind ref_id: type: string description: Reference id of product or combo quantity: type: number description: Quantity (1..9999) minimum: 1 maximum: 9999 required: - kind - ref_id - quantity security: - api-key: []