PACT v3 API 使用指南

數位減碳雲資料交換平台（DSCE） · PACT Technical Specifications v3.0.3 · 支援 CBAM Extension · 適用對象：合作廠商的系統整合開發人員

English version: DSCE PACT v3 API Technical Specification（PDF）

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

本 API 依循 WBCSD PACT Technical Specifications for PCF Data Exchange (v3.0.3)，所有端點以 /api/3/ 為前綴；認證相關端點（/api/auth/*）與 DSCE API 共用。

1. 存取前提

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

• 持有有效 Bearer Token（見「1-2. 取得 Bearer Token」）。
• 帳號已由管理者開啟 APIv3 使用權限（isApiV3Enabled = 1）。未開啟一律回 403。
• 帳號為啟用狀態。停用中的帳號回 402。

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

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

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

成功回應 (200)

{
  "client_id": "seq260921-121701",
  "client_secret": "Xy9kLmNoPqRsTuVwXy12"
}

⚠️ client_secret 僅顯示一次，請立即妥善保存。取得憑證不代表已可使用 v3 API，仍須完成 1-3 開通。

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

以 HTTP Basic Authentication 帶入憑證換取 Bearer Token，Token 有效期限 30 分鐘（1800 秒），到期請重新取得。

POST/api/auth/token

請求標頭

請求本體

curl 範例

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

成功回應 (200)

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

後續所有 v3 API 請在 Authorization 標頭帶入：Bearer <access_token>（Bearer 不分大小寫）。

1-3. APIv3 使用權限開通流程

本權限僅能由平台管理者開啟，使用者、資訊商皆無法自行開通。

1. 使用者向平台申請 PACT v3 API 使用權（或由所屬資訊商代為提出），說明整合用途與對接的合作方。
2. 管理者於後台「會員管理」開啟該會員明細，將「APIv3 使用？」切換為「使用」（isApiV3Enabled = 1）。
3. 開通後即可存取 /api/3/*，已取得的 Token 不需重新申請。
4. 管理者可隨時切回「不使用」，停用後立即回 403。

未開通時的回應：

HTTP/1.1 403 Forbidden
{ "code": "AccessDenied", "message": "PACT v3 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": "seq260921-121701",
  "clientHost": "1.2.3.4",
  "role": { "roles": ["offline_access", "uma_authorization", "default-roles-demo"] }
}

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

重新產生 client_secret，舊的密鑰立即失效。APIv3 使用權限不受影響。

PATCH/api/auth/credentials/{clientId}（標頭 Authorization: Bearer <access_token>）

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

2. 資料歸屬與存取範圍

companyIds 規則

• 未帶 companyName / companyIds 時，系統自動填入呼叫端公司的名稱與 companyId（建議作法）。
• 帶 companyIds 時必須為 JSON array；系統會確保自己的 companyId 在第一個（沒有就補上）。
• 可另外加入自己的其他識別碼（例如 DUNS、工廠／設施 URN），但不可包含其他已註冊公司的 companyId，否則回 400。

3. 碳足跡 Footprints

POST/api/3/footprints

• id（pfpId）由系統產生（RFC 4122 v4 UUID，小寫），請以回應中的 id 為準。
• 數值欄位一律為 字串型別的十進位數（string<decimal>，例如 "2.0"），不可使用 JSON number 或科學記號；系統依原值儲存，不做四捨五入。
• specVersion 須為 3.x。

curl -X POST https://<host>/api/3/footprints \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d @footprint.json

成功回應 (200)

{ "id": "bc30e6e5-d7c3-4ad8-91f6-5d8be04f9627" }

GET/api/3/footprints

回應格式為 { "data": [ ProductFootprint, ... ] }，分頁連結放在 Link 回應標頭（rel="first"、"prev"、"next"、"last"）。

4. 資料模型擴充 Extensions（含 CBAM）

依 PACT v3.0.3 §4.6.1，extensions 為 array，每個成員為一個 DataModelExtension object。系統分兩層驗證，任一層不通過即回 400 且不寫入：

第一層：PACT 信封規則（所有擴充、所有帳號）

第二層：CBAM Extension 規則

當 dataSchema 為 https://cbam.corporate-harmony.org/schemas/pact-extension.json 時，依 Product Footprint Extension for CBAM（specVersion 0.9.0）驗證。其他 dataSchema 只做第一層驗證並原樣保存。

CBAM 規格另要求 companyIds 代表前驅物的製造設施、productIds 可被交貨對象辨識。建議在自己的 companyId 之外加上設施識別碼，並使用雙方共通的產品識別碼（例如 GTIN）。

範例（僅列 extensions）

"extensions": [
  {
    "specVersion": "0.9.0",
    "dataSchema": "https://cbam.corporate-harmony.org/schemas/pact-extension.json",
    "data": {
      "directEmissions": {
        "determinationType": "01",
        "applicableReportingTypeMethodology": "TOM01",
        "specificEmbeddedEmissions": "1.5",
        "measurementUnit": "EMU1"
      },
      "indirectEmissions": {
        "determinationType": "01",
        "specificEmbeddedEmissions": "0.5",
        "measurementUnit": "EMU1",
        "electricitySource": "SOE01"
      }
    }
  }
]

上例搭配 pcfExcludingBiogenicUptake = "2.0"、productMassPerDeclaredUnit = "1.0"：1.5 + 0.5 = 2.0 ÷ 1.0，加總一致。

5. 事件 Events

支援的事件類型與接收方

RequestCreatedEvent 範例

curl -X POST https://<host>/api/3/events \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/cloudevents+json" \
  -d '{
    "type": "org.wbcsd.pact.ProductFootprint.RequestCreatedEvent.3",
    "specversion": "1.0",
    "id": "71f32fda-5ab6-4855-a88f-c085f31a523b",
    "source": "https://<your-host>/api",
    "time": "2026-09-30T06:31:44Z",
    "data": { "productId": ["urn:gtin:4712345060507"], "companyId": ["urn:company:III-DTRI:00000257"] }
  }'

事件驗證通過即回 200，請求於後續非同步處理；列表與單筆回應只包含 type、specversion、id、source、time、data。

⚠️ 系統會依 source 回呼 RequestFulfilledEvent / RequestRejectedEvent。回呼主機須事先由平台管理者登錄於允許清單，未登錄的主機不會收到回呼（事件本身仍會被接受）。

6. P2P 碳足跡傳遞

7. 錯誤代碼

錯誤回應一律為 PACT Error 物件：{ "code": "...", "message": "..." }（/api/* 不會回傳 HTML 錯誤頁）。

© 數位減碳雲資料交換平台（DSCE）· 本文件為 PACT v3 API 技術說明；權限受控的整合 API 請見「DSCE API 使用指南」，UI 操作請見「使用者指南」。