openapi: 3.0.0
info:
  title: 'API Docs｜QDM 網路開店平台'
  description: "API 提供給授權的店家或是第三方系統供應商 (.e.g APP會員加值, ERP供應商) 進行跨界數據交換。申請審核過後會提供商店環境的介接金鑰，使用呼叫以 RESTful 風格為主要基礎，將 JSON Web Token (JWT) 驗證憑證放入 Authorization: Bearer 標頭之中存取服務，回傳符合條件的 JSON 結果物件。\r\n\r\n## Changelog (2025-09-04)\r\n2025-09-04<br/>\r\n`Added` 會員 > GET > 查詢 增加 custom_value_1 自訂資料1<br/>\r\n`Added` 會員 > GET > 查詢 增加 custom_value_2 自訂資料2<br/>\r\n`Added` 訂單 > GET > 查詢 增加 custom_value_1 自訂資料1<br/>\r\n`Added` 訂單 > GET > 查詢 增加 custom_value_2 自訂資料2<br/>\r\n2025-03-18<br/>\r\n`Added` 訂單 > GET > 查詢 增加 顯示欄位 utm_content<br/>\r\n`Added` 訂單 > GET > 查詢 增加 顯示欄位 utm_term<br/>\r\n<br/>\r\n2025-03-14<br/>\r\n`Added` 設定 > GET > 取得所有優惠券設定 > 增加 限制月份<br/>\r\n`Added` 設定 > GET > 取得所有優惠券設定 > 增加 限制會員<br/>\r\n`Modified` 設定 > GET > 取得所有優惠券設定 > 限制會員群組 回傳格式改為陣列<br/>\r\n`Modified` 設定 > GET > 取得所有優惠券設定 > 限制商品 回傳格式改為陣列<br/>\r\n<br/>\r\n2024-10-18<br/>\r\n`Added` 設定 > GET > 取得所有配送方式<br/>\r\n`Added` 會員欄位新增首購日期 > first_purchase_date 首購日期<br/>\r\n<br/>\r\n2024-01-18<br/>\r\n`Modified` 訂單 > PUT > 訂單狀態異動，觸發商店後台設定（發票開立/受眾中心/會員升等/紅利發送)<br/>\r\n<br/>\r\n2024-01-15<br/>\r\n`Added` 會員 > PUT > 新增更新會員社群帳號 user ID<br/>\r\n<br/>\r\n2023-12-05<br/>\r\n`Added` 商品 > GET > 取得商品總筆數 > 增加「隱藏模式」<br/>\r\n`Added` 商品 > GET > 查詢商品基本資料(SKU) > 增加「隱藏模式」<br/>\r\n`Added` 商品 > GET > 查詢商品基本資料(ID) > 增加「隱藏模式」<br/>\r\n`Added` 商品 > GET > 條件式篩選商品(多筆) > 增加「隱藏模式」<br/>\r\n`Added` 商品 > POST > 新增商品 > 增加「隱藏模式」<br/>\r\n<br/>\r\n2023-11-28<br/>\r\n`Added` 會員 > GET > 條件式篩選會員(多筆) > 增加「購物車最近異動時間」篩選條件<br/>\r\n<br/>\r\n2023-11-22<br/>\r\n`Added` 商品 > GET > 查詢商品基本資料(SKU) > 新增購物選項顯示(必填、類型）<br/>\r\n`Added` 商品 > GET > 查詢商品基本資料(ID) > 新增購物選項顯示(必填、類型）<br/>\r\n<br/>\r\n2023-11-06<br/>\r\n`Added` 訂單 > GET > 取得訂單總筆數 > 新增配送狀態ABANDONED(七天未取)<br/>\r\n`Added` 訂單 > GET > 取得指定訂單(單筆) > 新增配送狀態ABANDONED(七天未取)<br/>\r\n`Added` 訂單 > GET > 條件式篩選訂單(多筆) > 新增配送狀態ABANDONED(七天未取)<br/>\r\n`Added` 訂單 > GET > 查詢包裹配送進度 > 新增配送狀態ABANDONED(七天未取)<br/>\r\n`Added` 訂單 > PUT > 更新物流貨況 > 新增配送狀態ABANDONED(七天未取)<br/>\r\n<br/>\r\n2023-07-24<br/>\r\n`Added` 商品 > GET > 查詢限時特賣(直購價)<br/>\r\n<br/>\r\n2023-05-19<br/>\r\n`Added` 商品基本資料 > 購物選項組合庫存 增加 低庫存警示量(min_quantity)<br/>\r\n`Added` 條件式篩選商品 > 購物選項組合庫存 增加 低庫存警示量(min_quantity)<br/>\r\n`Added` 訂單欄位新增綠界物流交易資訊 > AllPayLogisticsID 綠界科技的物流交易編號<br/>\r\n`Added` 訂單欄位新增綠界物流交易資訊 > CVSPaymentNo 寄貨編號<br/>\r\n`Added` 訂單欄位新增綠界物流交易資訊 > CVSValidationNo 驗證碼<br/>\r\n<br/>\r\n2022-08-17<br/>\r\n`Added` 會員 > PUT > 更新會員生日<br/>\r\n<br/>\r\n2022-08-16<br/>\r\n`Added` 商品 > PUT > 更新商品SKU<br/>\r\n<br/>\r\n2022-08-01<br/>\r\n`Added` 設定 > GET > 升等 與 優惠券 設定<br/>\r\n<br/>\r\n2022-06-20<br/>\r\n`Added` 會員 > GET > 增加「資料異動時間」篩選條件<br/>\r\n`Added` 通知(Webhooks) > PUT > 增加「會員資料異動」通知 customer-modified<br/>\r\n<br/>\r\n2022-06-13<br/>\r\n`Added` 商品 > PUT > 新增/更新限時特賣(直購價)<br/>\r\n`Added` 商品 > DELETE > 刪除限時特賣(直購價)<br/>\r\n<br/>\r\n2022-04-07<br/>\r\n`Added` 會員 > PUT > 更新會員群組<br/>\r\n`Added` 會員 > PUT > 更新會員升等日<br/>\r\n<br/>\r\n2021-11-29<br/>\r\n`Added` 訂單 > GET 條件篩選新增配送方式<br/>\r\n<br/>\r\n2021-09-08<br/>\r\n`Added` 訂單 > 條件式篩選訂單(多筆) > 增加 修改日期篩選<br/>\r\n<br/>\r\n2021-07-27<br/>\r\n`Added` 商品 > GET > 增加 modified_at_min 與 modified_at_max 篩選「商品更新時間」區間 <br/>\r\n`Added` 商品 > PUT > 更新庫存，返回成功 SKU 列表 <br/>\r\n2021-05-02<br/>\r\n`Added` 會員 > GET > 增加 reward 紅利累積與折抵紀錄 <br/>\r\n`Added` 會員 > POST > 新增紅利累積 或 折抵 <br/>\r\n<br/>\r\n2021-03-25<br/>\r\n`Added` 會員 > GET > 增加 Facebook User ID <br/>\r\n`Added` 會員 > GET > 增加 Line User ID <br/>\r\n`Added` 會員 > 篩選條件 > Facebook 與 Line User ID <br/>\r\n<br/>\r\n2020-12-15<br/>\r\n`Added` 訂單 > GET > 增加 convenient_store_XXXX 系列超商取貨門市資訊<br/>\r\n`Added` 訂單 > PUT > 更新訂單已付款<br/>\r\n`Added` 訂單 > PUT > 更新訂單物流貨況<br/>\r\n<br/>\r\n2020-08-07<br/>\r\n`Added` 訂單 > POST 新增訂單備註<br/>\r\n`Added` 商品 > GET > 查詢 categories 商品分類<br/>\r\n`Added` 會員 > GET > 查詢 tags 會員標籤<br/>\r\n`Added` 會員 > POST > 會員貼新的標籤<br/>\r\n<br/>\r\n2020-06-15<br/>\r\n`Added` 所有訂單狀態列表<br/>\r\n`Added` 更新訂單狀態(多筆)<br/>\r\n<br/>\r\n2020-05-07<br/>\r\n`Added` 新訂單 > Webhook > 將訂單內容 Post 至指定接收網址<br/>\r\n`Added` 新會員 > Webhook > 將會員資料 Post 至指定接收網址<br/>\r\n`Added` 訂單狀態異動 > Webhook > 將訂單內容 Post 至指定接收網址<br/>\r\n<br/>\r\n2020-04-29<br/>\r\n`Added` 商品(Products) > 新增商品基本檔(SKU, 商品名稱, 商品類別, 售價, 商品狀態, 庫存量)<br/>\r\n<br/>\r\n2020-04-24<br/>\r\n`Added` 訂單(Orders) > 更新包裹追蹤碼 > 更新 成功與失敗 的訂單集合<br/>\r\n`Added` 訂單(Orders) > 更新訂單發票號碼 > 更新 成功與失敗 的訂單集合<br/>\r\n`Added` 商品(Products) > 基本資料 > 限時特賣集合(special_offer)<br/>\r\n`Added` 商品(Products) > 限時特賣 條件(時間區間, 價格, 會員群組) > 篩選商品<br/>\r\n<br/>\r\n2020-04-22<br/>\r\n`Added` 訂單(Orders) > 批量(訂單)發票號碼更新<br/>\r\n`Added` 訂單(Orders) > 查詢退換貨申請訂單(多筆)<br/>\r\n`Added` 訂單(Orders) > 訂單基本資料 增加 退換貨項目(return_XXXX系列欄位)<br/>\r\n`Added` 商品(Products) > 條件式篩選商品(多筆)<br/>\r\n`Added` 會員(Customers) > 會員購物車內容(未結帳商品) > 購物車商品集合 & 購物車最近異動時間<br/>\r\n<br/>\r\n2020-04-09<br/>\r\n`Added` 訂單基本資料 增加 最近修改時間(date_modified)<br/>\r\n`Added` 商品基本資料 增加 最近修改時間(date_modified)<br/>\r\n<br/>\r\n2020-04-08<br/>\r\n`Added` 訂單(Orders) > 更新貨運包裹追蹤碼(批量)<br/>\r\n<br/>\r\n<br/>\r\n<br/>\r\n\r\n## Postman\r\n- 下載 Collections 測試包 [檔案連結](https://ecapis.qdm.cloud/doc/staging-QDM-EC-API-postman-collection.json.zip)\r\n- 請設定 Manage environments 環境變數(右上角點擊齒輪)\r\n- 環境變數：VARIABLE -> base_url , VALUE -> ecapis.qdm.cloud\r\n\r\n## Base URI\r\n\r\n資源存取 URIs 基底\r\n```\r\nhost: ecapis.qdm.cloud/api\r\nbasePath: v1\r\nresource: orders\r\nquery parameter: 2001095920\r\nschemes: https\r\n```\r\n>範例： &lt;scheme>://&lt;host>/&lt;basePath>/__orders/2001095920__ 取得訂單細節\r\n\r\n"
  termsOfService: 'https://qdm.tw/terms/'
  contact:
    name: QDM
    url: 'https://qdm.tw'
    email: hello@qdm.com.tw
  version: 1.0.0
  x-logo:
    url: 'https://cdn.qdm.cloud/api/doc/qdm-logo.png'
servers:
  -
    url: 'https://ecapis.qdm.cloud/v1'
    description: 'API server'
paths:
  '/webhooks/{webhookname}':
    get:
      tags:
        - 通知(Webhooks)
      summary: '取得已設定 Webhooks'
      description: ''
      parameters:
        -
          name: webhookname
          in: path
          description: '<b>網址{webhookname}參數：Webhook類型</b><br/>1. <font color=''6abd5b''>order</font> = 新訂單<br/>2. <font color=''6abd5b''>order-status-changes</font> = 訂單狀態異動(含已付款)<br/>3. <font color=''6abd5b''>order-days-after</font> = 訂單D+N天(<font color=''ff0000''>開發中</font>)<br/>4. <font color=''6abd5b''>customer</font> = 新會員(網站註冊)<br/>5. <font color=''6abd5b''>customer-modified</font> = 會員資料異動'
          required: true
          schema:
            type: string
          example: order
      responses:
        '200':
          description: 通知網址集合
          content:
            application/json:
              schema:
                properties:
                  urls: { description: '目前 HTTPS POST 通知網址', type: array, items: { type: string, format: uri } }
                type: object
                example:
                  data: { urls: ['https://your_domain.com/v1/new_order', 'https://your_domain.com/v2/new_order', 'https://your_partner_domain.com/v1/new_order'] }
      security:
        -
          JWT: []
    put:
      tags:
        - 通知(Webhooks)
      summary: '設定 Webhooks 通知'
      description: ''
      parameters:
        -
          name: webhookname
          in: path
          description: '<b>請把網址 {webhookname} 參數，改成以下的 Webhook 類型名稱，例如 /webhooks/order-status-changes </b><br/>1. <font color=''6abd5b''>order</font> = 新訂單<br/>2. <font color=''6abd5b''>order-status-changes</font> = 訂單狀態異動(含已付款)<br/>3. <font color=''6abd5b''>order-days-after</font> = 訂單D+N天<br/>4. <font color=''6abd5b''>customer</font> = 新會員(網站註冊)<br/>5. <font color=''6abd5b''>customer-modified</font> = 會員資料異動'
          required: true
          schema:
            type: string
          example: order
      requestBody:
        content:
          application/json:
            schema:
              required:
                - urls
              properties:
                urls:
                  description: "指定 HTTPS POST 通知網址 (最多 3 組) <br/>\r\n    -  order: 新訂單 POST 通知整筆訂單內容 JSON 格式請參考 [取得指定訂單(單筆)](#tag/(Orders)/paths/~1orders~1{order_id}/get)  <br/>\r\n    -  order-status-changes: 訂單狀態異動 POST 通知整筆訂單 [取得指定訂單(單筆)](#tag/(Orders)/paths/~1orders~1{order_id}/get)  <br/>\r\n    -  order-days-after: 訂單D+N通知 POST 通知整筆訂單 [取得指定訂單(單筆)](#tag/(Orders)/paths/~1orders~1{order_id}/get)  <br/>\r\n    -  customer: 新會員註冊 POST 通知整筆會員內容 JSON 格式請參考 [取得指定會員(單筆)](#tag/(Customers)/paths/~1customers~1{customer_id}/get)   <br/>\r\n    -  customer-modified: 會員資料異動 POST 通知整筆會員內容 JSON 格式請參考 [取得指定會員(單筆)](#tag/(Customers)/paths/~1customers~1{customer_id}/get) \r\n    \r\n    傳送與接收JSON：\r\n    - POST 請求標頭 'Content-Type' 為 'application/json'\r\n    - 以 raw 方式傳送 post 請求 body 的內容是一個 JSON 格式文件\r\n    - 接收端請以 JSON 形式回應 {data:'OK'}\r\n\r\n    "
                  type: array
                  items: { type: string, example: 'https://your_domain.com/v1/new_order' }
              type: object
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: '更新成功 Webhooks 筆數', type: integer }
                type: object
                example:
                  data: { rows_affected: '5' }
      security:
        -
          JWT: []
  /orders/count:
    get:
      tags:
        - 訂單(Orders)
      summary: 取得訂單總筆數
      description: ''
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - created_at_min
                - created_at_max
              properties:
                since_id:
                  description: 取得比指定訂單編號稍晚的訂單
                  type: string
                  example: '2001095920'
                created_at_min:
                  description: '起始時間：2020-01-16T10:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-16T10:15:47'
                created_at_max:
                  description: '結束時間：2020-01-25T19:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-25T19:15:47'
                status:
                  description: '訂單狀態<br/>1=待處理, 2=處理中, 3=已配送, 4=已取消, 5=已完成, 6=調貨中。或店家另新增的狀態'
                  type: integer
                  example: '6'
                payment_status:
                  description: '付款狀態：PAID=已付款, UNPAID=尚未付款'
                  type: string
                  enum: [PAID, UNPAID]
                  example: PAID
                shipping_status:
                  description: '配送狀態：PENDING=等待出貨, SHIPPED=已出貨, PICKREADY=貨到門市, DELIVERED=已取貨, EXCEPTION=配送失敗退回, ABANDONED=七天未取'
                  type: string
                  enum: [PENDING, SHIPPED, PICKREADY, DELIVERED, EXCEPTION, ABANDONED]
                  example: PICKREADY
                customer_id:
                  description: 會員編號
                  type: integer
                  example: '160028'
              type: object
      responses:
        '200':
          description: 訂單筆數
          content:
            application/json:
              schema:
                properties:
                  count: { description: 訂單筆數, type: integer }
                type: object
                example:
                  data: { count: 168 }
      security:
        -
          JWT: []
  '/orders/{order_id}':
    get:
      tags:
        - 訂單(Orders)
      summary: 取得指定訂單(單筆)
      description: ''
      parameters:
        -
          name: order_id
          in: path
          description: 訂單編號
          required: true
          schema:
            type: integer
          example: '2001095920'
      responses:
        '200':
          description: 訂單內容
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderModel'
              example:
                order_id: '1907234887'
                bb_id: '0'
                order_status: 1
                date_added: '2019-07-23T09:40:02'
                order_items:
                  - { product_id: 3, name: 'Hyperr超躍 貓咪無穀主食罐', options: [], sku: '', price: 1280, quantity: 2, total: 2560, giveaway: 0 }
                  - { product_id: 6, name: '[滿額贈] 小屋抓板', options: [], sku: '', price: 0, quantity: 2, total: 0, giveaway: 1 }
                  - { product_id: 10, name: '[滿額贈] 太空貓盆', options: [], sku: B123, price: 0, quantity: 8, total: 0, giveaway: 1 }
                  - { product_id: 25, name: '[滿額贈] 貓籃子', options: [], sku: CAT, price: 0, quantity: 8, total: 0, giveaway: 1 }
                order_subtotals:
                  - { code: sub_total, name: 商品小計, value: 2560 }
                  - { code: coupon, name: 優惠券(A1234), value: -100 }
                  - { code: cod, name: 到宅付款手續費, value: 40 }
                  - { code: shipping, name: 宅配, value: 40 }
                  - { code: promotion, name: 促銷活動折扣, value: -100 }
                  - { code: shipping, name: 折抵運費(促銷活動), value: -80 }
                  - { code: site_discount, name: '全館滿($1,000) 折扣 (10元)', value: -10 }
                  - { code: total, name: 總計, value: 2350 }
                total: 2350
                currency_code: TWD
                coupon_code_used: A1234
                reward_used: 0
                reward_bonus: 0
                promotion_discount_total: 210
                shipping_fee: 0
                payment_code: cod
                payment_method: 到宅付款手續費
                shipping_code: home
                shipping_method: 宅配
                customer_id: 14
                customer_group_id: 9
                regular_customer: 1
                payment_name: QDM
                payment_email: hello@qdm.com.tw
                payment_telephone: '0911111111'
                comment: ''
                customer_ip_address: 8.8.8.8
                customer_user_agent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36'
                shipping_name: test
                shipping_telephone: '0911111111'
                shipping_country: Taiwan
                shipping_postcode: 600
                shipping_zone: 高雄市
                shipping_address: 鼓山區明誠三路677號
                pickup_point: ''
                shipping_deliver_period: '00:00:00'
                shipping_deliver_ondate: '0000-00-00'
                shipping_status: PENDING
                tracking_number: ''
                payment_status: UNPAID
                payment_time: '0000-00-00T00:00:00'
                payment_banks: ''
                payment_account: ''
                invoice_number: ''
                invoice_type: 1
                invoice_randomnumber: ''
                invoice_vat_number: ''
                invoice_carrier_num: ''
                invoice_lovecode: ''
                invoice_title: ''
                invoice_address: ''
                invoice_created_at: '0000-00-00T00:00:00'
                ma_rid: ''
                ma_click_id: ''
                line_ecid: ''
                utm_source: ''
                utm_medium: ''
                utm_campaign: ''
                utm_content: ''
                utm_term: ''
                affiliate_id: '0'
                date_modified: '0000-00-00T00:00:00'
      security:
        -
          JWT: []
  /orders:
    get:
      tags:
        - 訂單(Orders)
      summary: 條件式篩選訂單(多筆)
      description: ''
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - created_at_min
                - created_at_max
              properties:
                since_id:
                  description: 取得比指定訂單編號稍晚的訂單
                  type: string
                  example: '2001095920'
                created_at_min:
                  description: '起始時間：2020-01-16T10:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-16T10:15:47'
                created_at_max:
                  description: '結束時間：2020-01-25T19:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-25T19:15:47'
                modified_at_min:
                  description: '修改日期起始時間：2020-01-16T10:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-16T10:15:47'
                modified_at_max:
                  description: '修改日期結束時間：2020-01-25T19:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-25T19:15:47'
                status:
                  description: '訂單狀態<br/>1=待處理, 2=處理中, 3=已配送, 4=已取消, 5=已完成, 6=調貨中。或店家另新增的狀態'
                  type: integer
                  example: '6'
                include_canceled_orders:
                  description: 顯示已取消訂單？預設篩選結果排除「已取消(4)」狀態的訂單
                  type: boolean
                  default: fasle
                  enum: ['true', fasle]
                  example: 'false'
                orders_by_coupon_not_used:
                  description: 只篩選未使用優惠券的訂單
                  type: boolean
                  default: fasle
                  enum: ['true', fasle]
                  example: 'false'
                payment_status:
                  description: '付款狀態：PAID=已付款, UNPAID=尚未付款'
                  type: string
                  enum: [PAID, UNPAID]
                  example: PAID
                shipping_status:
                  description: '配送狀態：PENDING=等待出貨, SHIPPED=已出貨, PICKREADY=貨到門市, DELIVERED=已取貨, EXCEPTION=配送失敗退回, ABANDONED=七天未取'
                  type: string
                  enum: [PENDING, SHIPPED, PICKREADY, DELIVERED, EXCEPTION, ABANDONED]
                  example: PICKREADY
                shipping_type:
                  description: 配送方式<br/>可輸入配送方式關鍵字，例如：搜尋全家常溫、冷凍，可輸入「全家」
                  type: string
                  example: 全家
                customer_id:
                  description: 會員編號
                  type: integer
                  example: '160028'
                page_size:
                  description: 每頁筆數(上限300筆)
                  type: integer
                  default: '300'
                  example: '50'
                page_number:
                  description: 從第幾頁開始
                  type: integer
                  default: '1'
                  example: '3'
              type: object
      responses:
        '200':
          description: 訂單集合
          content:
            application/json:
              schema:
                properties:
                  count: { description: 擷取訂單數, type: integer }
                  total_count: { description: 總訂單數, type: integer }
                  search_criteria: { description: 分頁參數, type: array, items: { $ref: '#/components/schemas/ResultPaginationModel' } }
                  result: { description: 訂單集合, type: array, items: { $ref: '#/components/schemas/OrderModel' } }
                type: object
      security:
        -
          JWT: []
  /orders/return:
    get:
      tags:
        - 訂單(Orders)
      summary: 退換貨申請訂單(多筆)
      description: ''
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - created_at_min
                - created_at_max
              properties:
                created_at_min:
                  description: '申請日期起始時間：2020-01-16T10:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-16T10:15:47'
                created_at_max:
                  description: '申請日期結束時間：2020-01-25T19:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-25T19:15:47'
                status:
                  description: '退換貨處理狀態<br/>1=待處理, 2=等待商品到貨, 3=已完成'
                  type: integer
                  example: '6'
                payment_status:
                  description: '付款狀態：PAID=已付款, UNPAID=尚未付款'
                  type: string
                  enum: [PAID, UNPAID]
                  example: PAID
                customer_id:
                  description: 會員編號
                  type: integer
                  example: '160028'
                page_size:
                  description: 每頁筆數(上限300筆)
                  type: integer
                  default: '300'
                  example: '50'
                page_number:
                  description: 從第幾頁開始
                  type: integer
                  default: '1'
                  example: '3'
              type: object
      responses:
        '200':
          description: 退換貨訂單集合
          content:
            application/json:
              schema:
                properties:
                  count: { description: 擷取訂單數, type: integer }
                  total_count: { description: 總訂單數, type: integer }
                  search_criteria: { description: 分頁參數, type: array, items: { $ref: '#/components/schemas/ResultPaginationModel' } }
                  result: { description: 訂單集合, type: array, items: { $ref: '#/components/schemas/OrderModel' } }
                type: object
      security:
        -
          JWT: []
  /orders/status:
    get:
      tags:
        - 訂單(Orders)
      summary: 所有訂單狀態列表
      description: ''
      responses:
        '200':
          description: 狀態列表
          content:
            application/json:
              schema:
                description: 狀態列表
                type: array
                items:
                  allOf: [{ properties: { order_status_id: { description: 訂單狀態編號, type: integer }, name: { description: 訂單狀態名稱, type: string } }, type: object }]
      security:
        -
          JWT: []
    put:
      tags:
        - 訂單(Orders)
      summary: 更新訂單狀態
      description: '異動訂單的狀態<br/>「已完成」觸發:會員升降等/紅利發放/首購送紅利。<br/>「發票開立」依據後台套件設定的自動開立發票時機：已完成 或 已付款。<br/>「受眾輪廓與接觸中心」：連動「自動-訂單狀態變更」事件。'
      requestBody:
        request: skus
        description: 訂單清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: 訂單清單
              type: array
              items:
                allOf:
                  - { required: [order_id, order_status_id], properties: { order_id: { description: 訂單編號, type: integer }, order_status_id: { description: 新的訂單狀態編號, type: integer } }, type: object }
              example:
                -
                  order_id: '2002246896'
                  order_status_id: 3
                -
                  order_id: '2002206157'
                  order_status_id: 5
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 更新成功訂單數量, type: integer }
                  order_id_list: { description: 更新成功的訂單集合, type: array, items: {  } }
                  rejection_list: { description: 更新失敗的訂單集合, type: array, items: {  } }
                type: object
                example:
                  data: { rows_affected: '2', order_id_list: [{ order_id: '1906182387' }, { order_id: '2004166906' }], rejection_list: [{ order_id: '2003266801' }] }
      security:
        -
          JWT: []
  /orders/return_status:
    put:
      tags:
        - 訂單(Orders)
      summary: 更新退換貨狀態
      description: '僅異動退換貨的狀態，<font color=''red''>不會額外異動觸發:會員升降等/發票開立/紅利發放</font>'
      requestBody:
        description: 退換貨清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: 退換貨清單
              type: array
              items:
                allOf:
                  - { required: [return_id, return_status_id], properties: { return_id: { description: 退換貨單號, type: integer }, return_status_id: { description: '退換貨處理狀態<br/>1=待處理, 2=等待商品到貨, 3=已完成', type: integer } }, type: object }
              example:
                -
                  return_id: '2002246896'
                  return_status_id: 3
                -
                  return_id: '2002206157'
                  return_status_id: 2
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 更新成功退換貨單數量, type: integer }
                  return_id_list: { description: 更新成功的退換貨單集合, type: array, items: {  } }
                  rejection_list: { description: 更新失敗的退換貨單集合, type: array, items: {  } }
                type: object
                example:
                  data: { rows_affected: '2', return_id_list: [{ return_id: '1906182387' }, { return_id: '2004166906' }], rejection_list: [{ return_id: '2003266801' }] }
      security:
        -
          JWT: []
  '/orders/{order_id}/delivery':
    get:
      tags:
        - 訂單(Orders)
      summary: 查詢包裹配送進度
      description: ''
      parameters:
        -
          name: order_id
          in: path
          description: 訂單編號
          required: true
          schema:
            type: integer
          example: '2001095920'
      responses:
        '200':
          description: 配送進度歷程(新>舊)
          content:
            application/json:
              schema:
                description: 包裹配送進度歷程
                type: array
                items:
                  $ref: '#/components/schemas/DeliverStatusModel'
      security:
        -
          JWT: []
  /orders/shipping_status:
    put:
      tags:
        - 訂單(Orders)
      summary: 更新物流貨況
      description: ''
      requestBody:
        request: skus
        description: 訂單清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: 訂單清單
              type: array
              items:
                allOf:
                  - { required: [order_id, shipping_status], properties: { order_id: { description: 訂單編號, type: integer }, shipping_status: { description: '物流貨況狀態：PENDING=等待出貨, SHIPPED=已出貨, PICKREADY=貨到門市, DELIVERED=已取貨, EXCEPTION=配送失敗退回, ABANDONED=七天未取', type: string, enum: [PENDING, SHIPPED, PICKREADY, DELIVERED, EXCEPTION, ABANDONED], example: PICKREADY } }, type: object }
              example:
                -
                  order_id: '2002246896'
                  shipping_status: SHIPPED
                -
                  order_id: '2002206157'
                  shipping_status: PICKREADY
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 更新成功訂單數量, type: integer }
                  order_id_list: { description: 更新成功的訂單集合, type: array, items: {  } }
                  rejection_list: { description: 更新失敗的訂單集合, type: array, items: {  } }
                type: object
                example:
                  data: { rows_affected: '2', order_id_list: [{ order_id: '1906182387' }, { order_id: '2004166906' }], rejection_list: [{ order_id: '2003266801' }] }
      security:
        -
          JWT: []
  /orders/tracking:
    put:
      tags:
        - 訂單(Orders)
      summary: 更新包裹追蹤碼
      description: ''
      requestBody:
        request: skus
        description: 訂單清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: 訂單清單
              type: array
              items:
                $ref: '#/components/schemas/OrderTracksPutModel'
              example:
                -
                  order_id: '2002246896'
                  tracking_number: GM99999999999
                  ship_date: '2022-06-06'
                -
                  order_id: '2002206157'
                  tracking_number: 3SBCC000123456
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 更新成功訂單數量, type: integer }
                  order_id_list: { description: 更新成功的訂單集合, type: array, items: {  } }
                  rejection_list: { description: 更新失敗的訂單集合, type: array, items: {  } }
                type: object
                example:
                  data: { rows_affected: '2', order_id_list: [{ order_id: '1906182387' }, { order_id: '2004166906' }], rejection_list: [{ order_id: '2003266801' }] }
      security:
        -
          JWT: []
  /orders/invoice:
    put:
      tags:
        - 訂單(Orders)
      summary: 更新訂單發票號碼
      description: ''
      requestBody:
        request: order_id
        description: 訂單清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: 訂單清單
              type: array
              items:
                $ref: '#/components/schemas/OrderInvoicePutModel'
              example:
                -
                  order_id: '2002246896'
                  invoice_number: YQ74130001
                  random_number: '1234'
                -
                  order_id: '2002206157'
                  invoice_number: YQ74130002
                  random_number: '1234'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 更新成功訂單數量, type: integer }
                  order_id_list: { description: 更新成功的訂單集合, type: array, items: {  } }
                  rejection_list: { description: 更新失敗的訂單集合, type: array, items: {  } }
                type: object
                example:
                  data: { rows_affected: '2', order_id_list: [{ order_id: '1906182387' }, { order_id: '2004166906' }], rejection_list: [{ order_id: '2003266801' }] }
      security:
        -
          JWT: []
  /orders/comment:
    post:
      tags:
        - 訂單(Orders)
      summary: 新增訂單備註
      description: ''
      requestBody:
        request: order_id
        description: 訂單清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: 訂單清單
              type: array
              items:
                $ref: '#/components/schemas/OrderCommentPostModel'
              example:
                -
                  order_id: '2002246896'
                  comment: 訂單備註內容說明A
                -
                  order_id: '2002206157'
                  comment: 訂單備註內容說明B
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 更新成功訂單數量, type: integer }
                  order_id_list: { description: 更新成功的訂單集合, type: array, items: {  } }
                  rejection_list: { description: 更新失敗的訂單集合, type: array, items: {  } }
                type: object
                example:
                  data: { rows_affected: '2', order_id_list: [{ order_id: '1906182387' }, { order_id: '2004166906' }], rejection_list: [{ order_id: '2003266801' }] }
      security:
        -
          JWT: []
  /orders/payment_status:
    put:
      tags:
        - 訂單(Orders)
      summary: 更新訂單已付款
      description: ''
      requestBody:
        request: order_id
        description: 訂單清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: 訂單清單
              type: array
              items:
                $ref: '#/components/schemas/OrderPaymentStatusPutModel'
              example:
                -
                  order_id: '2002246896'
                  payment_remark: 付款銀行帳號或其它備註(25個中文字)
                  payment_time: 'YYYY-MM-DDTHH:ii:ss'
                -
                  order_id: '2002206157'
                  payment_remark: 付款銀行帳號或其它備註(25個中文字)
                  payment_time: 'YYYY-MM-DDTHH:ii:ss'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 更新成功訂單數量, type: integer }
                  order_id_list: { description: 更新成功的訂單集合, type: array, items: {  } }
                  rejection_list: { description: 更新失敗的訂單集合, type: array, items: {  } }
                type: object
                example:
                  data: { rows_affected: '2', order_id_list: [{ order_id: '1906182387' }, { order_id: '2004166906' }], rejection_list: [{ order_id: '2003266801' }] }
      security:
        -
          JWT: []
  /orders/new:
    post:
      tags:
        - 訂單(Orders)
      summary: 新增訂單
      description: ''
      requestBody:
        content:
          application/json:
            schema:
              required:
                - customer_telephone
                - order_total
                - payment_method
                - shipping_method
              properties:
                merchant_order_id:
                  description: 廠商訂單編號
                  type: string
                  example: AB9812-32_12
                customer_telephone:
                  description: 會員手機號碼
                  type: string
                  example: '0988123123'
                order_total:
                  description: 訂單金額
                  type: integer
                  example: '1800'
                invoice_number:
                  description: 發票號碼
                  type: string
                  example: NK32526638
                payment_method:
                  description: 付款方式
                  type: string
                  example: 信用卡
                shipping_method:
                  description: 配送方式
                  type: string
                  example: 宅配
                email:
                  description: email
                  type: string
                  example: 123@abc.cc
                ez_ship_status:
                  description: '便利配 配送狀態'
                  type: string
                tracking_number:
                  description: 包裹追蹤碼
                  type: string
                tracking_status:
                  description: '包裹追蹤狀態：PENDING=等待出貨, SHIPPED=已出貨, PICKREADY=貨到門市, DELIVERED=已取貨, EXCEPTION=配送失敗退回, ABANDONED=七天未取'
                  type: string
                  enum: [PENDING, SHIPPED, PICKREADY, DELIVERED, EXCEPTION, ABANDONED]
                  example: PICKREADY
                parent_id:
                  description: ''
                  type: string
                affiliate_id:
                  description: '分銷合作 KOL專屬編號'
                  type: string
                bb_id:
                  description: 'Buy Button 專屬編號'
                  type: string
                ma_rid:
                  description: '美安 rid'
                  type: string
                ma_click_id:
                  description: '美安 click_id'
                  type: string
                ichannels_gid:
                  description: ichannels_gid
                  type: string
                line_ecid:
                  description: 'LINE購物 ecid'
                  type: string
                ec_id:
                  description: '導購追蹤識別碼 global unique identifier'
                  type: string
                total_info:
                  description: 訂單總計
                  properties: { shipping_title: { title: '例如: 宅配、超商取貨...等', description: 商品運送方式, type: string, example: 宅配 }, shipping_fee: { description: 運費, type: integer, example: 80 } }
                  type: object
                product_info:
                  description: 商品資訊集合
                  type: array
                  items: { allOf: [{ properties: { id: { description: 商品ID, type: integer, example: '20' }, quantity: { description: 商品數量, type: integer, example: 3 }, product_ov_id: { title: '多個以'',''逗號隔開', description: 商品購物選項值, type: string, example: '15,18' } }, type: object }] }
                utm_info:
                  description: UTM參數
                  properties: { medium: { description: utm_medium, type: string, example: '' }, campaign: { description: utm_campaign, type: string, example: '' }, term: { description: utm_term, type: string, example: '' } }
                  type: object
                payment_info:
                  description: 付款資訊
                  properties: { firstname: { description: 購買人姓名, type: string, example: '' }, status: { description: '付款狀態：PAID=已付款, UNPAID=尚未付款', type: string, enum: [PAID, UNPAID], example: PAID }, time: { description: 付款時間, type: string, format: data-time, default: 'Y-m-d H:i:s', example: '2024-01-15 10:59:59' }, banks: { title: '例如：綠界金流訂單編號:2001211526268401', description: 付款來源, type: string, example: '' }, account: { title: '例如：卡片的末 4 碼:5006', description: 付款帳號, type: string, example: '' }, address: { description: 付款地址, type: string, example: '' }, postcode: { description: 郵遞區號, type: string, example: '' }, country_id: { description: 國家ID(預設Taiwan), type: integer, default: 206, example: 206 }, zone_id: { description: 地區ID(預設自訂地址), type: integer, default: 3157, example: 3157 } }
                  type: object
                shipping_info:
                  description: 配送資訊
                  properties: { firstname: { description: 收件人姓名, type: string, example: '' }, address: { description: 包裹寄送地址, type: string, example: '' }, deliver_ondate: { description: 指定到貨日期, type: string, format: date, default: YYYY-MM-DD, example: '20240115' }, postcode: { description: 郵遞區號, type: string, example: '' }, country_id: { description: 配送國家ID(預設Taiwan), type: integer, default: 206, example: 206 }, zone_id: { description: 配送地區ID(預設自訂地址), type: integer, default: 3157, example: 3157 }, telephone: { description: 收件人手機號碼, type: string, example: '' } }
                  type: object
                invoice_info:
                  description: 發票資訊
                  properties: { name: { description: 發票持有人姓名, type: string, example: '' }, address: { description: 發票地址, type: string, example: '' }, vat_number: { description: 統一編號, type: string, example: '' }, telephone: { description: 手機號碼, type: string, example: '' }, title: { description: 發票抬頭, type: string, example: '' }, type: { description: '發票類型 (0=不開發票, 1=二聯式, 2=三聯式)', type: integer, default: '0', enum: [0, 1, 2], example: 0 }, datetime: { description: 發票開立時間, type: string, format: date-time, default: 'Y-m-d H:i:s', example: '2024-01-15 10:59:59' }, random_number: { description: 發票隨機碼, type: string, example: '' }, memo: { description: 發票備註, type: string, example: '' }, lovecode: { description: 捐贈愛心碼, type: string, example: '' }, carrier_num: { description: 發票載具, type: string, example: '' } }
                  type: object
              type: object
      responses:
        '200':
          description: 訂單新增成功
          content:
            application/json:
              schema:
                properties:
                  order_id: { description: QDM訂單編號, type: string }
                  merchant_order_id: { description: 廠商訂單編號, type: string }
                type: object
                example:
                  data: { order_id: '2306192091', merchant_order_id: ABC123-12_25, message: '' }
      security:
        -
          JWT: []
  /products/count:
    get:
      tags:
        - 商品(Products)
      summary: 取得商品總筆數
      description: ''
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required: []
              properties:
                name:
                  description: '商品名稱 (可用 * 模糊查询 ex: 貓*盆)'
                  type: string
                  example: '貓*盆'
                sku:
                  description: '商品主SKU 或 變體SKU (可用 * 模糊查询)'
                  type: string
                  example: 'ABC-*-586'
                price:
                  description: '價格區間 (ex: 300-1500)'
                  type: string
                  example: 300-1500
                available_at_min:
                  description: '上架時間 (區間起始)：2020-01-16T10:15:47'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-16T10:15:47'
                available_at_max:
                  description: '上架時間 (區間結束)：2020-01-25T19:15:47'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-25T19:15:47'
                disavailable_at_min:
                  description: '下架時間 (區間起始)：2020-01-16T10:15:47'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-16T10:15:47'
                disavailable_at_max:
                  description: '下架時間 (區間結束)：2020-01-25T19:15:47'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-25T19:15:47'
                modified_at_min:
                  description: '商品更新時間 (區間起始)：2020-01-16T10:15:47'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-16T10:15:47'
                modified_at_max:
                  description: '商品更新時間 (區間結束)：2020-01-25T19:15:47'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-25T19:15:47'
                status:
                  description: '啟用狀態<br/>1=啟用, 0=停用'
                  type: integer
                  example: '1'
                no_index:
                  description: '隱藏模式<br/>1=隱藏不曝光, 0=正常顯示'
                  type: integer
                  example: '0'
                quantity:
                  description: '總庫存量區間 (ex: 50-999)'
                  type: string
                  example: 50-999
                special_price:
                  description: '<b>限時特賣</b>-價格區間 (ex: 300-1500)'
                  type: string
                  example: 300-1500
                special_customer_group_id:
                  description: '<b>限時特賣</b>-適用會員群組編號'
                  type: integer
                  example: -1
                special_available_at_min:
                  description: '<b>限時特賣</b>-開始日期 (區間起始)：2020-01-16'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-16T10:15:47'
                special_available_at_max:
                  description: '<b>限時特賣</b>-開始日期 (區間結束)：2020-01-25'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-25T19:15:47'
                special_disavailable_at_min:
                  description: '<b>限時特賣</b>-截止日期 (區間起始)：2020-01-16'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-16T10:15:47'
                special_disavailable_at_max:
                  description: '<b>限時特賣</b>-截止日期 (區間結束)：2020-01-25'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-25T19:15:47'
              type: object
      responses:
        '200':
          description: 商品筆數
          content:
            application/json:
              schema:
                properties:
                  count: { description: 商品筆數, type: integer }
                type: object
                example:
                  data: { count: 168 }
      security:
        -
          JWT: []
  '/products/sku/{sku}':
    get:
      tags:
        - 商品(Products)
      summary: 查詢商品基本資料(SKU)
      description: ''
      parameters:
        -
          name: sku
          in: path
          description: '商品貨號 (SKU關鍵字)'
          required: true
          schema:
            type: string
            pattern: '^[0-9a-zA-Z\-_]$'
          example: S12T-MED
      responses:
        '200':
          description: '符合 SKU 關鍵字的商品集合'
          content:
            application/json:
              schema:
                description: '符合 SKU 關鍵字的商品集合'
                type: array
                items:
                  $ref: '#/components/schemas/ProductModel'
      security:
        -
          JWT: []
  '/products/id/{product_id}':
    get:
      tags:
        - 商品(Products)
      summary: 查詢商品基本資料(ID)
      description: ''
      parameters:
        -
          name: product_id
          in: path
          description: 商品編號
          required: true
          schema:
            type: integer
          example: '126'
      responses:
        '200':
          description: 商品內容
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductModel'
      security:
        -
          JWT: []
  /products:
    get:
      tags:
        - 商品(Products)
      summary: 條件式篩選商品(多筆)
      description: ''
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required: []
              properties:
                name:
                  description: '商品名稱 (可用 * 模糊查询 ex: 貓*盆)'
                  type: string
                  example: '貓*盆'
                sku:
                  description: '商品主SKU 或 變體SKU (可用 * 模糊查询)'
                  type: string
                  example: 'ABC-*-586'
                price:
                  description: '價格區間 (ex: 300-1500)'
                  type: string
                  example: 300-1500
                available_at_min:
                  description: '上架時間 (區間起始)：2020-01-16T10:15:47'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-16T10:15:47'
                available_at_max:
                  description: '上架時間 (區間結束)：2020-01-25T19:15:47'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-25T19:15:47'
                disavailable_at_min:
                  description: '下架時間 (區間起始)：2020-01-16T10:15:47'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-16T10:15:47'
                disavailable_at_max:
                  description: '下架時間 (區間結束)：2020-01-25T19:15:47'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-25T19:15:47'
                modified_at_min:
                  description: '商品更新時間 (區間起始)：2020-01-16T10:15:47'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-16T10:15:47'
                modified_at_max:
                  description: '商品更新時間 (區間結束)：2020-01-25T19:15:47'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-25T19:15:47'
                status:
                  description: '啟用狀態<br/>1=啟用, 0=停用'
                  type: integer
                  example: '1'
                no_index:
                  description: '隱藏模式<br/>1=隱藏不曝光, 0=正常顯示'
                  type: integer
                  example: '0'
                quantity:
                  description: '總庫存量區間 (ex: 50-999)'
                  type: string
                  example: 50-999
                special_price:
                  description: '<b>限時特賣</b>-價格區間 (ex: 300-1500)'
                  type: string
                  example: 300-1500
                special_customer_group_id:
                  description: '<b>限時特賣</b>-適用會員群組編號'
                  type: integer
                  example: -1
                special_available_at_min:
                  description: '<b>限時特賣</b>-開始日期 (區間起始)：2020-01-16'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-16T10:15:47'
                special_available_at_max:
                  description: '<b>限時特賣</b>-開始日期 (區間結束)：2020-01-25'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-25T19:15:47'
                special_disavailable_at_min:
                  description: '<b>限時特賣</b>-截止日期 (區間起始)：2020-01-16'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-16T10:15:47'
                special_disavailable_at_max:
                  description: '<b>限時特賣</b>-截止日期 (區間結束)：2020-01-25'
                  type: string
                  format: date-time
                  default: 'YYYY-MM-DDTHH:ii:ss'
                  example: '2020-01-25T19:15:47'
                page_size:
                  description: 每頁筆數(上限300筆)
                  type: integer
                  default: '300'
                  example: '50'
                page_number:
                  description: 從第幾頁開始
                  type: integer
                  default: '1'
                  example: '3'
              type: object
      responses:
        '200':
          description: 商品集合
          content:
            application/json:
              schema:
                properties:
                  count: { description: 擷取商品數, type: integer }
                  total_count: { description: 總商品數, type: integer }
                  search_criteria: { description: 分頁參數, type: array, items: { $ref: '#/components/schemas/ResultPaginationModel' } }
                  result: { description: 商品集合, type: array, items: { $ref: '#/components/schemas/ProductModel' } }
                type: object
      security:
        -
          JWT: []
    post:
      tags:
        - 商品(Products)
      summary: 新增商品
      description: ''
      requestBody:
        content:
          application/json:
            schema:
              properties:
                products:
                  description: 商品集合
                  type: array
                  items: { allOf: [{ required: [sku, name], properties: { sku: { title: SKU不可重複, description: 主商品SKU, type: string, example: S12T }, name: { description: 商品名稱, type: string, example: 義士大廚上湯鮮燉包 }, price: { title: 新台幣, description: 售價, type: integer, example: '1280' }, min_quantity: { description: 安全庫存量, type: integer, example: 99 }, quantity: { description: 庫存量, type: integer, example: '999' }, product_category: { description: '商品類別<br/><br/>- 分隔號「,」表示多組類別，階層號「>」表示子類別。<br/>- 自動建立不存在的類別名稱(預設不顯示於網站主選單)<br/>- 大小寫有關(case sensitive)<br/><br/><b>範例：</b>Food,Beverages,Tobacco > Beverages > Alcoholic Beverages', type: string, example: 'Food, Beverages, Tobacco > Beverages > Alcoholic Beverages' }, status: { title: '預設停用/商店不顯示, true=啟用, false＝停用', description: 啟用狀態, type: boolean, example: 'true' }, no_index: { title: '預設正常顯示, true=隱藏不曝光, false＝正常顯示', description: 隱藏模式, type: boolean, example: 'true' }, cost: { description: 成本, type: integer, example: 280 }, upc: { description: upc, type: string, example: '' }, ean: { description: ean, type: string, example: '' }, jan: { description: jan, type: string, example: '' }, mpn: { description: mpn, type: string, example: '' }, isbn: { description: isbn, type: string, example: '' }, minimum: { description: 最小購買量, type: integer, example: 3 }, maxmum: { description: 最大購買量, type: integer, example: 6 }, sort_order: { title: 排序由大至小, description: 商品主排序, type: integer, default: 0, example: 0 }, date_availiable: { description: 商品上架時間, type: string, default: 'Y-m-d H:i:s', example: '2024-01-01 09:00:00' }, date_disavailiable: { description: 商品下架時間, type: string, default: '2100-12-30 23:59:59', example: '2024-12-31 23:59:59' }, model: { description: 商品規格/型號, type: string, example: '' }, feature: { description: 商品特色, type: string, example: '' }, weight: { title: 單位：公斤, description: 重量, type: float, example: 15 }, length: { title: 單位：公分, description: '材積尺寸 - 長度', type: float, example: 12 }, width: { title: 單位：公分, description: '材積尺寸 - 寬度', type: float, example: 12 }, height: { title: 單位：公分, description: '材積尺寸 - 高度', type: float, example: 12 }, tax_class_id: { title: '0=應稅, 2=零稅率, 3=免稅', description: 課稅類別(開立電子發票的商品課稅別), type: integer, default: 0, example: 0 }, product_option: { description: 商品購物選項, type: array, items: { allOf: [{ properties: { option_id: { title: 需要先在後台建立購物選項取得選項ID, description: 選項ID, type: integer, example: 1 }, show_label: { title: '預設正常顯示, true=顯示, false＝關閉顯示', description: 顯示價格標籤, type: boolean, example: 'true' }, show_add_quantity: { title: '預設關閉顯示, true=顯示, false＝關閉顯示', description: 顯示自訂選項數量, type: boolean, example: 'false' } }, type: object }] } }, seo_description: { description: SEO微資料標記, properties: { meta_description: { description: 商品短描述, type: string, example: '' }, meta_keyword: { description: '商品名稱 & 商品頁標題', type: string, example: '' }, tag: { title: 關鍵字以(逗點)隔開, description: 商品關鍵字標籤, type: string, example: 'tag1,tag2,tag3' } }, type: object } }, type: object }] }
              type: object
      responses:
        '200':
          description: 商品新增成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 成功新增筆數, type: integer }
                  product_add_list: { description: 新增成功的商品SKU集合, type: array, items: {  } }
                  rejection_list: { description: 新增失敗的商品SKU集合, type: array, items: {  } }
                type: object
                example:
                  data: { rows_affected: '12', product_add_list: [{ sku: T208, product_id: 123 }, { sku: C308, product_id: 124 }, { sku: F508, product_id: 125 }], rejection_list: [{ sku: F509, message: 'error message' }, { sku: F511, message: 'error message' }] }
      security:
        -
          JWT: []
  /products/status/disabled:
    get:
      tags:
        - 商品(Products)
      summary: 查詢停用狀態的所有商品ID
      description: ''
      responses:
        '200':
          description: 停用狀態的商品ID集合
          content:
            application/json:
              schema:
                properties:
                  count: { description: 停用商品數, type: integer }
                  product_id_list: { description: 商品ID集合, type: array, items: {  } }
                type: object
                example:
                  data: { count: '2', product_id_list: ['127', '586'] }
      security:
        -
          JWT: []
  /products/inventory:
    put:
      tags:
        - 商品(Products)
      summary: 更新商品庫存
      description: ''
      requestBody:
        request: skus
        description: SKU清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: SKU清單
              type: array
              items:
                $ref: '#/components/schemas/ProductVariantsInventoryPutModel'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  product_sku_list: { description: 更新成功的SKU集合, type: array, items: {  } }
                  rows_affected: { description: 更新成功商品庫存, type: integer }
                type: object
                example:
                  data: { product_sku_list: [S12TMEDWHICOT, S12TABC555], rows_affected: '2' }
      security:
        -
          JWT: []
  /products/specialoffer:
    get:
      tags:
        - 商品(Products)
      summary: 查詢限時特賣(直購價)
      description: ''
      requestBody:
        request: products
        description: 商品清單
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              properties:
                page_size:
                  description: 每頁筆數(上限300筆)
                  type: integer
                  default: '300'
                  example: '50'
                page_number:
                  description: 從第幾頁開始
                  type: integer
                  default: '1'
                  example: '3'
                result:
                  description: '商品編號集合(使用半形逗號隔開,查詢全部限時特賣請留空)'
                  type: string
                  example: '116,181,121'
              type: object
      responses:
        '200':
          description: 商品集合
          content:
            application/json:
              schema:
                properties:
                  count: { description: 擷取商品數, type: integer }
                  total_count: { description: 總商品數, type: integer }
                  search_criteria: { description: 分頁參數, type: array, items: { $ref: '#/components/schemas/ResultPaginationModel' } }
                  result: { description: 商品集合, type: array, items: { allOf: [{ properties: { product_id: { description: 商品編號, type: integer, example: '126' }, special_offer: { description: 限時特賣集合, type: array, items: { $ref: '#/components/schemas/ProductSpecialOfferModel' } } }, type: object }] } }
                type: object
      security:
        -
          JWT: []
    put:
      tags:
        - 商品(Products)
      summary: 新增/更新限時特賣(直購價)
      description: ''
      requestBody:
        request: products
        description: 商品清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: 商品清單
              type: array
              items:
                $ref: '#/components/schemas/ProductSpecialModel'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 更新成功商品限時特賣(若設定不保留則包含刪除筆數), type: integer }
                type: object
                example:
                  data: { rows_affected: '5' }
      security:
        -
          JWT: []
  /products/delspecialoffer:
    delete:
      tags:
        - 商品(Products)
      summary: 刪除限時特賣(直購價)
      description: ''
      requestBody:
        request: products
        description: 商品清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: 商品清單
              type: array
              items:
                $ref: '#/components/schemas/DelProductSpecialModel'
      responses:
        '200':
          description: 刪除成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 成功刪除商品限時特賣, type: integer }
                type: object
                example:
                  data: { rows_affected: '2' }
      security:
        -
          JWT: []
  /products/sku/update:
    put:
      tags:
        - 商品(Products)
      summary: 更新商品SKU
      description: '更新已有設定的 主商品SKU 或 變體SKU'
      requestBody:
        request: skus
        description: SKU清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: SKU清單
              type: array
              items:
                $ref: '#/components/schemas/ProductVariantsSKUPutModel'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 更新成功商品SKU, type: integer }
                type: object
                example:
                  data: { rows_affected: '1' }
      security:
        -
          JWT: []
  '/products/{product_id}':
    put:
      tags:
        - 商品(Products)
      summary: 更新商品
      description: 更新商品的基本資訊，支援與新增商品相同的欄位
      parameters:
        -
          name: product_id
          in: path
          description: 商品編號
          required: true
          schema:
            type: integer
          example: '126'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  description: 商品名稱
                  type: string
                  example: 更新後的商品名稱
                description:
                  description: 商品介紹
                  type: string
                  example: 更新後的商品介紹
                feature:
                  description: 商品特色
                  type: string
                  example: 更新後的商品特色
                price:
                  description: 售價
                  type: integer
                  example: '1500'
                quantity:
                  description: 庫存量
                  type: integer
                  example: '100'
                min_quantity:
                  description: 安全庫存量
                  type: integer
                  example: '10'
                status:
                  description: 啟用狀態
                  type: boolean
                  example: 'true'
                no_index:
                  description: 隱藏模式
                  type: boolean
                  example: 'false'
                cost:
                  description: 成本
                  type: integer
                  example: '800'
                upc:
                  description: UPC條碼
                  type: string
                  example: ''
                ean:
                  description: EAN條碼
                  type: string
                  example: ''
                jan:
                  description: JAN條碼
                  type: string
                  example: ''
                mpn:
                  description: MPN製造商零件號
                  type: string
                  example: ''
                isbn:
                  description: ISBN國際標準書號
                  type: string
                  example: ''
                minimum:
                  description: 最小購買量
                  type: integer
                  example: '1'
                maxmum:
                  description: 最大購買量
                  type: integer
                  example: '999'
                date_available:
                  description: 商品上架時間
                  type: string
                  format: date-time
                  example: '2024-01-01 09:00:00'
                date_disavailable:
                  description: 商品下架時間
                  type: string
                  format: date-time
                  example: '2024-12-31 23:59:59'
                model:
                  description: 商品規格/型號
                  type: string
                  example: MODEL-2024
                weight:
                  description: 重量(公斤)
                  type: number
                  format: float
                  example: '1.5'
                length:
                  description: 長度(公分)
                  type: number
                  format: float
                  example: '20.0'
                width:
                  description: 寬度(公分)
                  type: number
                  format: float
                  example: '15.0'
                height:
                  description: 高度(公分)
                  type: number
                  format: float
                  example: '10.0'
                tax_class_id:
                  description: 課稅類別
                  type: integer
                  enum: [0, 2, 3]
                  example: '0'
                seo_description:
                  description: SEO微資料標記
                  properties: { meta_description: { description: 商品短描述, type: string, example: 這是商品的SEO描述 }, meta_keyword: { description: 商品關鍵字, type: string, example: 商品關鍵字 }, tag: { description: 商品標籤, type: string, example: 'tag1,tag2,tag3' } }
                  type: object
              type: object
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  product_id: { description: 商品編號, type: integer }
                  message: { description: 更新結果訊息, type: string }
                  rows_affected: { description: 影響的資料筆數, type: integer }
                type: object
                example:
                  data: { product_id: 126, message: 'Product updated successfully', rows_affected: 1 }
        '400':
          description: 更新失敗
          content:
            application/json:
              schema:
                properties:
                  product_id: { description: 商品編號, type: integer }
                  message: { description: 錯誤訊息, type: string }
                  rows_affected: { description: 影響的資料筆數, type: integer }
                type: object
      security:
        -
          JWT: []
  /customers/count:
    get:
      tags:
        - 會員(Customers)
      summary: 取得會員總筆數
      description: ''
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - created_at_min
                - created_at_max
              properties:
                since_id:
                  description: 取得比指定會員編號稍晚的會員
                  type: string
                  example: '1008'
                created_at_min:
                  description: '加入起始時間：2020-01-16T10:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-16T10:15:47'
                created_at_max:
                  description: '加入結束時間：2020-01-25T19:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-25T19:15:47'
              type: object
      responses:
        '200':
          description: 會員筆數
          content:
            application/json:
              schema:
                properties:
                  count: { description: 會員筆數, type: integer }
                type: object
                example:
                  count: { count: 2360 }
      security:
        -
          JWT: []
  /customers/group:
    get:
      tags:
        - 會員(Customers)
      summary: 取得會員群組集合
      description: ''
      responses:
        '200':
          description: 會員群組集合
          content:
            application/json:
              schema:
                properties:
                  count: { description: 會員群組數, type: integer }
                  result: { description: 會員群組集合, type: array, items: { $ref: '#/components/schemas/CustomerGroupModel' } }
                type: object
      security:
        -
          JWT: []
  '/customers/{customer_id}':
    get:
      tags:
        - 會員(Customers)
      summary: 取得指定會員(編號/單筆)
      description: ''
      parameters:
        -
          name: customer_id
          in: path
          description: 會員編號
          required: true
          schema:
            type: integer
          example: '160028'
      responses:
        '200':
          description: 會員個資
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerModel'
      security:
        -
          JWT: []
  '/customers/phone/{phone_number}':
    get:
      tags:
        - 會員(Customers)
      summary: 取得指定會員(電話/單筆)
      description: ''
      parameters:
        -
          name: phone_number
          in: path
          description: 會員登錄電話
          required: true
          schema:
            type: string
          example: '0988123456'
      responses:
        '200':
          description: 會員個資
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerModel'
      security:
        -
          JWT: []
  '/customers/email/{email}':
    get:
      tags:
        - 會員(Customers)
      summary: 取得指定會員(Email/單筆)
      description: ''
      parameters:
        -
          name: email
          in: path
          description: 會員登錄電子郵件
          required: true
          schema:
            type: string
          example: hello@qdm.com.tw
      responses:
        '200':
          description: 會員個資
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerModel'
      security:
        -
          JWT: []
  /customers:
    get:
      tags:
        - 會員(Customers)
      summary: 條件式篩選會員(多筆)
      description: ''
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - created_at_min
                - created_at_max
              properties:
                since_id:
                  description: 取得比指定會員編號稍晚的會員
                  type: string
                  example: '1008'
                facebook_user_id:
                  description: '只顯示有綁 Facebook User ID 的會員'
                  type: boolean
                  example: 'true'
                line_user_id:
                  description: '只顯示有綁 LINE User ID 的會員'
                  type: boolean
                  example: 'true'
                created_at_min:
                  description: '加入起始時間：2020-01-16T10:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-16T10:15:47'
                created_at_max:
                  description: '加入結束時間：2020-01-25T19:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-25T19:15:47'
                modified_at_min:
                  description: '資料異動起始時間：2020-01-16T10:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-16T10:15:47'
                modified_at_max:
                  description: '資料異動結束時間：2020-01-25T19:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-25T19:15:47'
                cartlast_at_min:
                  description: '購物車最近異動起始時間：2020-01-16T10:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-16T10:15:47'
                cartlast_at_max:
                  description: '購物車最近異動結束時間：2020-01-25T19:15:47'
                  type: string
                  format: date-time
                  example: '2020-01-25T19:15:47'
                page_size:
                  description: 每頁筆數(上限300筆)
                  type: integer
                  default: '300'
                  example: '50'
                page_number:
                  description: 從第幾頁開始
                  type: integer
                  default: '1'
                  example: '3'
              type: object
      responses:
        '200':
          description: 會員集合
          content:
            application/json:
              schema:
                properties:
                  count: { description: 擷取會員數, type: integer }
                  total_count: { description: 符合會員數, type: integer }
                  search_criteria: { description: 分頁參數, type: array, items: { $ref: '#/components/schemas/ResultPaginationModel' } }
                  result: { description: 會員集合, type: array, items: { $ref: '#/components/schemas/CustomerModel' } }
                type: object
      security:
        -
          JWT: []
    post:
      tags:
        - 會員(Customers)
      summary: 新增會員
      description: ''
      requestBody:
        content:
          application/json:
            schema:
              properties:
                customers:
                  description: 會員集合
                  type: array
                  items: { allOf: [{ required: [name, phone, customer_group_id], properties: { name: { description: 會員名稱, type: string, example: 王大頭 }, customer_group_id: { description: 會員群組, type: integer, example: '3' }, phone: { title: '範例： 0988245262', description: 手機號碼(唯一主鍵), type: string, example: '0988245262' }, email: { title: '範例： hello@your_domain.com', description: 電子郵件, type: string, example: hello@your_domain.com }, sex: { title: '1=女 2=男', description: 性別, type: integer, example: '2' }, birthday_date: { description: 生日, type: string, format: date-time, default: YYYY-MM-DD, example: '1980-11-02' }, date_added: { description: 加入日期, type: string, format: date-time, default: YYYY-MM-DD, example: '2020-01-20' }, status: { description: 會員狀態, type: boolean, default: 'true', example: 'true' }, password: { title: '長度 8 至 20 碼', description: 預設登入密碼, type: string }, comment: { description: 會員備註, type: string, example: 備註 }, social_media: { description: 社群ID集合, properties: { facebook_id: { description: 'Facebook id', type: string }, line_id: { description: 'Line id', type: string }, google_id: { description: 'Google id', type: string } }, type: object }, address_info: { description: 地址資訊, properties: { company: { description: 公司名稱, type: string }, address_1: { description: 地址1, type: string }, address_2: { description: 地址2, type: string }, postcode: { description: 郵遞區號, type: int, example: '802' } }, type: object }, invoice_carruer: { description: 電子發票載具, properties: { nature: { description: 自然人憑證, type: string }, mobile: { description: 手機載具條碼, type: string } }, type: object } }, type: object }] }
              type: object
      responses:
        '200':
          description: 會員新增成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 成功新增筆數, type: integer }
                  customer_id_list: { description: 新增成功的(會員)手機號碼集合, type: array, items: {  } }
                  rejection_list: { title: '(會員ID)重複的手機號碼 或 0=異常錯誤', description: 新增失敗的(會員)手機號碼集合, type: array, items: {  } }
                type: object
                example:
                  data: { rows_affected: '12', customer_id_list: [{ phone: '0910111111', customer_id: 123 }, { phone: '0910111112', customer_id: 124 }, { phone: '0910111113', customer_id: 125 }], rejection_list: [{ phone: '0910111114', customer_id: 126, message: 'error message' }, { phone: '0910111115', customer_id: 0, message: 'error message' }] }
      security:
        -
          JWT: []
  /customers/tag:
    post:
      tags:
        - 會員(Customers)
      summary: 會員貼新標籤
      description: ''
      requestBody:
        content:
          application/json:
            schema:
              properties:
                customers:
                  description: 會員集合
                  type: array
                  items: { allOf: [{ required: [phone, tags], properties: { phone: { description: 會員手機號碼, type: string, example: '0988123123' }, tags: { title: '新增多組標籤請用「,」符號分隔。不會覆蓋舊標籤', description: 新的標籤(新增), type: string, example: '標籤A,標籤B,標籤C' } }, type: object }] }
              type: object
      responses:
        '200':
          description: 會員貼新標籤成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 成功會員筆數, type: integer }
                  customer_id_list: { description: 標籤新增成功的會員集合, type: array, items: {  } }
                  rejection_list: { description: 標籤新增失敗的會員集合, type: array, items: {  } }
                type: object
                example:
                  data: { rows_affected: '12', customer_id_list: [{ phone: '0988123123', tags: [標籤A, 標籤B, 標籤C] }], rejection_list: [{ phone: '0988555123' }, { phone: '0988123666' }] }
      security:
        -
          JWT: []
  /customers/reward:
    post:
      tags:
        - 會員(Customers)
      summary: 會員新增紅利或折抵
      description: 紅利打-負號表示折抵
      requestBody:
        content:
          application/json:
            schema:
              properties:
                customers:
                  description: 會員集合
                  type: array
                  items: { allOf: [{ required: [points, description], properties: { phone: { title: '手機 或 ID 則一', description: 會員手機號碼, type: string, example: '0988123123' }, customer_id: { title: '手機 或 ID 則一', description: 會員編號(ID), type: integer, example: '123' }, points: { title: 若-負號表示折抵, description: 紅利點數, type: integer, example: '100' }, description: { description: 紅利項目說明, type: string, example: 當月壽星100紅利 } }, type: object }] }
              type: object
      responses:
        '200':
          description: 會員紅利項目新增成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 成功會員筆數, type: integer }
                  customer_id_list: { description: 紅利項目新增成功的會員集合, type: array, items: {  } }
                  rejection_list: { description: 紅利項目新增失敗的會員集合, type: array, items: {  } }
                type: object
                example:
                  data: { rows_affected: '12', customer_id_list: [{ phone: '0988123123' }], rejection_list: [{ phone: '0988555123' }, { phone: '0988123666' }] }
      security:
        -
          JWT: []
  /customers/apply_group:
    put:
      tags:
        - 會員(Customers)
      summary: 更新會員群組
      description: ''
      requestBody:
        request: skus
        description: 會員清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: 會員清單
              type: array
              items:
                allOf:
                  - { required: [customer_id, customer_group_id], properties: { customer_id: { description: 會員編號, type: integer }, customer_group_id: { description: 新的會員群組編號, type: integer } }, type: object }
              example:
                -
                  customer_id: '2101'
                  customer_group_id: 11
                -
                  customer_id: '2097'
                  customer_group_id: 11
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 更新成功會員數量, type: integer }
                  customer_id_list: { description: 更新成功的會員集合, type: array, items: {  } }
                type: object
                example:
                  data: { customer_id_list: [['2101', '2097']], rows_affected: '2' }
      security:
        -
          JWT: []
  /customers/apply_groupdate:
    put:
      tags:
        - 會員(Customers)
      summary: 更新會員升等日
      description: ''
      requestBody:
        request: skus
        description: 會員清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: 會員清單
              type: array
              items:
                allOf:
                  - { required: [customer_id, upgrade_date], properties: { customer_id: { description: 會員編號, type: integer }, upgrade_date: { description: 最後升等日, type: string, format: date-time, default: 'YYYY-MM-DDTHH:ii:ss' } }, type: object }
              example:
                -
                  customer_id: '2101'
                  upgrade_date: 'YYYY-MM-DDTHH:ii:ss'
                -
                  customer_id: '2097'
                  upgrade_date: 'YYYY-MM-DDTHH:ii:ss'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 更新成功會員數量, type: integer }
                  customer_id_list: { description: 更新成功的會員集合, type: array, items: {  } }
                type: object
                example:
                  data: { customer_id_list: [['2101', '2097']], rows_affected: '2' }
      security:
        -
          JWT: []
  /customers/apply_email:
    put:
      tags:
        - 會員(Customers)
      summary: 更新會員電子郵件
      description: ''
      requestBody:
        request: skus
        description: 會員清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: 會員清單
              type: array
              items:
                allOf:
                  - { required: [customer_id, new_email], properties: { customer_id: { description: 會員編號, type: integer }, new_email: { description: 新的電子郵件, type: string } }, type: object }
              example:
                -
                  customer_id: '2101'
                  new_email: 電子郵件
                -
                  customer_id: '2097'
                  new_email: 電子郵件
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 更新成功會員數量, type: integer }
                  customer_id_list: { description: 更新成功的會員集合, type: array, items: {  } }
                type: object
                example:
                  data: { customer_id_list: [['2101', '2097']], rows_affected: '2' }
      security:
        -
          JWT: []
  /customers/birthday:
    put:
      tags:
        - 會員(Customers)
      summary: 更新會員生日
      description: ''
      requestBody:
        request: skus
        description: 會員清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: 會員清單
              type: array
              items:
                allOf:
                  - { required: [customer_id, new_birthday], properties: { customer_id: { description: 會員編號, type: integer }, new_birthday: { description: 新的生日, type: string, format: date-time, default: YYYY-MM-DD } }, type: object }
              example:
                -
                  customer_id: '2101'
                  new_birthday: '1997-10-25'
                -
                  customer_id: '2097'
                  new_birthday: '1965-01-09'
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 更新成功會員數量, type: integer }
                  customer_id_list: { description: 更新成功的會員集合, type: array, items: {  } }
                type: object
                example:
                  data: { customer_id_list: [['2101', '2097']], rows_affected: '2' }
      security:
        -
          JWT: []
  /customers/social:
    put:
      tags:
        - 會員(Customers)
      summary: '更新會員社群帳號 user ID'
      description: ''
      requestBody:
        request: skus
        description: 會員清單
        required: true
        content:
          application/json:
            schema:
              property: null
              description: 會員清單
              type: array
              items:
                allOf:
                  - { required: [customer_id, new_user_id, social_account], properties: { customer_id: { description: 會員編號, type: integer }, new_user_id: { description: '新的user ID', type: string }, social_account: { description: '社群類型：LINE, GOOGLE, META(facebook)', type: string, enum: [LINE, GOOGLE, META] } }, type: object }
              example:
                -
                  customer_id: '2101'
                  new_user_id: ABC1231231245124
                  social_account: LINE
                -
                  customer_id: '2097'
                  new_user_id: CCC123123123489
                  social_account: GOOGLE
                -
                  customer_id: '92'
                  new_user_id: '12312553141489'
                  social_account: META
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  rows_affected: { description: 更新成功會員數量, type: integer }
                  customer_id_list: { description: 更新成功的會員集合, type: array, items: {  } }
                type: object
                example:
                  data: { customer_id_list: [['2101', '2097']], rows_affected: '2' }
      security:
        -
          JWT: []
  /settings/coupon:
    get:
      tags:
        - 設定(Settings)
      summary: 取得所有優惠券設定
      description: ''
      security:
        -
          JWT: []
  /settings/shipping:
    get:
      tags:
        - 設定(Settings)
      summary: 取得所有配送方式
      description: ''
      responses:
        '200':
          description: 配送方式集合
          content:
            application/json:
              schema:
                properties:
                  count: { description: 配送方式數, type: integer }
                  result: { description: 配送方式集合, type: array, items: { $ref: '#/components/schemas/ShippingMethodModel' } }
                type: object
      security:
        -
          JWT: []
  /settings/customer/upgrade_conditions:
    get:
      tags:
        - 設定(Settings)
      summary: 取得會員升等設定
      description: ''
      security:
        -
          JWT: []
  /report/product/purchase:
    get:
      tags:
        - 報表(Reports)
      summary: 商品購買統計
      description: 日期查詢區間最大180天。每頁結果筆數最多300筆(商品)
      requestBody:
        content:
          application/json:
            schema:
              required:
                - start_at
                - end_at
              properties:
                start_at:
                  description: 訂單購買日(起始)
                  type: string
                  format: date-time
                  default: YYYY-MM-DD
                  example: '2021-11-02'
                end_at:
                  description: 訂單購買日(結束)
                  type: string
                  format: date-time
                  default: YYYY-MM-DD
                  example: '2023-01-20'
                product_id_list:
                  description: '指定統計的商品ID (多筆逗點 「 , 」 分隔)'
                  type: string
                  default: 非必填
                  example: '12,59,38,2'
                page_size(上限300筆):
                  description: 每頁筆數
                  type: integer
                  default: '300'
                page_number:
                  description: 從第幾頁開始
                  type: integer
                  default: '1'
              type: object
      security:
        -
          JWT: []
  /token/authorize:
    post:
      tags:
        - 身分驗證(Auth)
      summary: '取得 API Access Token'
      description: '使用 client_id 與 client_secret 通過 Basic Auth 身分驗證取得 API Access Token (JWT)。後續 API 的存取通過 HTTP header 中的 Authorization 傳送 Bearer Token (JWT) 做權限驗證。每次取得的 JWT 令牌效期為 1 個小時。'
      responses:
        '200':
          description: '取得一組 API Access Token (JWT)'
          content:
            application/json:
              schema:
                properties:
                  access_token: { description: 'JSON Web Token (JWT)', type: string }
                  token_type: { description: 'Token 的類型 (Bearer)', type: string }
                  expires_in: { description: 'Token 的效期 (一個小時)', type: integer }
                type: object
                example:
                  data: { store_uid: 商品專屬編號, access_token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImp0aSI6IjdrVUtqa3ZkeGxEN2J6SmxrMmF4V0kifQ.eyJpc3MiOiJodHRwczpcL1wvcWRtLnR3IiwiYXVkIjoicTZhNGFhMjIwODQ0M2EiLCJqdGkiOiI3a1VLamt2ZHhsRDdiekpsazJheFdJIiwiaWF0IjoxNTc5NTg0MTg5LCJuYmYiOjE1Nzk1ODQxODksImV4cCI6MTU3OTU4Nzc4OSwidWlkIjoxLCJhZGRyZXNzIjoiWjQ3enp3a1c3UHJTN2hOUUs4S1F3T2hyWW4zdE9wZEVzczFUeVBuS2tzYll2THRZIn0.94ypJ0dNQUWaiY-UQTYVKebLC5KGuzQ8A7OMO7i8jis, token_type: bearer, expires_in: 1579587789, message: '成功取得一組 API Access Token' }
      security:
        -
          BasicAuth: []
components:
  schemas:
    ResultPaginationModel:
      properties:
        page_size:
          description: 每頁筆數
          type: integer
          default: '300'
        page_number:
          description: 從第幾頁開始
          type: integer
          default: '1'
        page_count:
          description: 總頁數
          type: integer
      type: object
    DeliverStatusModel:
      properties:
        status:
          description: '配送狀態：PENDING=等待出貨, SHIPPED=已出貨, PICKREADY=貨到門市, DELIVERED=已取貨, EXCEPTION=配送失敗退回, ABANDONED=七天未取'
          type: string
          enum:
            - PENDING
            - SHIPPED
            - PICKREADY
            - DELIVERED
            - EXCEPTION
            - ABANDONED
          example: PICKREADY
        progress_desc:
          description: 配送進度
          type: string
          example: 包裹配達取件門市
        comment:
          description: 備註說明
          type: string
          example: OOO
        created_at:
          description: 更新時間
          type: string
          format: date-time
          example: '2020-01-25T19:15:47'
      type: object
    OrderProductOptionModel:
      properties:
        id:
          description: 選項值編號
          type: string
        name:
          description: 選項名稱
          type: string
        value:
          description: 選項值
          type: string
      type: object
    OrderItemModel:
      properties:
        product_id:
          description: 商品編號
          type: integer
        name:
          description: 商品名稱
          type: string
        options:
          description: 購物選項
          type: array
          items:
            $ref: '#/components/schemas/OrderProductOptionModel'
        sku:
          description: 'Variant SKU<br/>單一商品SKU，或者有含購物選項的變體SKU，例如 T-shirt 有顏色和尺寸之分。'
          type: string
        price:
          description: 單價
          type: integer
        quantity:
          description: 數量
          type: integer
        total:
          description: 小計
          type: integer
        giveaway:
          description: 是否為贈品
          type: integer
          default: '0'
      type: object
    OrderSubtotalsModel:
      properties:
        code:
          description: 項目類型
          type: string
          enum:
            - sub_total
            - shipping
            - reward
            - coupon
            - site_discount
            - promotion
        name:
          description: 項目名稱
          type: string
        value:
          description: 小計金額
          type: integer
      type: object
    OrderTracksPutModel:
      required:
        - order_id
        - tracking_number
      properties:
        order_id:
          description: 訂單編號
          type: integer
          pattern: '^[0-9]{10}$'
        tracking_number:
          description: 包裹追蹤碼
          type: string
        ship_date:
          description: 出貨日
          type: 'string <date>'
          default: YYYY-MM-DD
      type: object
    OrderInvoicePutModel:
      required:
        - order_id
        - invoice_number
      properties:
        order_id:
          description: 訂單編號
          type: integer
          pattern: '^[0-9]{10}$'
        invoice_number:
          description: 發票號碼
          type: string
        random_number:
          description: 隨機號碼
          type: string
      type: object
    OrderPaymentStatusPutModel:
      required:
        - order_id
        - invoice_number
      properties:
        order_id:
          description: 訂單編號
          type: integer
          pattern: '^[0-9]{10}$'
        payment_remark:
          description: 付款銀行帳號或其它備註(25個中文字)
          type: string
        payment_time:
          description: 付款時間
          type: string
          format: date-time
          default: 'YYYY-MM-DDTHH:ii:ss'
      type: object
    OrderCommentPostModel:
      required:
        - order_id
        - comment
      properties:
        order_id:
          description: 訂單編號
          type: integer
          pattern: '^[0-9]{10}$'
        comment:
          description: 備註內容
          type: string
      type: object
    OrderModel:
      properties:
        order_id:
          description: 訂單編號
          type: integer
          pattern: '^[0-9]{10}$'
        bb_id:
          description: 'Buy Button 專屬編號'
          type: string
        order_status:
          description: '訂單狀態<br/>1=待處理, 2=處理中, 3=已配送, 4=已取消, 5=已完成, 6=調貨中。或店家另新增的狀態'
          type: integer
        date_added:
          description: 購買日期
          type: string
          format: date-time
          default: 'YYYY-MM-DDTHH:ii:ss'
        order_items:
          description: 購買商品集合
          type: array
          items:
            $ref: '#/components/schemas/OrderItemModel'
        order_subtotals:
          description: 訂單小計項目
          type: array
          items:
            $ref: '#/components/schemas/OrderSubtotalsModel'
        total:
          description: 訂單總金額
          type: number
        currency_code:
          description: 幣別
          type: string
          default: TWD
        coupon_code_used:
          description: 使用優惠券代碼
          type: string
        reward_used:
          description: 紅利折抵
          type: integer
        reward_bonus:
          description: 紅利獲得
          type: integer
        promotion_discount_total:
          description: '折扣總計 (活動促銷, 紅利折抵, 優惠卷，不含 折抵運費 shipping 類的項目 )'
          type: integer
        shipping_fee:
          description: 運費
          type: integer
        payment_code:
          description: 付款方式代號
          type: string
        payment_method:
          description: 付款方式說明
          type: string
        shipping_code:
          description: 配送方式代號
          type: string
        shipping_method:
          description: 配送方式說明
          type: string
        customer_id:
          description: '會員ID, 0=訪客購買'
          type: integer
          default: '0'
        customer_group_id:
          description: 會員群組ID
          type: integer
        regular_customer:
          title: '購買次數 (已付款)(不含此筆訂單)'
          description: 熟客會員
          type: integer
          default: '0'
        payment_name:
          description: 購買人姓名
          type: string
        payment_email:
          description: 購買人電子郵件信箱
          type: string
          format: email
        payment_telephone:
          description: 購買人手機號碼
          type: string
        comment:
          description: '購買人留言備註 (給店長的話)'
          type: string
        customer_ip_address:
          description: 連線IP
          type: string
        customer_user_agent:
          description: 連線裝置User-Agent
          type: string
        shipping_name:
          description: 收件人姓名
          type: string
        shipping_telephone:
          description: 收件人手機號碼
          type: string
        shipping_country:
          description: 配送國家
          type: string
          default: Taiwan
        shipping_postcode:
          description: 郵遞區號
          type: integer
        shipping_zone:
          description: 配送縣市
          type: string
        shipping_address:
          description: 配送地址
          type: string
        pickup_point:
          description: 取貨門市店號(或服務編號)
          type: string
        convenient_store_type:
          title: 'UNIMART=7-11, FAMI=全家, HILIFE=萊爾富'
          description: 超商類型
          type: string
          enum:
            - UNIMART
            - FAMI
            - HILIFE
        convenient_store_no:
          description: 超商門市店號
          type: string
        convenient_store_name:
          description: 超商門市名稱
          type: string
        convenient_store_address:
          description: 超商門市地址
          type: string
        ECPay_AllPayLogisticsID:
          description: (綠界科技)物流交易編號
          type: string
        ECPay_CVSPaymentNo:
          description: (綠界科技)寄貨編號
          type: string
        ECPay_CVSValidationNo:
          description: '(綠界科技)驗證碼&nbsp;&nbsp;<small><font color=''#A0A0A0''>說明：注意事項：7-ELEVEN C2C 交貨便代碼即為 CVSPaymentNo 與 CVSValidationNo 的組合。</font></small>'
          type: string
        shipping_deliver_period:
          description: '指定到貨時段<br/><br/>00:00:00   不指定<br/>08:00:00   中午前<br/>13:00:00   下午時段<br/>18:00:00   晚上時段<br/><b>以下以''秒數''當識別</b><br/>00:00:04  白天(09:00 - 18:00) <br/>00:00:05  晚上(18:00 - 21:00)'
          type: string
          format: time
          default: 'HH:ii:ss'
        shipping_deliver_ondate:
          description: 指定到貨日期
          type: string
          format: date
          default: YYYY-MM-DD
        shipping_status:
          description: '配送狀態：PENDING=等待出貨, SHIPPED=已出貨, PICKREADY=貨到門市, DELIVERED=已取貨, EXCEPTION=配送失敗退回, ABANDONED=七天未取'
          type: string
          default: PENDING
          enum:
            - PENDING
            - SHIPPED
            - PICKREADY
            - DELIVERED
            - EXCEPTION
            - ABANDONED
        tracking_number:
          description: 包裹追蹤碼
          type: string
        payment_status:
          description: '付款狀態：PAID=已付款, UNPAID=尚未付款'
          type: string
          default: UNPAID
          enum:
            - PAID
            - UNPAID
        payment_time:
          description: 付款時間
          type: string
          format: date-time
          default: 'YYYY-MM-DDTHH:ii:ss'
        payment_banks:
          title: '例如：綠界金流訂單編號:2001211526268401'
          description: 付款來源
          type: string
        payment_account:
          title: '例如：卡片的末 4 碼:5006'
          description: 付款帳號
          type: string
        invoice_number:
          description: 發票號碼
          type: string
        invoice_type:
          description: '發票類型 (0=不開發票, 2=二聯式, 3=三聯式)'
          type: integer
          default: '0'
          enum:
            - 0
            - 2
            - 3
        invoice_randomnumber:
          description: 發票隨機碼
          type: string
        invoice_vat_number:
          description: 開立統編
          type: string
        invoice_carrier_num:
          description: 載具編號
          type: string
        invoice_lovecode:
          description: 捐贈愛心碼
          type: string
        invoice_title:
          description: 發票抬頭
          type: string
        invoice_address:
          description: 發票地址
          type: string
        invoice_created_at:
          description: 發票開立時間
          type: string
          format: date-time
          default: 'YYYY-MM-DDTHH:ii:ss'
        ma_rid:
          description: '美安 rid'
          type: string
        ma_click_id:
          description: '美安 click_id'
          type: string
        line_ecid:
          description: 'LINE購物 ecid'
          type: string
        ec_id:
          description: '導購追蹤識別碼 global unique identifier'
          type: string
        utm_source:
          description: utm_source
          type: string
          default: '網址帶參數 ?utm_source=OOOOO 導購的訂單'
        utm_medium:
          description: utm_medium
          type: string
        utm_campaign:
          description: utm_campaign
          type: string
        utm_content:
          description: utm_content
          type: string
        utm_term:
          description: utm_term
          type: string
        affiliate_id:
          description: '分銷合作 KOL專屬編號'
          type: string
          default: '網址帶參數 ?affiliate_id=OOOOO 導購的訂單'
        date_modified:
          description: 最近修改時間
          type: string
          format: date-time
          default: 'YYYY-MM-DDTHH:ii:ss'
        return_request:
          description: '此單是否申請退換貨<br/>0=無, 1=是'
          type: integer
        return_id:
          description: 退換貨單號
          type: integer
        return_status_id:
          description: '退換貨處理狀態<br/>1=待處理, 2=等待商品到貨, 3=已完成'
          type: integer
        return_name:
          description: 退換貨申請人
          type: string
        return_email:
          description: 退換貨申請人電子郵件
          type: string
        return_telephone:
          description: 退換貨申請人手機號碼
          type: string
        return_comment:
          description: 退換貨申請人留言
          type: string
        return_address:
          description: 退換貨申請收貨地址
          type: string
        return_return_bank:
          description: 退換貨申請退款銀行
          type: string
        return_date_added:
          description: 退換貨申請時間
          type: string
          format: date-time
          default: 'YYYY-MM-DDTHH:ii:ss'
        return_items:
          description: 退換貨商品
          type: array
          items:
            allOf:
              -
                properties:
                  product_id: { description: 商品編號, type: integer, example: '17' }
                  name: { description: 商品名稱, type: string, example: 貓籃子 }
                  sku: { description: SKU, type: string, example: CAT-EAST-G-F002 }
                  quantity: { description: 數量, type: integer, example: '1' }
                  price: { description: 價格, type: integer, example: '1230' }
                  return_reason_id: { description: 退換貨申請原因代號, type: integer, example: '1' }
                  return_reason_name: { description: 退換貨申請原因, type: string, example: 商品不符 }
                type: object
      type: object
    OptionVariantModel:
      properties:
        id:
          title: ''
          description: 購物選項編號
          type: integer
          example: '10'
        name:
          title: 範例：顏色
          description: 購物選項名稱
          type: string
          example: 顏色
        type:
          description: '購物選項類型：SELECT=下拉選單(單選), CHOICE=單選, MULTIPLE_CHOICE=多選, IMAGE=圖片, DATE=日期, TIME=時間, DATETIME=日期時間, TEXT=單行文字, PARAGRAPH_TEXT=多行文字'
          type: string
          enum:
            - SELECT
            - CHOICE
            - MULTIPLE_CHOICE
            - IMAGE
            - DATE
            - TIME
            - DATETIME
            - TEXT
            - PARAGRAPH_TEXT
          example: SELECT
        required:
          description: 是否必選
          type: boolean
          enum:
            - 'true'
            - 'false'
          example: 'true'
        sort_order:
          title: 數字越小越前面(遞增排序)
          description: 排序
          type: integer
      type: object
    OptionvValueVariantModel:
      properties:
        id:
          title: ''
          description: 選項值編號
          type: integer
          example: '10'
        name:
          title: 範例：紅色
          description: 選項值名稱
          type: string
          example: 紅色
        price_prefix:
          title: 價格增減標記
          description: 價格增減標記
          type: string
          enum:
            - +
            - '-'
            - '='
        price:
          title: 價格增減的金額
          description: 商品價格增減金額
          type: integer
      type: object
    ProductOptionVariantsModel:
      properties:
        option:
          description: 購物選項
          type: object
          allOf:
            -
              $ref: '#/components/schemas/OptionVariantModel'
        option_value:
          description: 選項值
          type: array
          items:
            $ref: '#/components/schemas/OptionvValueVariantModel'
      type: object
    ProductVariantsInventoryModel:
      properties:
        option_ref_id:
          title: ''
          description: 選項值編號組合
          type: string
          example: '204,46'
        sku:
          title: '範例: RTS-CHKF5-RED8'
          description: 組合選項SKU
          type: string
          example: RTS-CHKF5-RED8
        name:
          title: '範例: 紅##鰹魚白肉+雞肉+海鯛。以 ## 符號區隔'
          description: 選項值名稱組合
          type: string
          example: '紅##鰹魚白肉+雞肉+海鯛'
        quantity:
          title: ''
          description: 組合選項庫存
          type: integer
        min_quantity:
          title: ''
          description: 低庫存警示量
          type: integer
        option_image_url:
          title: ''
          description: 關聯商品圖網址
          type: 'string <uri>'
      type: object
    ProductVariantsInventoryPutModel:
      required:
        - sku
        - quantity
      properties:
        sku:
          title: '格式: 主商品SKU 或 變體SKU'
          description: '主商品SKU 或 變體SKU'
          type: string
          example: S12TMEDWHICOT
        quantity:
          description: 庫存數量
          type: integer
          example: '999'
      type: object
    ProductImageModel:
      properties:
        image_url:
          description: 圖片CDN網址
          type: string
          format: uri
          example: 'https://image-cdn-flare.qdm.cloud/q6a4aa2208443a/image/cache/data/2018/09/07/724392c6c17e01eb0c3a49aad2de31c7-cr-280x280.jpg'
        image_relative_filename:
          description: 相對路徑圖片檔名
          type: string
          format: uri
          example: /image/cache/data/2018/09/07/724392c6c17e01eb0c3a49aad2de31c7-cr-280x280.jpg
        position:
          title: '1=主圖, 由小至大遞增排序'
          description: 位置排序
          type: integer
      type: object
    ProductSpecialOfferModel:
      properties:
        customer_group_id:
          title: '若 -1 表示無限制群組'
          description: 適用會員群組編號
          type: integer
          example: '3'
        price:
          description: 特賣直購價
          type: integer
          example: '1280'
        date_available:
          description: 特賣開始日期
          type: string
          format: date-time
          default: YYYY-MM-DD
          example: '2020-12-25'
        date_disavailable:
          description: 特賣截止日期
          type: string
          format: date-time
          default: YYYY-MM-DD
          example: '2020-12-25'
      type: object
    ProductPurchaseRewardsModel:
      properties:
        customer_group_id:
          description: 適用會員群組編號
          type: integer
          example: '3'
        customer_group_name:
          description: 會員群組名稱
          type: string
          example: VIP等級
        price:
          description: 回饋點數
          type: integer
          example: '100'
      type: object
    ProductModel:
      properties:
        product_id:
          description: 商品編號
          type: integer
        url:
          description: 商品網址
          type: string
        name:
          description: 商品名稱
          type: string
        feature:
          description: 商品特色
          type: string
        description:
          description: 商品介紹
          type: string
        price:
          description: 基本售價
          type: integer
        independent_delivery_charge:
          description: 獨立運費
          type: string
          default: 留空
        sku:
          title: 範例：S12T
          description: SKU
          type: string
          example: S12T
        ean:
          description: EAN
          type: string
          example: '978020137962'
        model:
          description: 規格型號
          type: string
        weight:
          description: 重量(kg)
          type: number
          format: float
        length:
          description: 長(cm)
          type: number
          format: float
        width:
          description: 寬(cm)
          type: number
          format: float
        height:
          description: 高(cm)
          type: number
          format: float
        tax_class_id:
          title: '0=應稅, 1=零稅率, 2=免稅'
          description: 課稅別
          type: integer
          default: '0'
          enum:
            - '0'
            - '2'
            - '3'
          example: '0'
        date_available:
          description: 上架日期
          type: string
          format: date-time
          default: 'YYYY-MM-DDTHH:ii:ss'
        date_disavailable:
          description: 下架日期
          type: string
          format: date-time
          default: 'YYYY-MM-DDTHH:ii:ss'
        status:
          description: 啟用狀態
          type: boolean
        no_index:
          description: '隱藏模式<br/>true=隱藏不曝光, false=正常顯示'
          type: boolean
        custom_value_1:
          description: 自訂資料1
          type: string
        custom_value_2:
          description: 自訂資料2
          type: string
        images:
          description: 商品圖片集
          type: array
          items:
            $ref: '#/components/schemas/ProductImageModel'
        variants_options:
          description: 購物選項集合
          type: array
          items:
            $ref: '#/components/schemas/ProductOptionVariantsModel'
        variants_inventory:
          description: 購物選項組合庫存
          type: array
          items:
            $ref: '#/components/schemas/ProductVariantsInventoryModel'
        special_offer:
          description: 限時特賣集合
          type: array
          items:
            $ref: '#/components/schemas/ProductSpecialOfferModel'
        purchase_rewards:
          description: 紅利積點回饋
          type: array
          items:
            $ref: '#/components/schemas/ProductPurchaseRewardsModel'
        categories:
          description: 商品分類
          type: array
          items:
            allOf:
              -
                required:
                  - category_id
                  - category_name
                properties:
                  category_id: { description: 分類編號ID, type: integer }
                  category_name: { description: 分類名稱, type: string }
                type: object
        seo_information:
          description: SEO微資料標記
          type: array
          items:
            allOf:
              -
                properties:
                  meta_description: { description: 商品短描述, type: string }
                  meta_keyword: { description: '商品名稱 & 商品頁標題', type: string }
                  tag: { description: 商品關鍵字標籤, type: array }
                type: object
        date_modified:
          description: 最近修改時間
          type: string
          format: date-time
          default: 'YYYY-MM-DDTHH:ii:ss'
      type: object
    ProductSpecialModel:
      required:
        - product_id
      properties:
        product_id:
          description: 商品編號
          type: integer
          example: '3'
        clean:
          title: 'true=刪除其他未異動的設定, false=保留其他未異動的設定'
          description: '是否刪除其他未異動的設定(<font color=''ff0000''>注意:使用true會刪除商品內未異動的設定，請謹慎使用</font>)'
          type: boolean
          default: 'false'
          enum:
            - 'true'
            - 'false'
          example: 'true'
        special_offer:
          description: 限時特賣集合<br/>更新對應商品編號與會員群組編號的資料，若無則新增一筆
          type: array
          items:
            $ref: '#/components/schemas/ProductSpecialOfferModel'
      type: object
    DelProductSpecialModel:
      required:
        - product_id
      properties:
        product_id:
          description: '商品編號(<font color=''ff0000''>注意:送出後會刪除對應商品編號內的所有限時特賣設定，請謹慎使用</font>)'
          type: integer
          example: '3'
      type: object
    ProductVariantsSKUPutModel:
      required:
        - curr_sku
        - new_sku
      properties:
        curr_sku:
          description: '目前 主商品SKU 或 變體SKU'
          type: string
          example: S12TMEDWHICOT
        new_sku:
          description: '新的 SKU'
          type: string
          example: A13CKUVEACTEV
      type: object
    AddressInfoModel:
      properties:
        postcode:
          description: 郵遞區號
          type: integer
          default: ''
        city:
          description: 縣市
          type: string
          default: ''
        address:
          description: 地址
          type: string
          default: ''
      type: object
    CustomerUpgradeHistoryModel:
      properties:
        previous_customer_group_id:
          description: 升等前(舊的)會員群組
          type: integer
        recent_customer_group_id:
          description: 升等後(新的)會員群組
          type: integer
        effective_date:
          description: 升等生效時間
          type: string
          format: date-time
          default: 'YYYY-MM-DDTHH:ii:ss'
      type: object
    CustomerModel:
      properties:
        customer_id:
          description: 會員編號
          type: integer
          example: '160028'
        customer_group_id:
          description: 會員群組編號
          type: integer
          example: '3'
        country_code:
          description: '國別代號 ISO 3166‑1 二字母碼（A2）'
          type: string
          example: TW
        facebook_connected:
          title: '0=無, 1=使用臉書登入'
          description: '連動 Facebook 帳號登入'
          type: integer
          example: '1'
        facebook_user_id:
          description: 'Facebook User ID'
          type: string
          example: '128555445426417'
        line_connected:
          title: '0=無, 1=使用LINE登入'
          description: '連動 LINE 帳號登入'
          type: integer
          example: '1'
        line_user_id:
          description: 'LINE User ID'
          type: string
          example: U2f809fdaca712a9ca11d99c382e32bcd
        name:
          description: 姓名
          type: string
          example: 王小明
        birthday:
          description: 生日
          type: string
          format: date-time
          default: YYYY-MM-DD
          example: '1988-07-23'
        sex:
          title: '1=女, 2=男'
          description: 性別
          type: integer
          example: '2'
        email:
          description: 電子郵件
          type: string
          example: hello@your_domain.com
        telephone:
          description: 聯絡手機
          type: string
          example: '0988123123'
        newsletter:
          title: '0=無, 1=訂閱'
          description: 訂閱電子報
          type: integer
          example: '1'
        approved:
          title: '0=等待審核, 1=核准'
          description: 會員資格審核
          type: integer
          example: '1'
        date_added:
          description: 加入日期
          type: string
          format: date-time
          default: 'YYYY-MM-DDTHH:ii:ss'
          example: '2020-01-20T20:50:20'
        date_modified:
          description: 資料異動時間
          type: string
          format: date-time
          default: 'YYYY-MM-DDTHH:ii:ss'
          example: '2020-01-20T22:45:16'
        address_info:
          description: 預設地址(會員中心)
          type: array
          items:
            $ref: '#/components/schemas/AddressInfoModel'
        upgrade_history_info:
          description: 會員升等(群組異動)歷程
          type: array
          items:
            $ref: '#/components/schemas/CustomerUpgradeHistoryModel'
        total_purchase_amount:
          title: '已付款, 不含已取消'
          description: 累積消費金額
          type: integer
          example: '9999'
        cart:
          description: 購物車商品集合
          type: array
          items:
            $ref: '#/components/schemas/ProductModel'
        cart_last_modified:
          description: 購物車最近異動時間
          type: string
          format: date-time
          default: 'YYYY-MM-DDTHH:ii:ss'
        tags:
          description: 會員標籤
          type: array
          items:
            type: string
        custom_value_1:
          description: 自訂資料1
          type: string
        custom_value_2:
          description: 自訂資料2
          type: string
        reward:
          description: 紅利
          properties:
            total:
              description: 累積可用紅利
              type: integer
              example: '2000'
            rows:
              description: 紅利累積與折抵紀錄
              type: array
              items:
                allOf:
                  - { properties: { order_id: { description: 訂單編號, type: integer, pattern: '^[0-9]{10}$' }, description: { description: 紅利項目說明, type: string }, points: { title: '-負號表示折抵', description: 紅利積點或折抵, type: integer }, date_added: { description: 項目新增時間, type: string, format: date-time, default: 'YYYY-MM-DDTHH:ii:ss' } }, type: object }
          type: object
      type: object
    CustomerGroupModel:
      description: 會員群組
      properties:
        customer_group_id:
          description: 會員群組編號
          type: integer
        name:
          description: 名稱
          type: string
        description:
          description: 描述
          type: string
        approval:
          title: 0=免審核
          description: 加入會員是否需要審核
          type: integer
          default: '0'
        effective_period:
          title: 0=永久
          description: 會員資格效期(年)
          type: integer
          default: '0'
        renewal_by_amount:
          title: 0=無限制
          description: 最低購買次數(續會)
          type: integer
          default: '0'
        renewal_by_total:
          title: 0=無限制
          description: 最低購買金額(續會)
          type: integer
          default: '0'
      type: object
    ShippingMethodModel:
      description: 配送方式
      properties:
        shipping_code:
          description: 配送方式代碼
          type: string
        shipping_name:
          description: 配送方式名稱
          type: string
        shipping_custom_name:
          description: 自定名稱
          type: string
        shipping_cost:
          description: 運費
          type: array
          items:
            $ref: '#/components/schemas/ShippingCostModel'
        shipping_amount_free:
          description: '【滿額免運】須達到此 金額 才享有免費配送'
          type: integer
        shipping_count_free:
          description: '【滿件免運】須達到此 數量 才享有免費配送'
          type: integer
        shipping_restrict:
          description: 配送限制
          type: array
          items:
            $ref: '#/components/schemas/ShippingRestrictModel'
      type: object
    ShippingCostModel:
      properties:
        unit:
          description: '以 元/件/箱 為單位計算'
          type: string
          enum:
            - 元
            - 件
            - 箱
        range:
          description: 運費級距
          type: array
          items:
            $ref: '#/components/schemas/ShippingCostRangeModel'
      type: object
    ShippingCostRangeModel:
      properties:
        item:
          description: '達到 N 元/件/箱 之門檻'
          type: integer
        fee:
          description: '收取費用 N 元'
          type: integer
      type: object
    ShippingRestrictModel:
      properties:
        unit:
          description: ''
          type: string
          enum:
            - 金額
            - 數量
            - 重量
        value:
          title: 'null 無限制'
          description: 限制值，超過此限制，則不能使用
          type: integer
      type: object
  responses:
    '200':
      description: 上傳成功
      content:
        application/json:
          schema:
            properties:
              success:
                description: 是否成功
                type: boolean
                example: true
              message:
                description: 成功訊息
                type: string
                example: 圖片上傳成功
              url:
                description: 圖片URL（主要回傳值）
                type: string
                example: 'https://domain.com/image/data/2024/01/15/abc123.jpg'
              data:
                description: 詳細資訊
                properties:
                  upload_type: { description: 上傳類型, type: string, example: product_image }
                  file_name: { description: 檔案名稱, type: string, example: abc123.jpg }
                  relative_path: { description: 相對路徑, type: string, example: data/2024/01/15/abc123.jpg }
                  file_size: { description: 檔案大小（位元組）, type: integer, example: 245760 }
                  dimensions: { description: 商品圖片上傳, properties: { width: { description: 圖片寬度, type: integer, example: 800 }, height: { description: 圖片高度, type: integer, example: 600 } }, type: object }
                type: object
            type: object
    '400':
      description: 上傳失敗
      content:
        application/json:
          schema:
            properties:
              success:
                description: 是否成功
                type: boolean
                example: false
              error:
                description: 錯誤訊息
                type: string
                example: '檔案大小超過限制（最大 1.5MB）'
            type: object
  requestBodies: {  }
  securitySchemes:
    BasicAuth:
      type: http
      description: '帶入專屬的介接金鑰 client_id 與 client_secret 通過 HTTP Basic Auth 身分驗證取得 API Access Token (JWT)。後續 API 的存取通過 HTTP header 中的 Authorization 傳送 Bearer Token (JWT) 做權限驗證。每次取得的 `JWT 令牌效期為 1 個小時`。'
      name: BasicAuth
      in: header
      scheme: basic
    JWT:
      type: http
      description: 'Usage format: Bearer &lt;JWT>'
      name: JWT
      in: header
      bearerFormat: JWT
      scheme: bearer