Logoskills for everything
Agent Skill
2/7/2026

etl-master-data-api

ETL 基本資料查詢 API Skill - 協助查詢 ERP 系統基本資料，包含員工、供應商、會計科目、料件、固定資產、帳款類別、客戶、部門、專案、幣別、匯率等 18 種查詢功能，支援 Token 自動管理與過期刷新機制

D
dafon
0GitHub Stars
1Views
npx skills add Dafon-IT/DF-User-Skills

SKILL.md

Nameetl-master-data-api
DescriptionETL 基本資料查詢 API Skill - 協助查詢 ERP 系統基本資料，包含員工、供應商、會計科目、料件、固定資產、帳款類別、客戶、部門、專案、幣別、匯率等 18 種查詢功能，支援 Token 自動管理與過期刷新機制

name: "etl-master-data-api" description: "ETL 基本資料查詢 API Skill - 協助查詢 ERP 系統基本資料，包含員工、供應商、會計科目、料件、固定資產、帳款類別、客戶、匯率、出貨、部門、專案、幣別等 19 種查詢功能，支援 Token 自動管理與過期刷新機制"

ETL 基本資料查詢 API Skill

此 Skill 提供 ETL 基本資料查詢 API 的完整功能，支援 Windows (PowerShell) 和 Linux/macOS (Bash) 雙平台。

環境設定

環境變數必要性說明
ETL_API_BASE_URL選用API 基礎 URL，預設 https://zpos-api-stage.zerozero.com.tw
ETL_USERNAME必要登入帳號
ETL_PASSWORD必要登入密碼
ETL_ACCESS_TOKEN自動登入後自動設定，30 分鐘過期
ETL_REFRESH_TOKEN自動登入後自動設定，1 小時過期
ETL_TOKEN_EXPIRES自動Token 過期時間 (Unix timestamp)

環境變數設定方式

PowerShell:

$env:ETL_USERNAME = "your_username"
$env:ETL_PASSWORD = "your_password"
# 選用：自訂 API URL
$env:ETL_API_BASE_URL = "https://zpos-api-stage.zerozero.com.tw"

Bash:

export ETL_USERNAME="your_username"
export ETL_PASSWORD="your_password"
# 選用：自訂 API URL
export ETL_API_BASE_URL="https://zpos-api-stage.zerozero.com.tw"

支援的查詢操作

一、基礎資料查詢 (POST 搜尋)

1. 員工資料查詢

  • 端點: /api/etl/employee/search
  • 方法: POST
  • 參數: gen01 (員工編號) / gen02 (員工姓名) / gen06 (Email)
  • 回傳: 員工編號、姓名、部門代碼、部門名稱、Email

2. 供應商查詢

  • 端點: /api/etl/supplier/search
  • 方法: POST
  • 參數: pmc24 (統一編號)
  • 回傳: 供應商代碼、簡稱、全名、付款條件、統編、幣別等

3. 會計科目查詢

  • 端點: /api/etl/account-title/search
  • 方法: POST
  • 參數: aag01 (科目代碼) / aag02 (科目名稱)
  • 回傳: 科目代碼、科目名稱

4. 料件查詢

  • 端點: /api/etl/material/search
  • 方法: POST
  • 參數: ima01 (料件編號) / ima02 (料件名稱)
  • 回傳: 料件編號、料件名稱、規格、計價單位

5. 固定資產查詢

  • 端點: /api/etl/fixed-asset/search
  • 方法: POST
  • 參數: faj02 (資產編號) / faj06 (資產名稱)
  • 回傳: 資產編號、資產名稱

6. 帳款類別查詢

  • 端點: /api/etl/payment-type/search
  • 方法: POST
  • 參數: apr01 (類別代碼) / apr02 (類別名稱)
  • 回傳: 類別代碼、類別名稱

7. 客戶查詢

  • 端點: /api/etl/customer/search
  • 方法: POST
  • 參數: occ01 (客戶代號) / occ02 (客戶名稱)
  • 回傳: 客戶代號、名稱、慣用幣別、銷售分類、地址、收款條件等

8. 匯率查詢

  • 端點: /api/etl/exchange-rate/search
  • 方法: POST
  • 參數: azk02 (匯率日期，格式：YYYY-MM-DD)
  • 回傳: 幣別代碼、日期、買入匯率、賣出匯率

9. 出貨查詢

  • 端點: /api/etl/shipment/search
  • 方法: POST
  • 參數: keyword (關鍵字，如出貨單號)
  • 回傳: 單頭 24 欄 + 單身 10 欄 + 訂單 5 欄（共 39 欄位）

二、基礎資料列表 (GET 列表)

10. 部門列表

  • 端點: /api/etl/department
  • 方法: GET
  • 回傳: 部門代碼 (gem01)、部門名稱 (gem02)

11. 銷售分類列表

  • 端點: /api/etl/sales-category
  • 方法: GET
  • 回傳: 分類代碼 (oab01)、分類名稱 (oab02)

12. 專案編號列表

  • 端點: /api/etl/project
  • 方法: GET
  • 回傳: 專案代碼 (pja01)、專案名稱 (pja02)、WBS 代碼 (wbs_code)

13. 到達起運地列表

  • 端點: /api/etl/shipping-destination
  • 方法: GET
  • 回傳: 起運地代碼 (oac01)、起運地名稱 (oac02)

14. 貿易條件列表

  • 端點: /api/etl/trade-condition
  • 方法: GET
  • 回傳: 條件代碼 (tc_its01)、條件說明 (tc_its02)

15. 銀行列表

  • 端點: /api/etl/bank
  • 方法: GET
  • 回傳: 銀行代碼 (nma01)、銀行名稱 (nma02)

16. 幣別列表

  • 端點: /api/etl/currency
  • 方法: GET
  • 回傳: 幣別代碼 (azi01)、幣別名稱 (azi02)

17. 稅別列表

  • 端點: /api/etl/tax-type
  • 方法: GET
  • 回傳: 稅別代碼 (gec01)、類型 (gec011)、稅別名稱 (gec02)、稅率 (gec04)

18. 收款條件列表

  • 端點: /api/etl/payment-term
  • 方法: GET
  • 回傳: 條件代碼 (oag01)、條件說明 (oag02)

19. 銷售單位列表

  • 端點: /api/etl/sales-unit
  • 方法: GET
  • 回傳: 單位代碼 (gfe01)、單位名稱 (gfe02)

欄位代碼對照表

基礎資料欄位

查詢類型欄位代碼中文說明
員工gen01員工編號
gen02員工姓名
gen03部門代碼
gem02部門名稱
gen06Email
供應商pmc01供應商代碼
pmc03供應商簡稱
pmc081供應商全名
pmc17付款條件
pmc24統一編號
pmc49付款方式
pmc22幣別
pmc47科目代碼
會計科目aag01科目代碼
aag02科目名稱
料件ima01料件編號
ima02料件名稱
ima021規格
ima908計價單位
固定資產faj02資產編號
faj06資產名稱
帳款類別apr01類別代碼
apr02類別名稱

銷售相關欄位

查詢類型欄位代碼中文說明
客戶occ01客戶代號
occ02客戶名稱
occ42慣用幣別
occ43銷售分類
occ231客戶地址
occ44收款條件類型
occ45收款條件代碼
部門gem01部門代碼
gem02部門名稱
銷售分類oab01分類代碼
oab02分類名稱
專案pja01專案代碼
pja02專案名稱
wbs_codeWBS 代碼
起運地oac01起運地代碼
oac02起運地名稱
貿易條件tc_its01條件代碼
tc_its02條件說明
銀行nma01銀行代碼
nma02銀行名稱
幣別azi01幣別代碼
azi02幣別名稱
匯率azk01幣別代碼
azk02匯率日期
azk03買入匯率
azk04賣出匯率
稅別gec01稅別代碼
gec011稅別類型
gec02稅別名稱
gec04稅率
gec06稅別分類
收款條件oag01條件代碼
oag02條件說明
銷售單位gfe01單位代碼
gfe02單位名稱
出貨（單頭）oaydesc單據名稱
oga16訂單單號
oga03帳款客戶編號
oga032帳款客戶簡稱
oga04送貨客戶編號
occ02客戶簡稱（送貨客戶）
oga18收款客戶編號
oga18_ds收款客戶名稱
ta_oga013出貨數量 KG
addr送貨地址
oga14人員編號
oga15部門編號
ogaconf確認否/作廢碼
oga55狀況碼
oga23幣別
oga24匯率
oga21稅別
oga211稅率
oga212聯數
oga05發票別
oga10帳單編號
ogaud10totQ
ogaud11totW
ogaud12totG
出貨（單身）ogb31訂單編號
ogb04產品編號
ogb06品名規格
ima021規格
ogb11客戶產品編號
ogb05銷售單位
ogb916計價單位
ogb917計價數量
ogb41專案代號
ogb42WBS編號
出貨（訂單）oeaconf確認否
oea49狀況碼
oea05發票別
oeb916計價單位
oeb917計價數量

Token 自動管理機制

本 Skill 實作 Token 自動過期檢查與刷新機制：

API 呼叫 → Test-EtlTokenExpiry (檢查過期)
                    ↓
    $env:ETL_TOKEN_EXPIRES < 當前時間?
                    ↓
         是 → Update-EtlToken → 更新 Token + Expires
         否 → 繼續執行 API 呼叫
  • Access Token 有效期：30 分鐘
  • Refresh Token 有效期：1 小時
  • 每次成功登入/刷新後，自動設定 ETL_TOKEN_EXPIRES 為當前時間 + 30 分鐘

執行指引

  1. 確認環境變數 - 確保 ETL_USERNAME 和 ETL_PASSWORD 已設定
  2. 識別作業系統 - 判斷使用者環境為 Windows 或 Linux/macOS
  3. 選擇對應腳本
    • Windows: scripts/powershell/etl-master-data.ps1
    • Linux/macOS: scripts/bash/etl-master-data.sh
  4. 處理編碼 - PowerShell 需設定 UTF-8 編碼以正確顯示中文
  5. 執行前檢查 - 腳本會自動檢查 Token 是否過期並刷新

API 認證格式

所有 API 請求需在 Header 中包含：

Authorization: Bearer {accessToken}

相關資源

與 etl-dictionary-api 的關係

本 Skill 與 etl-dictionary-api 共用相同的認證機制和 API 基礎架構。若已透過 etl-dictionary-api 登入並取得 Token，可直接使用該 Token 進行本 Skill 的查詢操作。

Skills Info
Original Name:etl-master-data-apiAuthor:dafon
Download
View on GitHub