DSCE API 使用指南

數位減碳雲資料交換平台（DSCE） · 權限受控資料交換 API · 適用對象：資訊商 (ISP) 與進階使用者的系統整合開發人員

DSCE API 是疊加在 PACT Pathfinder v3 之上的權限受控層，具備多租戶資料隔離與完整審計。所有端點以 /api/dsce/ 為前綴。原生 v3 API 僅限特定合作廠商，另見 v3 文件。

1. 存取前提

呼叫任何 /api/dsce/* 端點前，需同時滿足：

• 持有有效 Bearer Token（見下方「取得 Bearer Token」）。
• 帳號的 isApiDsceEnabled = 1（已開通）。未開通一律回 403。

1-1. 準備工作：取得憑證

首次使用前，需申請一組 client_id 與 client_secret。

POST/api/auth/credentials（無需任何認證標頭）

成功回應 (200)

{
  "client_id": "dsce-a1b2c3d4",
  "client_secret": "Xy9kLmNoPqRsTuVwXy12"
}

⚠️ client_secret 僅顯示一次，請立即妥善保存。

1-2. 取得 Bearer Token（登入）

以 HTTP Basic Authentication 帶入憑證換取 Bearer Token，Token 有效期限 30 分鐘（1800 秒）。後續所有 DSCE API 動作皆須帶入此 Token。

POST/api/auth/token

請求標頭

標頭	值
Authorization	Basic <Base64(client_id:client_secret)>
Content-Type	application/x-www-form-urlencoded

請求本體

欄位	值
grant_type	client_credentials（固定值）

curl 範例

curl -X POST https://<host>/api/auth/token \
  -u "dsce-a1b2c3d4:Xy9kLmNoPqRsTuVwXy12" \
  -d "grant_type=client_credentials"

成功回應 (200)

{
  "access_token": "eyJhbGci...",
  "expires_in": 1800,
  "token_type": "Bearer",
  "scope": "footprint:list profile footprint:read email"
}

後續所有 DSCE API 請在 Authorization 標頭帶入：Bearer <access_token>

1-3. isApiDsceEnabled 開通流程

1. 使用者向平台申請開通（或由所屬資訊商 / 管理者代為提出）。
2. 管理者於後台「會員管理」審核，將該帳號 isApiDsceEnabled 設為 1。
3. 開通後即可存取 /api/dsce/*。

未開通時的回應：

HTTP/1.1 403 Forbidden
{ "code": "AccessDenied", "message": "PACT DSCE API access is not enabled for this account." }

1-4. 驗證 Token

確認 Token 是否仍有效，並取得 Token 內含的身份資訊。

POST/api/auth/tokenVerify

請求標頭

標頭	值
Authorization	Bearer <access_token>

成功回應 (200)

{
  "valid": true,
  "client_id": "dsce-a1b2c3d4",
  "clientHost": "1.2.3.4",
  "role": {
    "roles": ["offline_access", "uma_authorization", "default-roles-demo"]
  }
}

1-5. 補發憑證（遺失 Client Secret）

重新產生 client_secret，舊的密鑰立即失效。

PATCH/api/auth/credentials/{clientId}

請求標頭

標頭	值
Authorization	Bearer <access_token>

路徑參數

參數	說明
clientId	欲重置密鑰的 Client ID

成功回應 (200)

{
  "client_id": "dsce-a1b2c3d4",
  "client_secret": "NewSecretXyzAbc456"
}

⚠️ 重置後請更新所有使用舊憑證的系統，並重新取得 Token。

2. 身分與資料隔離

身分	可存取的資料範圍
一般 / 進階使用者	僅自身公司 (creator_company_serial = 自身) 的資料
資訊商 (ISP)	自身 + 所有 Auth_Status = 1（已授權）代管客戶的資料

列表端點的 ?company_serial= 篩選：一般／進階使用者一律強制僅回傳自身，忽略此參數；資訊商指定時須為可存取範圍內的公司，否則回 403。

3. 代管機制（X-On-Behalf-Of）

資訊商代表其代管客戶操作碳足跡與事件時，於 HTTP Header 帶入客戶公司序號：

X-On-Behalf-Of: {customerSn}

• 系統驗證【資訊商序號（你自己）+ 客戶序號】於代理關係表為 Auth_Status = 1。
• 驗證失敗 → 回 403。
• 通過後，該次請求的寫入／查詢目標即為該客戶公司；審計日誌同時記錄操作者與目標公司。
• 未帶此 Header 時，目標公司為操作者自身。

此標頭僅碳足跡（footprints）與事件（events）端點支援；公司與代理關係端點不使用。

4. 公司管理 Company

POST/api/dsce/company

僅資訊商可呼叫，用於建立客戶公司。客戶公司不存在→建立並同步發出 Auth_Status=0 待確認代理邀請；已存在→回 409，請改用 POST /api/dsce/provider 發邀請。

curl -X POST https://<host>/api/dsce/company \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{ "agreeVer": true, "companyName": "客戶公司", "taxIDNumber": "12345678",
        "contactName": "王小明", "contactEmail": "a@b.com", "isTaiwan": "Y" }'

GET/api/dsce/company

公司列表。資訊商：自身 + Auth_Status=1 代管客戶；一般／進階使用者：僅自身。

GET / PATCH/api/dsce/company/{serial}

取得 / 更新特定公司資料（須在可存取範圍內，否則 403）。

5. 代理關係 Provider

POST/api/dsce/provider

建立 / 發送代理邀請，預設 Auth_Status = 0（待確認）。Body：customer_serial。

DELETE/api/dsce/provider/{customerSn}

解除代理關係。刪除前系統會先將該客戶公司的 Identity_Type 更新為 3（進階使用者），確保解綁後客戶仍可獨立操作，再刪除代理紀錄。

GET/api/dsce/provider

查詢代理關係清單，可用 ?Auth_Status= 篩選（0 待確認 / 1 已授權 / 2 已解除）。

6. 碳足跡 Footprints

代管操作須帶 X-On-Behalf-Of: {customerSn}。

方法	路徑	說明
POST	/api/dsce/footprints	建立碳足跡（歸屬目標公司）
PATCH	/api/dsce/footprints/{pfpId}	廢棄碳足跡（Deprecated）
GET	/api/dsce/footprints	列表，支援 ?company_serial=、?limit=、?offset=
GET	/api/dsce/footprints/{pfpId}	取得單筆

7. 事件 Events

方法	路徑	說明
POST	/api/dsce/events	建立碳排事件（歸屬目標公司，可代管）
GET	/api/dsce/events	事件列表，支援 ?company_serial=
GET	/api/dsce/events/{id}	取得單一事件

8. 錯誤代碼

HTTP	code	常見情境
400	BadRequest	參數缺漏或格式錯誤
401	TokenExpired	Token 無效或過期
402	PaymentRequired	帳號未啟用（isEnabled=0）
403	AccessDenied	未開通 isApiDsceEnabled、或代管關係非 Auth_Status=1、或超出可存取範圍
404	NotFound	資料不存在或非可存取範圍（不洩漏存在與否）
409	Conflict	建立公司時該公司已存在
500	InternalError	伺服器內部錯誤

錯誤回應格式：{ "code": "...", "message": "..." }

---

© 數位減碳雲資料交換平台（DSCE）· 本文件為 DSCE API 技術說明，UI 操作請見「使用者指南」。