API Docs

REST API 文件

Public REST API endpoint、參數、扣款金額與回應摘要。

REST API 文件

以下 endpoint 由 API catalog 自動渲染。Public API 使用 `x-api-key` header 驗證，並要求 `Idempotency-Key` 防止重送時重複扣款；價格以新台幣顯示。

每個 endpoint 會列出 request 範例、成功 response schema、成功 JSON 範例及各項錯誤 response。`code: 200` 只代表成功 body；錯誤 body 會回對應的 `code` 與 `msg`。

overview

Overview 趨勢

取得整體週度交易趨勢，適合用於首頁總覽面積圖。

NT$5 起 / 次（依查詢區間計價）

Method	GET
Path	`/api/public/trends/overview`
Params	無
Example	`https://app.ecpaydata.com.tw/api/public/trends/overview`

請求範例

curl -s "https://app.ecpaydata.com.tw/api/public/trends/overview" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

回應欄位	型別	說明
`code`	number	固定為 200。
`data.type`	string	資料類型識別值。
`data.granularity`	string	趨勢粒度；週聚合可用時為 week，尚未建立或刷新時暫回退為 month。
`data.start`	string	回應資料涵蓋的起始日期。
`data.end`	string	回應資料涵蓋的結束日期。
`data.trend[].month`	string	週區間標籤，格式為 MM/DD-MM/DD；欄位名保留為 month 以相容既有客戶端。
`data.trend[].week_start`	string	週度資料的完整週起始日，格式為 YYYY-MM-DD；月度 fallback 不提供。
`data.trend[].week_end`	string	週度資料的完整週結束日，格式為 YYYY-MM-DD；月度 fallback 不提供。
`data.trend[].total_amount`	number	該週交易金額。
`data.trend[].trade_count`	number	該週交易筆數。
`data.trend[].avg_amount`	number	該週平均客單價。

成功回應範例

{
  "code": 200,
  "data": {
    "type": "overview",
    "granularity": "week",
    "start": "2025-01-01",
    "end": "2025-12-26",
    "trend": [
      {
        "month": "01/06-01/12",
        "week_start": "2025-01-06",
        "week_end": "2025-01-12",
        "total_amount": 1514345291,
        "trade_count": 464376,
        "avg_amount": 3261
      },
      {
        "month": "01/13-01/19",
        "week_start": "2025-01-13",
        "week_end": "2025-01-19",
        "total_amount": 1490029693,
        "trade_count": 444618,
        "avg_amount": 3351
      }
    ]
  }
}

錯誤回應範例

HTTP	Message	意思
400	`Idempotency-Key header is required`	付費 API 必須提供唯一的 `Idempotency-Key`，重送相同查詢時沿用同一個 key。
400	`Invalid Idempotency-Key`	`Idempotency-Key` 必須為 8 至 128 字元，只能使用英數字、`.`、`_`、`:`、`-`。
401	`Missing API key`	未提供 `x-api-key` header。
401	`Invalid API key`	API Key 不存在、格式錯誤或已被刪除。
403	`API key is inactive`	API Key 已停用。
403	`API key owner is inactive`	API Key 所屬帳號已停用。
409	`Idempotency-Key was already used for a different request`	同一個 `Idempotency-Key` 已用於不同 path 或 query；請為新查詢產生新 key。
409	`Request with this Idempotency-Key is still processing`	相同請求仍在處理中，請稍後使用同一個 key 重查，不要產生新 key。
402	`Active payment method required`	會員沒有有效的綁定信用卡，請先至會員中心完成綁定。
402	`Card payment failed`	綁定信用卡扣款失敗，本次不會回傳查詢資料；請確認卡片狀態或重新綁定。
402	`Daily charge limit exceeded`	已達每位會員每日 NT$500 的 API 扣款上限；台灣時間隔日歸零，待確認交易也會暫占額度。
502	`Payment status unknown; do not retry immediately`	綠界付款結果仍待確認，請勿立即重試以免重複扣款，並使用 paymentReference 聯絡客服。
422	`A valid invoice email is required`	綁卡時保存的發票 Email 無效；請重新綁卡並填入可收件的 Email。
500	`Internal server error`	系統錯誤，請稍後重試或聯絡支援。

HTTP 400

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "msg": "Idempotency-Key header is required"
}

HTTP 400

{
  "code": "INVALID_IDEMPOTENCY_KEY",
  "msg": "Invalid Idempotency-Key",
  "data": {
    "requirement": "8-128 characters: A-Z, a-z, 0-9, dot, underscore, colon or hyphen"
  }
}

HTTP 401

{
  "code": 401,
  "msg": "Missing API key"
}

HTTP 401

{
  "code": 401,
  "msg": "Invalid API key"
}

HTTP 403

{
  "code": 403,
  "msg": "API key is inactive"
}

HTTP 403

{
  "code": 403,
  "msg": "API key owner is inactive"
}

HTTP 409

{
  "code": "IDEMPOTENCY_KEY_REUSED",
  "msg": "Idempotency-Key was already used for a different request"
}

HTTP 409

{
  "code": "IDEMPOTENCY_IN_PROGRESS",
  "msg": "Request with this Idempotency-Key is still processing"
}

HTTP 402

{
  "code": "PAYMENT_METHOD_REQUIRED",
  "msg": "Active payment method required"
}

HTTP 402

{
  "code": "PAYMENT_FAILED",
  "msg": "Card payment failed"
}

HTTP 402

{
  "code": "DAILY_CHARGE_LIMIT_EXCEEDED",
  "msg": "Daily charge limit exceeded",
  "data": {
    "dailyLimit": 500,
    "chargedOrReservedToday": 498,
    "requestedAmount": 4
  }
}

HTTP 502

{
  "code": "PAYMENT_STATUS_UNKNOWN",
  "msg": "Payment status unknown; do not retry immediately",
  "data": {
    "paymentReference": "00000000-0000-0000-0000-000000000000"
  }
}

HTTP 422

{
  "code": "INVOICE_EMAIL_REQUIRED",
  "msg": "A valid invoice email is required"
}

HTTP 500

{
  "code": 500,
  "msg": "Internal server error"
}

overview

Overview 排行

取得首頁主分類交易排行，包含金額、筆數、客單與熱門次分類。

NT$5 起 / 次（依查詢區間計價）

Method	GET
Path	`/api/public/overview/ranking`
Params	無
Example	`https://app.ecpaydata.com.tw/api/public/overview/ranking`

請求範例

curl -s "https://app.ecpaydata.com.tw/api/public/overview/ranking" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

回應欄位	型別	說明
`code`	number	固定為 200。
`data.type`	string	資料類型識別值。
`data.start`	string	回應資料涵蓋的起始日期。
`data.end`	string	回應資料涵蓋的結束日期。
`data.items[].name`	string	分類或付款方式名稱。
`data.items[].total_amount`	number	交易金額。
`data.items[].trade_count`	number	交易筆數。
`data.items[].avg_amount`	number	平均客單價。
`data.items[].producttypename`	string	主分類名稱。
`data.items[].top_subs[]`	string[]	該主分類熱門次分類。

成功回應範例

{
  "code": 200,
  "data": {
    "type": "overview-ranking",
    "start": "2025-01-01",
    "end": "2025-12-26",
    "items": [
      {
        "producttypename": "金融服務",
        "total_amount": 15854722007,
        "trade_count": 4090836,
        "avg_amount": 3876,
        "top_subs": [
          "支付與金流服務",
          "理財與投資服務",
          "保險相關服務"
        ]
      }
    ]
  }
}

錯誤回應範例

HTTP	Message	意思
400	`Idempotency-Key header is required`	付費 API 必須提供唯一的 `Idempotency-Key`，重送相同查詢時沿用同一個 key。
400	`Invalid Idempotency-Key`	`Idempotency-Key` 必須為 8 至 128 字元，只能使用英數字、`.`、`_`、`:`、`-`。
401	`Missing API key`	未提供 `x-api-key` header。
401	`Invalid API key`	API Key 不存在、格式錯誤或已被刪除。
403	`API key is inactive`	API Key 已停用。
403	`API key owner is inactive`	API Key 所屬帳號已停用。
409	`Idempotency-Key was already used for a different request`	同一個 `Idempotency-Key` 已用於不同 path 或 query；請為新查詢產生新 key。
409	`Request with this Idempotency-Key is still processing`	相同請求仍在處理中，請稍後使用同一個 key 重查，不要產生新 key。
402	`Active payment method required`	會員沒有有效的綁定信用卡，請先至會員中心完成綁定。
402	`Card payment failed`	綁定信用卡扣款失敗，本次不會回傳查詢資料；請確認卡片狀態或重新綁定。
402	`Daily charge limit exceeded`	已達每位會員每日 NT$500 的 API 扣款上限；台灣時間隔日歸零，待確認交易也會暫占額度。
502	`Payment status unknown; do not retry immediately`	綠界付款結果仍待確認，請勿立即重試以免重複扣款，並使用 paymentReference 聯絡客服。
422	`A valid invoice email is required`	綁卡時保存的發票 Email 無效；請重新綁卡並填入可收件的 Email。
500	`Internal server error`	系統錯誤，請稍後重試或聯絡支援。

HTTP 400

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "msg": "Idempotency-Key header is required"
}

HTTP 400

{
  "code": "INVALID_IDEMPOTENCY_KEY",
  "msg": "Invalid Idempotency-Key",
  "data": {
    "requirement": "8-128 characters: A-Z, a-z, 0-9, dot, underscore, colon or hyphen"
  }
}

HTTP 401

{
  "code": 401,
  "msg": "Missing API key"
}

HTTP 401

{
  "code": 401,
  "msg": "Invalid API key"
}

HTTP 403

{
  "code": 403,
  "msg": "API key is inactive"
}

HTTP 403

{
  "code": 403,
  "msg": "API key owner is inactive"
}

HTTP 409

{
  "code": "IDEMPOTENCY_KEY_REUSED",
  "msg": "Idempotency-Key was already used for a different request"
}

HTTP 409

{
  "code": "IDEMPOTENCY_IN_PROGRESS",
  "msg": "Request with this Idempotency-Key is still processing"
}

HTTP 402

{
  "code": "PAYMENT_METHOD_REQUIRED",
  "msg": "Active payment method required"
}

HTTP 402

{
  "code": "PAYMENT_FAILED",
  "msg": "Card payment failed"
}

HTTP 402

{
  "code": "DAILY_CHARGE_LIMIT_EXCEEDED",
  "msg": "Daily charge limit exceeded",
  "data": {
    "dailyLimit": 500,
    "chargedOrReservedToday": 498,
    "requestedAmount": 4
  }
}

HTTP 502

{
  "code": "PAYMENT_STATUS_UNKNOWN",
  "msg": "Payment status unknown; do not retry immediately",
  "data": {
    "paymentReference": "00000000-0000-0000-0000-000000000000"
  }
}

HTTP 422

{
  "code": "INVOICE_EMAIL_REQUIRED",
  "msg": "A valid invoice email is required"
}

HTTP 500

{
  "code": 500,
  "msg": "Internal server error"
}

overview

Overview 成長率

取得主分類金額與筆數成長率排行。

NT$5 起 / 次（依查詢區間計價）

Method	GET
Path	`/api/public/overview/growth`
Params	無
Example	`https://app.ecpaydata.com.tw/api/public/overview/growth`

請求範例

curl -s "https://app.ecpaydata.com.tw/api/public/overview/growth" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

回應欄位	型別	說明
`code`	number	固定為 200。
`data.type`	string	固定為 overview-growth。
`data.items[].producttypename`	string	主分類名稱。
`data.items[].current_amount`	number	目前區間交易金額。
`data.items[].previous_amount`	number	前一比較區間交易金額。
`data.items[].growth_rate`	number	金額成長率。
`data.items[].current_count`	number	目前區間交易筆數。
`data.items[].count_growth_rate`	number	筆數成長率。

成功回應範例

{
  "code": 200,
  "data": {
    "type": "overview-growth",
    "start": "2025-01-01",
    "end": "2025-12-26",
    "items": [
      {
        "producttypename": "彩妝保養",
        "current_amount": 3238346622,
        "previous_amount": 2615150862,
        "growth_rate": 23.8,
        "current_count": 357889,
        "previous_count": 359045,
        "count_growth_rate": -0.3
      }
    ]
  }
}

錯誤回應範例

HTTP	Message	意思
400	`Idempotency-Key header is required`	付費 API 必須提供唯一的 `Idempotency-Key`，重送相同查詢時沿用同一個 key。
400	`Invalid Idempotency-Key`	`Idempotency-Key` 必須為 8 至 128 字元，只能使用英數字、`.`、`_`、`:`、`-`。
401	`Missing API key`	未提供 `x-api-key` header。
401	`Invalid API key`	API Key 不存在、格式錯誤或已被刪除。
403	`API key is inactive`	API Key 已停用。
403	`API key owner is inactive`	API Key 所屬帳號已停用。
409	`Idempotency-Key was already used for a different request`	同一個 `Idempotency-Key` 已用於不同 path 或 query；請為新查詢產生新 key。
409	`Request with this Idempotency-Key is still processing`	相同請求仍在處理中，請稍後使用同一個 key 重查，不要產生新 key。
402	`Active payment method required`	會員沒有有效的綁定信用卡，請先至會員中心完成綁定。
402	`Card payment failed`	綁定信用卡扣款失敗，本次不會回傳查詢資料；請確認卡片狀態或重新綁定。
402	`Daily charge limit exceeded`	已達每位會員每日 NT$500 的 API 扣款上限；台灣時間隔日歸零，待確認交易也會暫占額度。
502	`Payment status unknown; do not retry immediately`	綠界付款結果仍待確認，請勿立即重試以免重複扣款，並使用 paymentReference 聯絡客服。
422	`A valid invoice email is required`	綁卡時保存的發票 Email 無效；請重新綁卡並填入可收件的 Email。
500	`Internal server error`	系統錯誤，請稍後重試或聯絡支援。

HTTP 400

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "msg": "Idempotency-Key header is required"
}

HTTP 400

{
  "code": "INVALID_IDEMPOTENCY_KEY",
  "msg": "Invalid Idempotency-Key",
  "data": {
    "requirement": "8-128 characters: A-Z, a-z, 0-9, dot, underscore, colon or hyphen"
  }
}

HTTP 401

{
  "code": 401,
  "msg": "Missing API key"
}

HTTP 401

{
  "code": 401,
  "msg": "Invalid API key"
}

HTTP 403

{
  "code": 403,
  "msg": "API key is inactive"
}

HTTP 403

{
  "code": 403,
  "msg": "API key owner is inactive"
}

HTTP 409

{
  "code": "IDEMPOTENCY_KEY_REUSED",
  "msg": "Idempotency-Key was already used for a different request"
}

HTTP 409

{
  "code": "IDEMPOTENCY_IN_PROGRESS",
  "msg": "Request with this Idempotency-Key is still processing"
}

HTTP 402

{
  "code": "PAYMENT_METHOD_REQUIRED",
  "msg": "Active payment method required"
}

HTTP 402

{
  "code": "PAYMENT_FAILED",
  "msg": "Card payment failed"
}

HTTP 402

{
  "code": "DAILY_CHARGE_LIMIT_EXCEEDED",
  "msg": "Daily charge limit exceeded",
  "data": {
    "dailyLimit": 500,
    "chargedOrReservedToday": 498,
    "requestedAmount": 4
  }
}

HTTP 502

{
  "code": "PAYMENT_STATUS_UNKNOWN",
  "msg": "Payment status unknown; do not retry immediately",
  "data": {
    "paymentReference": "00000000-0000-0000-0000-000000000000"
  }
}

HTTP 422

{
  "code": "INVOICE_EMAIL_REQUIRED",
  "msg": "A valid invoice email is required"
}

HTTP 500

{
  "code": 500,
  "msg": "Internal server error"
}

overview

Overview 付款方式

取得首頁付款方式分佈。

NT$5 起 / 次（依查詢區間計價）

Method	GET
Path	`/api/public/overview/payment`
Params	無
Example	`https://app.ecpaydata.com.tw/api/public/overview/payment`

請求範例

curl -s "https://app.ecpaydata.com.tw/api/public/overview/payment" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

回應欄位	型別	說明
`code`	number	固定為 200。
`data.type`	string	資料類型識別值。
`data.start`	string	回應資料涵蓋的起始日期。
`data.end`	string	回應資料涵蓋的結束日期。
`data.items[].name`	string	付款方式名稱。
`data.items[].count`	number	交易筆數。
`data.items[].percent`	string	該付款方式佔比。

成功回應範例

{
  "code": 200,
  "data": {
    "type": "overview-payment",
    "start": "2025-01-01",
    "end": "2025-12-26",
    "items": [
      {
        "name": "信用卡",
        "count": 1262379,
        "percent": "66.8%"
      },
      {
        "name": "ATM 虛擬帳號",
        "count": 245834,
        "percent": "13.0%"
      },
      {
        "name": "超商代碼",
        "count": 170524,
        "percent": "9.0%"
      }
    ]
  }
}

錯誤回應範例

HTTP	Message	意思
400	`Idempotency-Key header is required`	付費 API 必須提供唯一的 `Idempotency-Key`，重送相同查詢時沿用同一個 key。
400	`Invalid Idempotency-Key`	`Idempotency-Key` 必須為 8 至 128 字元，只能使用英數字、`.`、`_`、`:`、`-`。
401	`Missing API key`	未提供 `x-api-key` header。
401	`Invalid API key`	API Key 不存在、格式錯誤或已被刪除。
403	`API key is inactive`	API Key 已停用。
403	`API key owner is inactive`	API Key 所屬帳號已停用。
409	`Idempotency-Key was already used for a different request`	同一個 `Idempotency-Key` 已用於不同 path 或 query；請為新查詢產生新 key。
409	`Request with this Idempotency-Key is still processing`	相同請求仍在處理中，請稍後使用同一個 key 重查，不要產生新 key。
402	`Active payment method required`	會員沒有有效的綁定信用卡，請先至會員中心完成綁定。
402	`Card payment failed`	綁定信用卡扣款失敗，本次不會回傳查詢資料；請確認卡片狀態或重新綁定。
402	`Daily charge limit exceeded`	已達每位會員每日 NT$500 的 API 扣款上限；台灣時間隔日歸零，待確認交易也會暫占額度。
502	`Payment status unknown; do not retry immediately`	綠界付款結果仍待確認，請勿立即重試以免重複扣款，並使用 paymentReference 聯絡客服。
422	`A valid invoice email is required`	綁卡時保存的發票 Email 無效；請重新綁卡並填入可收件的 Email。
500	`Internal server error`	系統錯誤，請稍後重試或聯絡支援。

HTTP 400

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "msg": "Idempotency-Key header is required"
}

HTTP 400

{
  "code": "INVALID_IDEMPOTENCY_KEY",
  "msg": "Invalid Idempotency-Key",
  "data": {
    "requirement": "8-128 characters: A-Z, a-z, 0-9, dot, underscore, colon or hyphen"
  }
}

HTTP 401

{
  "code": 401,
  "msg": "Missing API key"
}

HTTP 401

{
  "code": 401,
  "msg": "Invalid API key"
}

HTTP 403

{
  "code": 403,
  "msg": "API key is inactive"
}

HTTP 403

{
  "code": 403,
  "msg": "API key owner is inactive"
}

HTTP 409

{
  "code": "IDEMPOTENCY_KEY_REUSED",
  "msg": "Idempotency-Key was already used for a different request"
}

HTTP 409

{
  "code": "IDEMPOTENCY_IN_PROGRESS",
  "msg": "Request with this Idempotency-Key is still processing"
}

HTTP 402

{
  "code": "PAYMENT_METHOD_REQUIRED",
  "msg": "Active payment method required"
}

HTTP 402

{
  "code": "PAYMENT_FAILED",
  "msg": "Card payment failed"
}

HTTP 402

{
  "code": "DAILY_CHARGE_LIMIT_EXCEEDED",
  "msg": "Daily charge limit exceeded",
  "data": {
    "dailyLimit": 500,
    "chargedOrReservedToday": 498,
    "requestedAmount": 4
  }
}

HTTP 502

{
  "code": "PAYMENT_STATUS_UNKNOWN",
  "msg": "Payment status unknown; do not retry immediately",
  "data": {
    "paymentReference": "00000000-0000-0000-0000-000000000000"
  }
}

HTTP 422

{
  "code": "INVOICE_EMAIL_REQUIRED",
  "msg": "A valid invoice email is required"
}

HTTP 500

{
  "code": 500,
  "msg": "Internal server error"
}

Market

主分類市場分析資料。

market

Market 趨勢

取得主分類市場的週度交易趨勢。

NT$5 起 / 次（依查詢區間計價）

Method	GET
Path	`/api/public/trends/market`
Params	category、start、end 選填
Example	`https://app.ecpaydata.com.tw/api/public/trends/market?category=%E7%BE%8E%E5%A6%9D%E4%BF%9D%E9%A4%8A&start=2025-07-01&end=2025-12-26`

Param	Required	Description	Example
`category`	no	主分類名稱。未提供或無效時會使用系統預設主分類。	美妝保養
`start`	no	查詢起始日期，格式為 YYYY-MM-DD。	2025-07-01
`end`	no	查詢結束日期，格式為 YYYY-MM-DD。	2025-12-26

請求範例

curl -s "https://app.ecpaydata.com.tw/api/public/trends/market?category=%E7%BE%8E%E5%A6%9D%E4%BF%9D%E9%A4%8A&start=2025-07-01&end=2025-12-26" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

回應欄位	型別	說明
`code`	number	固定為 200。
`data.type`	string	資料類型識別值。
`data.granularity`	string	趨勢粒度；週聚合可用時為 week，尚未建立或刷新時暫回退為 month。
`data.start`	string	回應資料涵蓋的起始日期。
`data.end`	string	回應資料涵蓋的結束日期。
`data.trend[].month`	string	週區間標籤，格式為 MM/DD-MM/DD；欄位名保留為 month 以相容既有客戶端。
`data.trend[].week_start`	string	週度資料的完整週起始日，格式為 YYYY-MM-DD；月度 fallback 不提供。
`data.trend[].week_end`	string	週度資料的完整週結束日，格式為 YYYY-MM-DD；月度 fallback 不提供。
`data.trend[].total_amount`	number	該週交易金額。
`data.trend[].trade_count`	number	該週交易筆數。
`data.trend[].avg_amount`	number	該週平均客單價。
`data.category`	string	實際使用的主分類名稱。

成功回應範例

{
  "code": 200,
  "data": {
    "type": "market",
    "granularity": "week",
    "category": "3C周邊",
    "start": "2025-07-01",
    "end": "2025-12-26",
    "trend": [
      {
        "month": "07/07-07/13",
        "week_start": "2025-07-07",
        "week_end": "2025-07-13",
        "total_amount": 33183836,
        "trade_count": 8743,
        "avg_amount": 3795
      },
      {
        "month": "07/14-07/20",
        "week_start": "2025-07-14",
        "week_end": "2025-07-20",
        "total_amount": 40292866,
        "trade_count": 9331,
        "avg_amount": 4319
      }
    ]
  }
}

錯誤回應範例

HTTP	Message	意思
400	`Idempotency-Key header is required`	付費 API 必須提供唯一的 `Idempotency-Key`，重送相同查詢時沿用同一個 key。
400	`Invalid Idempotency-Key`	`Idempotency-Key` 必須為 8 至 128 字元，只能使用英數字、`.`、`_`、`:`、`-`。
401	`Missing API key`	未提供 `x-api-key` header。
401	`Invalid API key`	API Key 不存在、格式錯誤或已被刪除。
403	`API key is inactive`	API Key 已停用。
403	`API key owner is inactive`	API Key 所屬帳號已停用。
409	`Idempotency-Key was already used for a different request`	同一個 `Idempotency-Key` 已用於不同 path 或 query；請為新查詢產生新 key。
409	`Request with this Idempotency-Key is still processing`	相同請求仍在處理中，請稍後使用同一個 key 重查，不要產生新 key。
402	`Active payment method required`	會員沒有有效的綁定信用卡，請先至會員中心完成綁定。
402	`Card payment failed`	綁定信用卡扣款失敗，本次不會回傳查詢資料；請確認卡片狀態或重新綁定。
402	`Daily charge limit exceeded`	已達每位會員每日 NT$500 的 API 扣款上限；台灣時間隔日歸零，待確認交易也會暫占額度。
502	`Payment status unknown; do not retry immediately`	綠界付款結果仍待確認，請勿立即重試以免重複扣款，並使用 paymentReference 聯絡客服。
422	`A valid invoice email is required`	綁卡時保存的發票 Email 無效；請重新綁卡並填入可收件的 Email。
500	`Internal server error`	系統錯誤，請稍後重試或聯絡支援。

HTTP 400

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "msg": "Idempotency-Key header is required"
}

HTTP 400

{
  "code": "INVALID_IDEMPOTENCY_KEY",
  "msg": "Invalid Idempotency-Key",
  "data": {
    "requirement": "8-128 characters: A-Z, a-z, 0-9, dot, underscore, colon or hyphen"
  }
}

HTTP 401

{
  "code": 401,
  "msg": "Missing API key"
}

HTTP 401

{
  "code": 401,
  "msg": "Invalid API key"
}

HTTP 403

{
  "code": 403,
  "msg": "API key is inactive"
}

HTTP 403

{
  "code": 403,
  "msg": "API key owner is inactive"
}

HTTP 409

{
  "code": "IDEMPOTENCY_KEY_REUSED",
  "msg": "Idempotency-Key was already used for a different request"
}

HTTP 409

{
  "code": "IDEMPOTENCY_IN_PROGRESS",
  "msg": "Request with this Idempotency-Key is still processing"
}

HTTP 402

{
  "code": "PAYMENT_METHOD_REQUIRED",
  "msg": "Active payment method required"
}

HTTP 402

{
  "code": "PAYMENT_FAILED",
  "msg": "Card payment failed"
}

HTTP 402

{
  "code": "DAILY_CHARGE_LIMIT_EXCEEDED",
  "msg": "Daily charge limit exceeded",
  "data": {
    "dailyLimit": 500,
    "chargedOrReservedToday": 498,
    "requestedAmount": 4
  }
}

HTTP 502

{
  "code": "PAYMENT_STATUS_UNKNOWN",
  "msg": "Payment status unknown; do not retry immediately",
  "data": {
    "paymentReference": "00000000-0000-0000-0000-000000000000"
  }
}

HTTP 422

{
  "code": "INVOICE_EMAIL_REQUIRED",
  "msg": "A valid invoice email is required"
}

HTTP 500

{
  "code": 500,
  "msg": "Internal server error"
}

market

Market 次分類排行

取得指定主分類底下的次分類交易排行。

NT$5 起 / 次（依查詢區間計價）

Method	GET
Path	`/api/public/market/sub-ranking`
Params	category、start、end 選填
Example	`https://app.ecpaydata.com.tw/api/public/market/sub-ranking?category=%E7%BE%8E%E5%A6%9D%E4%BF%9D%E9%A4%8A&start=2025-07-01&end=2025-12-26`

Param	Required	Description	Example
`category`	no	主分類名稱。未提供或無效時會使用系統預設主分類。	美妝保養
`start`	no	查詢起始日期，格式為 YYYY-MM-DD。	2025-07-01
`end`	no	查詢結束日期，格式為 YYYY-MM-DD。	2025-12-26

請求範例

curl -s "https://app.ecpaydata.com.tw/api/public/market/sub-ranking?category=%E7%BE%8E%E5%A6%9D%E4%BF%9D%E9%A4%8A&start=2025-07-01&end=2025-12-26" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

回應欄位	型別	說明
`code`	number	固定為 200。
`data.type`	string	資料類型識別值。
`data.start`	string	回應資料涵蓋的起始日期。
`data.end`	string	回應資料涵蓋的結束日期。
`data.items[].name`	string	分類或付款方式名稱。
`data.items[].total_amount`	number	交易金額。
`data.items[].trade_count`	number	交易筆數。
`data.items[].avg_amount`	number	平均客單價。
`data.category`	string	實際使用的主分類名稱。

成功回應範例

{
  "code": 200,
  "data": {
    "type": "market-sub-ranking",
    "category": "3C周邊",
    "start": "2025-07-01",
    "end": "2025-12-26",
    "items": [
      {
        "name": "電腦周邊設備",
        "total_amount": 506720263,
        "trade_count": 120008,
        "avg_amount": 4222
      },
      {
        "name": "手機",
        "total_amount": 221828289,
        "trade_count": 85593,
        "avg_amount": 2592
      },
      {
        "name": "筆電與桌機",
        "total_amount": 78126816,
        "trade_count": 11086,
        "avg_amount": 7047
      }
    ]
  }
}

錯誤回應範例

HTTP	Message	意思
400	`Idempotency-Key header is required`	付費 API 必須提供唯一的 `Idempotency-Key`，重送相同查詢時沿用同一個 key。
400	`Invalid Idempotency-Key`	`Idempotency-Key` 必須為 8 至 128 字元，只能使用英數字、`.`、`_`、`:`、`-`。
401	`Missing API key`	未提供 `x-api-key` header。
401	`Invalid API key`	API Key 不存在、格式錯誤或已被刪除。
403	`API key is inactive`	API Key 已停用。
403	`API key owner is inactive`	API Key 所屬帳號已停用。
409	`Idempotency-Key was already used for a different request`	同一個 `Idempotency-Key` 已用於不同 path 或 query；請為新查詢產生新 key。
409	`Request with this Idempotency-Key is still processing`	相同請求仍在處理中，請稍後使用同一個 key 重查，不要產生新 key。
402	`Active payment method required`	會員沒有有效的綁定信用卡，請先至會員中心完成綁定。
402	`Card payment failed`	綁定信用卡扣款失敗，本次不會回傳查詢資料；請確認卡片狀態或重新綁定。
402	`Daily charge limit exceeded`	已達每位會員每日 NT$500 的 API 扣款上限；台灣時間隔日歸零，待確認交易也會暫占額度。
502	`Payment status unknown; do not retry immediately`	綠界付款結果仍待確認，請勿立即重試以免重複扣款，並使用 paymentReference 聯絡客服。
422	`A valid invoice email is required`	綁卡時保存的發票 Email 無效；請重新綁卡並填入可收件的 Email。
500	`Internal server error`	系統錯誤，請稍後重試或聯絡支援。

HTTP 400

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "msg": "Idempotency-Key header is required"
}

HTTP 400

{
  "code": "INVALID_IDEMPOTENCY_KEY",
  "msg": "Invalid Idempotency-Key",
  "data": {
    "requirement": "8-128 characters: A-Z, a-z, 0-9, dot, underscore, colon or hyphen"
  }
}

HTTP 401

{
  "code": 401,
  "msg": "Missing API key"
}

HTTP 401

{
  "code": 401,
  "msg": "Invalid API key"
}

HTTP 403

{
  "code": 403,
  "msg": "API key is inactive"
}

HTTP 403

{
  "code": 403,
  "msg": "API key owner is inactive"
}

HTTP 409

{
  "code": "IDEMPOTENCY_KEY_REUSED",
  "msg": "Idempotency-Key was already used for a different request"
}

HTTP 409

{
  "code": "IDEMPOTENCY_IN_PROGRESS",
  "msg": "Request with this Idempotency-Key is still processing"
}

HTTP 402

{
  "code": "PAYMENT_METHOD_REQUIRED",
  "msg": "Active payment method required"
}

HTTP 402

{
  "code": "PAYMENT_FAILED",
  "msg": "Card payment failed"
}

HTTP 402

{
  "code": "DAILY_CHARGE_LIMIT_EXCEEDED",
  "msg": "Daily charge limit exceeded",
  "data": {
    "dailyLimit": 500,
    "chargedOrReservedToday": 498,
    "requestedAmount": 4
  }
}

HTTP 502

{
  "code": "PAYMENT_STATUS_UNKNOWN",
  "msg": "Payment status unknown; do not retry immediately",
  "data": {
    "paymentReference": "00000000-0000-0000-0000-000000000000"
  }
}

HTTP 422

{
  "code": "INVOICE_EMAIL_REQUIRED",
  "msg": "A valid invoice email is required"
}

HTTP 500

{
  "code": 500,
  "msg": "Internal server error"
}

market

Market 付款方式

取得指定主分類的付款方式分佈。

NT$5 起 / 次（依查詢區間計價）

Method	GET
Path	`/api/public/market/payment`
Params	category、start、end 選填
Example	`https://app.ecpaydata.com.tw/api/public/market/payment?category=%E7%BE%8E%E5%A6%9D%E4%BF%9D%E9%A4%8A&start=2025-07-01&end=2025-12-26`

Param	Required	Description	Example
`category`	no	主分類名稱。未提供或無效時會使用系統預設主分類。	美妝保養
`start`	no	查詢起始日期，格式為 YYYY-MM-DD。	2025-07-01
`end`	no	查詢結束日期，格式為 YYYY-MM-DD。	2025-12-26

請求範例

curl -s "https://app.ecpaydata.com.tw/api/public/market/payment?category=%E7%BE%8E%E5%A6%9D%E4%BF%9D%E9%A4%8A&start=2025-07-01&end=2025-12-26" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

回應欄位	型別	說明
`code`	number	固定為 200。
`data.type`	string	資料類型識別值。
`data.start`	string	回應資料涵蓋的起始日期。
`data.end`	string	回應資料涵蓋的結束日期。
`data.items[].name`	string	付款方式名稱。
`data.items[].count`	number	交易筆數。
`data.items[].percent`	string	該付款方式佔比。
`data.category`	string	實際使用的主分類名稱。

成功回應範例

{
  "code": 200,
  "data": {
    "type": "market-payment",
    "category": "3C周邊",
    "start": "2025-07-01",
    "end": "2025-12-26",
    "items": [
      {
        "name": "信用卡",
        "count": 148428,
        "percent": "63.9%"
      },
      {
        "name": "超商代碼",
        "count": 35188,
        "percent": "15.1%"
      },
      {
        "name": "ATM 虛擬帳號",
        "count": 27895,
        "percent": "12.0%"
      }
    ]
  }
}

錯誤回應範例

HTTP	Message	意思
400	`Idempotency-Key header is required`	付費 API 必須提供唯一的 `Idempotency-Key`，重送相同查詢時沿用同一個 key。
400	`Invalid Idempotency-Key`	`Idempotency-Key` 必須為 8 至 128 字元，只能使用英數字、`.`、`_`、`:`、`-`。
401	`Missing API key`	未提供 `x-api-key` header。
401	`Invalid API key`	API Key 不存在、格式錯誤或已被刪除。
403	`API key is inactive`	API Key 已停用。
403	`API key owner is inactive`	API Key 所屬帳號已停用。
409	`Idempotency-Key was already used for a different request`	同一個 `Idempotency-Key` 已用於不同 path 或 query；請為新查詢產生新 key。
409	`Request with this Idempotency-Key is still processing`	相同請求仍在處理中，請稍後使用同一個 key 重查，不要產生新 key。
402	`Active payment method required`	會員沒有有效的綁定信用卡，請先至會員中心完成綁定。
402	`Card payment failed`	綁定信用卡扣款失敗，本次不會回傳查詢資料；請確認卡片狀態或重新綁定。
402	`Daily charge limit exceeded`	已達每位會員每日 NT$500 的 API 扣款上限；台灣時間隔日歸零，待確認交易也會暫占額度。
502	`Payment status unknown; do not retry immediately`	綠界付款結果仍待確認，請勿立即重試以免重複扣款，並使用 paymentReference 聯絡客服。
422	`A valid invoice email is required`	綁卡時保存的發票 Email 無效；請重新綁卡並填入可收件的 Email。
500	`Internal server error`	系統錯誤，請稍後重試或聯絡支援。

HTTP 400

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "msg": "Idempotency-Key header is required"
}

HTTP 400

{
  "code": "INVALID_IDEMPOTENCY_KEY",
  "msg": "Invalid Idempotency-Key",
  "data": {
    "requirement": "8-128 characters: A-Z, a-z, 0-9, dot, underscore, colon or hyphen"
  }
}

HTTP 401

{
  "code": 401,
  "msg": "Missing API key"
}

HTTP 401

{
  "code": 401,
  "msg": "Invalid API key"
}

HTTP 403

{
  "code": 403,
  "msg": "API key is inactive"
}

HTTP 403

{
  "code": 403,
  "msg": "API key owner is inactive"
}

HTTP 409

{
  "code": "IDEMPOTENCY_KEY_REUSED",
  "msg": "Idempotency-Key was already used for a different request"
}

HTTP 409

{
  "code": "IDEMPOTENCY_IN_PROGRESS",
  "msg": "Request with this Idempotency-Key is still processing"
}

HTTP 402

{
  "code": "PAYMENT_METHOD_REQUIRED",
  "msg": "Active payment method required"
}

HTTP 402

{
  "code": "PAYMENT_FAILED",
  "msg": "Card payment failed"
}

HTTP 402

{
  "code": "DAILY_CHARGE_LIMIT_EXCEEDED",
  "msg": "Daily charge limit exceeded",
  "data": {
    "dailyLimit": 500,
    "chargedOrReservedToday": 498,
    "requestedAmount": 4
  }
}

HTTP 502

{
  "code": "PAYMENT_STATUS_UNKNOWN",
  "msg": "Payment status unknown; do not retry immediately",
  "data": {
    "paymentReference": "00000000-0000-0000-0000-000000000000"
  }
}

HTTP 422

{
  "code": "INVOICE_EMAIL_REQUIRED",
  "msg": "A valid invoice email is required"
}

HTTP 500

{
  "code": 500,
  "msg": "Internal server error"
}

market

Market 數據焦點

取得指定主分類的人維度與交易焦點指標。其中 tradeCount、totalAmount、avgAmount 為目前查詢區間的全付款方式交易口徑；audienceCount、frequency、arpu 僅統計信用卡、信用卡分期與銀聯且具會員識別的訂單。

NT$5 起 / 次（依查詢區間計價）

Method	GET
Path	`/api/public/market/focus`
Params	category、start、end 選填
Example	`https://app.ecpaydata.com.tw/api/public/market/focus?category=%E7%BE%8E%E5%A6%9D%E4%BF%9D%E9%A4%8A&start=2025-07-01&end=2025-12-26`

Param	Required	Description	Example
`category`	no	主分類名稱。未提供或無效時會使用系統預設主分類。	美妝保養
`start`	no	查詢起始日期，格式為 YYYY-MM-DD。	2025-07-01
`end`	no	查詢結束日期，格式為 YYYY-MM-DD。	2025-12-26

請求範例

curl -s "https://app.ecpaydata.com.tw/api/public/market/focus?category=%E7%BE%8E%E5%A6%9D%E4%BF%9D%E9%A4%8A&start=2025-07-01&end=2025-12-26" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

回應欄位	型別	說明
`code`	number	固定為 200。
`data.type`	string	資料類型識別值。
`data.category`	string	主分類名稱。
`data.start`	string	回應資料涵蓋的起始日期。
`data.end`	string	回應資料涵蓋的結束日期。
`data.focus`	object	目前區間的人維度與交易焦點指標。其中 tradeCount、totalAmount、avgAmount 為目前查詢區間的全付款方式交易口徑；audienceCount、frequency、arpu 僅統計信用卡、信用卡分期與銀聯且具會員識別的訂單。
`data.prevFocus`	object\|null	前一比較區間的人維度與交易焦點指標；若該 endpoint 未提供比較期則為 null。其中 tradeCount、totalAmount、avgAmount 為目前查詢區間的全付款方式交易口徑；audienceCount、frequency、arpu 僅統計信用卡、信用卡分期與銀聯且具會員識別的訂單。

成功回應範例

{
  "code": 200,
  "data": {
    "type": "market-focus",
    "category": "3C周邊",
    "start": "2025-07-01",
    "end": "2025-12-26",
    "focus": {
      "tradeCount": 232406,
      "totalAmount": 909019948,
      "avgAmount": 3911,
      "merchantCount": 4011,
      "audienceCount": 52589,
      "frequency": 4.42,
      "arpu": 17285
    },
    "prevFocus": {
      "tradeCount": 286402,
      "totalAmount": 947358328,
      "avgAmount": 3308,
      "merchantCount": 3851,
      "audienceCount": 51940,
      "frequency": 5.51,
      "arpu": 18239
    }
  }
}

錯誤回應範例

HTTP	Message	意思
400	`Idempotency-Key header is required`	付費 API 必須提供唯一的 `Idempotency-Key`，重送相同查詢時沿用同一個 key。
400	`Invalid Idempotency-Key`	`Idempotency-Key` 必須為 8 至 128 字元，只能使用英數字、`.`、`_`、`:`、`-`。
401	`Missing API key`	未提供 `x-api-key` header。
401	`Invalid API key`	API Key 不存在、格式錯誤或已被刪除。
403	`API key is inactive`	API Key 已停用。
403	`API key owner is inactive`	API Key 所屬帳號已停用。
409	`Idempotency-Key was already used for a different request`	同一個 `Idempotency-Key` 已用於不同 path 或 query；請為新查詢產生新 key。
409	`Request with this Idempotency-Key is still processing`	相同請求仍在處理中，請稍後使用同一個 key 重查，不要產生新 key。
402	`Active payment method required`	會員沒有有效的綁定信用卡，請先至會員中心完成綁定。
402	`Card payment failed`	綁定信用卡扣款失敗，本次不會回傳查詢資料；請確認卡片狀態或重新綁定。
402	`Daily charge limit exceeded`	已達每位會員每日 NT$500 的 API 扣款上限；台灣時間隔日歸零，待確認交易也會暫占額度。
502	`Payment status unknown; do not retry immediately`	綠界付款結果仍待確認，請勿立即重試以免重複扣款，並使用 paymentReference 聯絡客服。
422	`A valid invoice email is required`	綁卡時保存的發票 Email 無效；請重新綁卡並填入可收件的 Email。
500	`Internal server error`	系統錯誤，請稍後重試或聯絡支援。

HTTP 400

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "msg": "Idempotency-Key header is required"
}

HTTP 400

{
  "code": "INVALID_IDEMPOTENCY_KEY",
  "msg": "Invalid Idempotency-Key",
  "data": {
    "requirement": "8-128 characters: A-Z, a-z, 0-9, dot, underscore, colon or hyphen"
  }
}

HTTP 401

{
  "code": 401,
  "msg": "Missing API key"
}

HTTP 401

{
  "code": 401,
  "msg": "Invalid API key"
}

HTTP 403

{
  "code": 403,
  "msg": "API key is inactive"
}

HTTP 403

{
  "code": 403,
  "msg": "API key owner is inactive"
}

HTTP 409

{
  "code": "IDEMPOTENCY_KEY_REUSED",
  "msg": "Idempotency-Key was already used for a different request"
}

HTTP 409

{
  "code": "IDEMPOTENCY_IN_PROGRESS",
  "msg": "Request with this Idempotency-Key is still processing"
}

HTTP 402

{
  "code": "PAYMENT_METHOD_REQUIRED",
  "msg": "Active payment method required"
}

HTTP 402

{
  "code": "PAYMENT_FAILED",
  "msg": "Card payment failed"
}

HTTP 402

{
  "code": "DAILY_CHARGE_LIMIT_EXCEEDED",
  "msg": "Daily charge limit exceeded",
  "data": {
    "dailyLimit": 500,
    "chargedOrReservedToday": 498,
    "requestedAmount": 4
  }
}

HTTP 502

{
  "code": "PAYMENT_STATUS_UNKNOWN",
  "msg": "Payment status unknown; do not retry immediately",
  "data": {
    "paymentReference": "00000000-0000-0000-0000-000000000000"
  }
}

HTTP 422

{
  "code": "INVOICE_EMAIL_REQUIRED",
  "msg": "A valid invoice email is required"
}

HTTP 500

{
  "code": 500,
  "msg": "Internal server error"
}

Sub-market

次市場分析資料。

sub-market

Sub-market 趨勢

取得指定次分類的週度交易趨勢。

NT$10 起 / 次（依查詢區間計價）

Method	GET
Path	`/api/public/trends/sub-market`
Params	category、sub、start、end 選填
Example	`https://app.ecpaydata.com.tw/api/public/trends/sub-market?category=%E7%BE%8E%E5%A6%9D%E4%BF%9D%E9%A4%8A&sub=%E7%B2%BE%E8%8F%AF%E6%B6%B2&start=2025-07-01&end=2025-12-26`

Param	Required	Description	Example
`category`	no	主分類名稱。未提供或無效時會使用系統預設主分類。	美妝保養
`sub`	no	次分類名稱。未提供或無效時會使用系統預設次分類。	精華液
`start`	no	查詢起始日期，格式為 YYYY-MM-DD。	2025-07-01
`end`	no	查詢結束日期，格式為 YYYY-MM-DD。	2025-12-26

請求範例

curl -s "https://app.ecpaydata.com.tw/api/public/trends/sub-market?category=%E7%BE%8E%E5%A6%9D%E4%BF%9D%E9%A4%8A&sub=%E7%B2%BE%E8%8F%AF%E6%B6%B2&start=2025-07-01&end=2025-12-26" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

回應欄位	型別	說明
`code`	number	固定為 200。
`data.type`	string	資料類型識別值。
`data.granularity`	string	趨勢粒度；週聚合可用時為 week，尚未建立或刷新時暫回退為 month。
`data.start`	string	回應資料涵蓋的起始日期。
`data.end`	string	回應資料涵蓋的結束日期。
`data.trend[].month`	string	週區間標籤，格式為 MM/DD-MM/DD；欄位名保留為 month 以相容既有客戶端。
`data.trend[].week_start`	string	週度資料的完整週起始日，格式為 YYYY-MM-DD；月度 fallback 不提供。
`data.trend[].week_end`	string	週度資料的完整週結束日，格式為 YYYY-MM-DD；月度 fallback 不提供。
`data.trend[].total_amount`	number	該週交易金額。
`data.trend[].trade_count`	number	該週交易筆數。
`data.trend[].avg_amount`	number	該週平均客單價。
`data.category`	string	實際使用的主分類名稱。
`data.subCategory`	string	實際使用的次分類名稱。

成功回應範例

{
  "code": 200,
  "data": {
    "type": "sub-market",
    "granularity": "week",
    "category": "3C周邊",
    "subCategory": "平板",
    "start": "2025-07-01",
    "end": "2025-12-26",
    "trend": [
      {
        "month": "07/07-07/13",
        "week_start": "2025-07-07",
        "week_end": "2025-07-13",
        "total_amount": 3626635,
        "trade_count": 460,
        "avg_amount": 7888
      },
      {
        "month": "07/14-07/20",
        "week_start": "2025-07-14",
        "week_end": "2025-07-20",
        "total_amount": 3421084,
        "trade_count": 444,
        "avg_amount": 7709
      }
    ]
  }
}

錯誤回應範例

HTTP	Message	意思
400	`Idempotency-Key header is required`	付費 API 必須提供唯一的 `Idempotency-Key`，重送相同查詢時沿用同一個 key。
400	`Invalid Idempotency-Key`	`Idempotency-Key` 必須為 8 至 128 字元，只能使用英數字、`.`、`_`、`:`、`-`。
401	`Missing API key`	未提供 `x-api-key` header。
401	`Invalid API key`	API Key 不存在、格式錯誤或已被刪除。
403	`API key is inactive`	API Key 已停用。
403	`API key owner is inactive`	API Key 所屬帳號已停用。
409	`Idempotency-Key was already used for a different request`	同一個 `Idempotency-Key` 已用於不同 path 或 query；請為新查詢產生新 key。
409	`Request with this Idempotency-Key is still processing`	相同請求仍在處理中，請稍後使用同一個 key 重查，不要產生新 key。
402	`Active payment method required`	會員沒有有效的綁定信用卡，請先至會員中心完成綁定。
402	`Card payment failed`	綁定信用卡扣款失敗，本次不會回傳查詢資料；請確認卡片狀態或重新綁定。
402	`Daily charge limit exceeded`	已達每位會員每日 NT$500 的 API 扣款上限；台灣時間隔日歸零，待確認交易也會暫占額度。
502	`Payment status unknown; do not retry immediately`	綠界付款結果仍待確認，請勿立即重試以免重複扣款，並使用 paymentReference 聯絡客服。
422	`A valid invoice email is required`	綁卡時保存的發票 Email 無效；請重新綁卡並填入可收件的 Email。
500	`Internal server error`	系統錯誤，請稍後重試或聯絡支援。

HTTP 400

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "msg": "Idempotency-Key header is required"
}

HTTP 400

{
  "code": "INVALID_IDEMPOTENCY_KEY",
  "msg": "Invalid Idempotency-Key",
  "data": {
    "requirement": "8-128 characters: A-Z, a-z, 0-9, dot, underscore, colon or hyphen"
  }
}

HTTP 401

{
  "code": 401,
  "msg": "Missing API key"
}

HTTP 401

{
  "code": 401,
  "msg": "Invalid API key"
}

HTTP 403

{
  "code": 403,
  "msg": "API key is inactive"
}

HTTP 403

{
  "code": 403,
  "msg": "API key owner is inactive"
}

HTTP 409

{
  "code": "IDEMPOTENCY_KEY_REUSED",
  "msg": "Idempotency-Key was already used for a different request"
}

HTTP 409

{
  "code": "IDEMPOTENCY_IN_PROGRESS",
  "msg": "Request with this Idempotency-Key is still processing"
}

HTTP 402

{
  "code": "PAYMENT_METHOD_REQUIRED",
  "msg": "Active payment method required"
}

HTTP 402

{
  "code": "PAYMENT_FAILED",
  "msg": "Card payment failed"
}

HTTP 402

{
  "code": "DAILY_CHARGE_LIMIT_EXCEEDED",
  "msg": "Daily charge limit exceeded",
  "data": {
    "dailyLimit": 500,
    "chargedOrReservedToday": 498,
    "requestedAmount": 4
  }
}

HTTP 502

{
  "code": "PAYMENT_STATUS_UNKNOWN",
  "msg": "Payment status unknown; do not retry immediately",
  "data": {
    "paymentReference": "00000000-0000-0000-0000-000000000000"
  }
}

HTTP 422

{
  "code": "INVOICE_EMAIL_REQUIRED",
  "msg": "A valid invoice email is required"
}

HTTP 500

{
  "code": 500,
  "msg": "Internal server error"
}

sub-market

Sub-market 數據焦點

取得指定次分類的人維度與交易焦點指標。其中 tradeCount、totalAmount、avgAmount 為目前查詢區間的全付款方式交易口徑；audienceCount、frequency、arpu 僅統計信用卡、信用卡分期與銀聯且具會員識別的訂單。

NT$10 起 / 次（依查詢區間計價）

Method	GET
Path	`/api/public/sub-market/focus`
Params	category、sub、start、end 選填
Example	`https://app.ecpaydata.com.tw/api/public/sub-market/focus?category=%E7%BE%8E%E5%A6%9D%E4%BF%9D%E9%A4%8A&sub=%E7%B2%BE%E8%8F%AF%E6%B6%B2&start=2025-07-01&end=2025-12-26`

Param	Required	Description	Example
`category`	no	主分類名稱。未提供或無效時會使用系統預設主分類。	美妝保養
`sub`	no	次分類名稱。未提供或無效時會使用系統預設次分類。	精華液
`start`	no	查詢起始日期，格式為 YYYY-MM-DD。	2025-07-01
`end`	no	查詢結束日期，格式為 YYYY-MM-DD。	2025-12-26

請求範例

curl -s "https://app.ecpaydata.com.tw/api/public/sub-market/focus?category=%E7%BE%8E%E5%A6%9D%E4%BF%9D%E9%A4%8A&sub=%E7%B2%BE%E8%8F%AF%E6%B6%B2&start=2025-07-01&end=2025-12-26" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

回應欄位	型別	說明
`code`	number	固定為 200。
`data.type`	string	資料類型識別值。
`data.category`	string	主分類名稱。
`data.start`	string	回應資料涵蓋的起始日期。
`data.end`	string	回應資料涵蓋的結束日期。
`data.focus`	object	目前區間的人維度與交易焦點指標。其中 tradeCount、totalAmount、avgAmount 為目前查詢區間的全付款方式交易口徑；audienceCount、frequency、arpu 僅統計信用卡、信用卡分期與銀聯且具會員識別的訂單。
`data.prevFocus`	object\|null	前一比較區間的人維度與交易焦點指標；若該 endpoint 未提供比較期則為 null。其中 tradeCount、totalAmount、avgAmount 為目前查詢區間的全付款方式交易口徑；audienceCount、frequency、arpu 僅統計信用卡、信用卡分期與銀聯且具會員識別的訂單。
`data.subCategory`	string	實際使用的次分類名稱。

成功回應範例

{
  "code": 200,
  "data": {
    "type": "sub-market-focus",
    "category": "3C周邊",
    "subCategory": "平板",
    "start": "2025-07-01",
    "end": "2025-12-26",
    "focus": {
      "tradeCount": 9880,
      "totalAmount": 76501807,
      "avgAmount": 7743,
      "merchantCount": 25,
      "audienceCount": 747,
      "frequency": 13.23,
      "arpu": 102412
    },
    "prevFocus": null
  }
}

錯誤回應範例

HTTP	Message	意思
400	`Idempotency-Key header is required`	付費 API 必須提供唯一的 `Idempotency-Key`，重送相同查詢時沿用同一個 key。
400	`Invalid Idempotency-Key`	`Idempotency-Key` 必須為 8 至 128 字元，只能使用英數字、`.`、`_`、`:`、`-`。
401	`Missing API key`	未提供 `x-api-key` header。
401	`Invalid API key`	API Key 不存在、格式錯誤或已被刪除。
403	`API key is inactive`	API Key 已停用。
403	`API key owner is inactive`	API Key 所屬帳號已停用。
409	`Idempotency-Key was already used for a different request`	同一個 `Idempotency-Key` 已用於不同 path 或 query；請為新查詢產生新 key。
409	`Request with this Idempotency-Key is still processing`	相同請求仍在處理中，請稍後使用同一個 key 重查，不要產生新 key。
402	`Active payment method required`	會員沒有有效的綁定信用卡，請先至會員中心完成綁定。
402	`Card payment failed`	綁定信用卡扣款失敗，本次不會回傳查詢資料；請確認卡片狀態或重新綁定。
402	`Daily charge limit exceeded`	已達每位會員每日 NT$500 的 API 扣款上限；台灣時間隔日歸零，待確認交易也會暫占額度。
502	`Payment status unknown; do not retry immediately`	綠界付款結果仍待確認，請勿立即重試以免重複扣款，並使用 paymentReference 聯絡客服。
422	`A valid invoice email is required`	綁卡時保存的發票 Email 無效；請重新綁卡並填入可收件的 Email。
500	`Internal server error`	系統錯誤，請稍後重試或聯絡支援。

HTTP 400

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "msg": "Idempotency-Key header is required"
}

HTTP 400

{
  "code": "INVALID_IDEMPOTENCY_KEY",
  "msg": "Invalid Idempotency-Key",
  "data": {
    "requirement": "8-128 characters: A-Z, a-z, 0-9, dot, underscore, colon or hyphen"
  }
}

HTTP 401

{
  "code": 401,
  "msg": "Missing API key"
}

HTTP 401

{
  "code": 401,
  "msg": "Invalid API key"
}

HTTP 403

{
  "code": 403,
  "msg": "API key is inactive"
}

HTTP 403

{
  "code": 403,
  "msg": "API key owner is inactive"
}

HTTP 409

{
  "code": "IDEMPOTENCY_KEY_REUSED",
  "msg": "Idempotency-Key was already used for a different request"
}

HTTP 409

{
  "code": "IDEMPOTENCY_IN_PROGRESS",
  "msg": "Request with this Idempotency-Key is still processing"
}

HTTP 402

{
  "code": "PAYMENT_METHOD_REQUIRED",
  "msg": "Active payment method required"
}

HTTP 402

{
  "code": "PAYMENT_FAILED",
  "msg": "Card payment failed"
}

HTTP 402

{
  "code": "DAILY_CHARGE_LIMIT_EXCEEDED",
  "msg": "Daily charge limit exceeded",
  "data": {
    "dailyLimit": 500,
    "chargedOrReservedToday": 498,
    "requestedAmount": 4
  }
}

HTTP 502

{
  "code": "PAYMENT_STATUS_UNKNOWN",
  "msg": "Payment status unknown; do not retry immediately",
  "data": {
    "paymentReference": "00000000-0000-0000-0000-000000000000"
  }
}

HTTP 422

{
  "code": "INVOICE_EMAIL_REQUIRED",
  "msg": "A valid invoice email is required"
}

HTTP 500

{
  "code": 500,
  "msg": "Internal server error"
}

sub-market

Sub-market 常見商品標籤

取得指定次分類在指定期間內有成交商品的常見直覺商品標籤與覆蓋率；標籤可重疊，百分比不一定加總為 100%。

NT$15 起 / 次（依查詢區間計價）

Method	GET
Path	`/api/public/sub-market/tags`
Params	category、sub、start、end 選填
Example	`https://app.ecpaydata.com.tw/api/public/sub-market/tags?category=3C%E5%91%A8%E9%82%8A&sub=%E5%B9%B3%E6%9D%BF&start=2025-07-01&end=2025-12-26`

Param	Required	Description	Example
`category`	no	主分類名稱。未提供或無效時會使用系統預設主分類。	美妝保養
`sub`	no	次分類名稱。未提供或無效時會使用系統預設次分類。	精華液
`start`	no	查詢起始日期，格式為 YYYY-MM-DD。	2025-07-01
`end`	no	查詢結束日期，格式為 YYYY-MM-DD。	2025-12-26

請求範例

curl -s "https://app.ecpaydata.com.tw/api/public/sub-market/tags?category=3C%E5%91%A8%E9%82%8A&sub=%E5%B9%B3%E6%9D%BF&start=2025-07-01&end=2025-12-26" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

回應欄位	型別	說明
`code`	number	固定為 200。
`data.type`	string	固定為 sub-market-tags。
`data.category`	string	實際使用的主分類名稱。
`data.subCategory`	string	實際使用的次分類名稱。
`data.start`	string	回應資料涵蓋的起始日期。
`data.end`	string	回應資料涵蓋的結束日期。
`data.items[].key`	string	TAG 維度名稱，例如類型、功能。
`data.items[].value`	string	TAG 值。
`data.items[].count`	number	指定期間內有成交，且帶有此標籤的商品數。
`data.items[].percent`	number	指定期間內有成交且具任一標籤商品中的覆蓋率；標籤可重疊，因此不一定加總為 100。

成功回應範例

{
  "code": 200,
  "data": {
    "type": "sub-market-tags",
    "category": "3C周邊",
    "subCategory": "平板",
    "start": "2025-07-01",
    "end": "2025-12-26",
    "items": [
      {
        "key": "保護殼",
        "value": "15.6吋",
        "count": 1280,
        "percent": 15.6
      },
      {
        "key": "作業系統",
        "value": "平板",
        "count": 1140,
        "percent": 14
      }
    ]
  }
}

錯誤回應範例

HTTP	Message	意思
400	`Idempotency-Key header is required`	付費 API 必須提供唯一的 `Idempotency-Key`，重送相同查詢時沿用同一個 key。
400	`Invalid Idempotency-Key`	`Idempotency-Key` 必須為 8 至 128 字元，只能使用英數字、`.`、`_`、`:`、`-`。
401	`Missing API key`	未提供 `x-api-key` header。
401	`Invalid API key`	API Key 不存在、格式錯誤或已被刪除。
403	`API key is inactive`	API Key 已停用。
403	`API key owner is inactive`	API Key 所屬帳號已停用。
409	`Idempotency-Key was already used for a different request`	同一個 `Idempotency-Key` 已用於不同 path 或 query；請為新查詢產生新 key。
409	`Request with this Idempotency-Key is still processing`	相同請求仍在處理中，請稍後使用同一個 key 重查，不要產生新 key。
402	`Active payment method required`	會員沒有有效的綁定信用卡，請先至會員中心完成綁定。
402	`Card payment failed`	綁定信用卡扣款失敗，本次不會回傳查詢資料；請確認卡片狀態或重新綁定。
402	`Daily charge limit exceeded`	已達每位會員每日 NT$500 的 API 扣款上限；台灣時間隔日歸零，待確認交易也會暫占額度。
502	`Payment status unknown; do not retry immediately`	綠界付款結果仍待確認，請勿立即重試以免重複扣款，並使用 paymentReference 聯絡客服。
422	`A valid invoice email is required`	綁卡時保存的發票 Email 無效；請重新綁卡並填入可收件的 Email。
500	`Internal server error`	系統錯誤，請稍後重試或聯絡支援。

HTTP 400

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "msg": "Idempotency-Key header is required"
}

HTTP 400

{
  "code": "INVALID_IDEMPOTENCY_KEY",
  "msg": "Invalid Idempotency-Key",
  "data": {
    "requirement": "8-128 characters: A-Z, a-z, 0-9, dot, underscore, colon or hyphen"
  }
}

HTTP 401

{
  "code": 401,
  "msg": "Missing API key"
}

HTTP 401

{
  "code": 401,
  "msg": "Invalid API key"
}

HTTP 403

{
  "code": 403,
  "msg": "API key is inactive"
}

HTTP 403

{
  "code": 403,
  "msg": "API key owner is inactive"
}

HTTP 409

{
  "code": "IDEMPOTENCY_KEY_REUSED",
  "msg": "Idempotency-Key was already used for a different request"
}

HTTP 409

{
  "code": "IDEMPOTENCY_IN_PROGRESS",
  "msg": "Request with this Idempotency-Key is still processing"
}

HTTP 402

{
  "code": "PAYMENT_METHOD_REQUIRED",
  "msg": "Active payment method required"
}

HTTP 402

{
  "code": "PAYMENT_FAILED",
  "msg": "Card payment failed"
}

HTTP 402

{
  "code": "DAILY_CHARGE_LIMIT_EXCEEDED",
  "msg": "Daily charge limit exceeded",
  "data": {
    "dailyLimit": 500,
    "chargedOrReservedToday": 498,
    "requestedAmount": 4
  }
}

HTTP 502

{
  "code": "PAYMENT_STATUS_UNKNOWN",
  "msg": "Payment status unknown; do not retry immediately",
  "data": {
    "paymentReference": "00000000-0000-0000-0000-000000000000"
  }
}

HTTP 422

{
  "code": "INVOICE_EMAIL_REQUIRED",
  "msg": "A valid invoice email is required"
}

HTTP 500

{
  "code": 500,
  "msg": "Internal server error"
}

sub-market

Sub-market 相關購買關聯

取得買過指定次分類的消費者，還買了哪些其他次分類 Top 5；此端點使用目前預設資料區間快取，不支援自訂日期即時計算。

固定 NT$10 / 次

Method	GET
Path	`/api/public/sub-market/related-purchases`
Params	category、sub 選填
Example	`https://app.ecpaydata.com.tw/api/public/sub-market/related-purchases?category=3C%E5%91%A8%E9%82%8A&sub=%E5%B9%B3%E6%9D%BF`

Param	Required	Description	Example
`category`	no	主分類名稱。未提供或無效時會使用系統預設主分類。	美妝保養
`sub`	no	次分類名稱。未提供或無效時會使用系統預設次分類。	精華液

請求範例

curl -s "https://app.ecpaydata.com.tw/api/public/sub-market/related-purchases?category=3C%E5%91%A8%E9%82%8A&sub=%E5%B9%B3%E6%9D%BF" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID"

回應欄位	型別	說明
`code`	number	固定為 200。
`data.type`	string	固定為 sub-market-related-purchases。
`data.category`	string	實際使用的主分類名稱。
`data.subCategory`	string	實際使用的次分類名稱。
`data.start`	string	回應資料涵蓋的起始日期。
`data.end`	string	回應資料涵蓋的結束日期。
`data.items[].category`	string	關聯購買的主分類名稱。
`data.items[].subCategory`	string	關聯購買的次分類名稱。
`data.items[].memberCount`	number	符合關聯條件的消費者人數。
`data.items[].percent`	number	Top 清單內的佔比百分比數值。

成功回應範例

{
  "code": 200,
  "data": {
    "type": "sub-market-related-purchases",
    "category": "3C周邊",
    "subCategory": "平板",
    "start": "2025-07-01",
    "end": "2025-12-26",
    "items": [
      {
        "category": "成人用品",
        "subCategory": "成人用品",
        "memberCount": 1280,
        "percent": 23.9
      },
      {
        "category": "皮膚管理療程",
        "subCategory": "皮膚管理療程",
        "memberCount": 1140,
        "percent": 23.9
      }
    ]
  }
}

錯誤回應範例

HTTP	Message	意思
400	`Idempotency-Key header is required`	付費 API 必須提供唯一的 `Idempotency-Key`，重送相同查詢時沿用同一個 key。
400	`Invalid Idempotency-Key`	`Idempotency-Key` 必須為 8 至 128 字元，只能使用英數字、`.`、`_`、`:`、`-`。
401	`Missing API key`	未提供 `x-api-key` header。
401	`Invalid API key`	API Key 不存在、格式錯誤或已被刪除。
403	`API key is inactive`	API Key 已停用。
403	`API key owner is inactive`	API Key 所屬帳號已停用。
409	`Idempotency-Key was already used for a different request`	同一個 `Idempotency-Key` 已用於不同 path 或 query；請為新查詢產生新 key。
409	`Request with this Idempotency-Key is still processing`	相同請求仍在處理中，請稍後使用同一個 key 重查，不要產生新 key。
402	`Active payment method required`	會員沒有有效的綁定信用卡，請先至會員中心完成綁定。
402	`Card payment failed`	綁定信用卡扣款失敗，本次不會回傳查詢資料；請確認卡片狀態或重新綁定。
402	`Daily charge limit exceeded`	已達每位會員每日 NT$500 的 API 扣款上限；台灣時間隔日歸零，待確認交易也會暫占額度。
502	`Payment status unknown; do not retry immediately`	綠界付款結果仍待確認，請勿立即重試以免重複扣款，並使用 paymentReference 聯絡客服。
422	`A valid invoice email is required`	綁卡時保存的發票 Email 無效；請重新綁卡並填入可收件的 Email。
500	`Internal server error`	系統錯誤，請稍後重試或聯絡支援。

HTTP 400

{
  "code": "IDEMPOTENCY_KEY_REQUIRED",
  "msg": "Idempotency-Key header is required"
}

HTTP 400

{
  "code": "INVALID_IDEMPOTENCY_KEY",
  "msg": "Invalid Idempotency-Key",
  "data": {
    "requirement": "8-128 characters: A-Z, a-z, 0-9, dot, underscore, colon or hyphen"
  }
}

HTTP 401

{
  "code": 401,
  "msg": "Missing API key"
}

HTTP 401

{
  "code": 401,
  "msg": "Invalid API key"
}

HTTP 403

{
  "code": 403,
  "msg": "API key is inactive"
}

HTTP 403

{
  "code": 403,
  "msg": "API key owner is inactive"
}

HTTP 409

{
  "code": "IDEMPOTENCY_KEY_REUSED",
  "msg": "Idempotency-Key was already used for a different request"
}

HTTP 409

{
  "code": "IDEMPOTENCY_IN_PROGRESS",
  "msg": "Request with this Idempotency-Key is still processing"
}

HTTP 402

{
  "code": "PAYMENT_METHOD_REQUIRED",
  "msg": "Active payment method required"
}

HTTP 402

{
  "code": "PAYMENT_FAILED",
  "msg": "Card payment failed"
}

HTTP 402

{
  "code": "DAILY_CHARGE_LIMIT_EXCEEDED",
  "msg": "Daily charge limit exceeded",
  "data": {
    "dailyLimit": 500,
    "chargedOrReservedToday": 498,
    "requestedAmount": 4
  }
}

HTTP 502

{
  "code": "PAYMENT_STATUS_UNKNOWN",
  "msg": "Payment status unknown; do not retry immediately",
  "data": {
    "paymentReference": "00000000-0000-0000-0000-000000000000"
  }
}

HTTP 422

{
  "code": "INVOICE_EMAIL_REQUIRED",
  "msg": "A valid invoice email is required"
}

HTTP 500

{
  "code": 500,
  "msg": "Internal server error"
}

REST API 文件

REST API 文件

Meta

主分類清單

次分類清單

Overview

Overview 趨勢

Overview 排行

Overview 成長率

Overview 付款方式

Market

Market 趨勢

Market 次分類排行

Market 付款方式

Market 數據焦點

Sub-market

Sub-market 趨勢

Sub-market 數據焦點

Sub-market 常見商品標籤

Sub-market 相關購買關聯

Method	GET
Path	`/api/public/meta/categories`
Params	無
Example	`https://app.ecpaydata.com.tw/api/public/meta/categories`

Method	GET
Path	`/api/public/meta/sub-categories`
Params	category 選填
Example	`https://app.ecpaydata.com.tw/api/public/meta/sub-categories?category=%E7%BE%8E%E5%A6%9D%E4%BF%9D%E9%A4%8A`