數位信任減碳雲資料交換相關API說明

修訂紀錄

年月日	版本	修改原因
2023/10/25	1.0	初稿
2023/11/13	1.1	Tproof 內容調整
2023/11/15	1.1	Tproof 內容調整
2023/12/07	1.2	身份驗證內容調整
2023/12/11	1.3	新增 Event API
2024/01/02	1.4	新增用量查詢 API
2024/01/18	1.5	新增使用次數查詢 API
2024/04/18	2.0	大幅度改版，新增公司資訊以權限設定相關 API
2024/05/16	2.1	查詢公司清單 API 調整

文件說明

這份文件在 1.x 之前的版本是為了 PACT 規定的 API 而建置，在 2.x 之後會新增公司資訊以及使用碳排資訊的權限設定 API服務。

常用規格

若無特別標示，HTTP method 預設為 POST
Json 欄位名稱表示法，參考 JSONPath expressions
PCF 詳細資料規格，參考 PCF Data Exchange

平台API服務類型

平台提供兩類API服務

認證流程API端點
一般服務功能API端點

API服務類別	端點主機路徑	端點位置前綴詞 {preNodePath}
認證流程API端點	{authUrl}	{authUrl}/api
一般服務功能API端點	{baseUrl}	{baseUrl}

{authUrl} 為 https://api.dsce.com.tw/app
{baseUrl} 為 https://api.dsce.com.tw/app

身分驗證與請求流程

以下是數據串接者呼叫API的流程說明：

首先，透過認證流程取得存取權杖（access token）。
在呼叫API時，請將獲得的存取權杖設置為Bearer token，以取得API的回應結果。
如果存取權杖過期，必須重新經過驗證流程以取得新的存取權杖。

認證流程API端點列表

功能	端點位置
新建一組 clientid, clientsecret	{preNodePath}/auth/clientId
重建一組 clientid, clientsecret	{preNodePath}/auth/clientId/{clientId}
取得 token	{preNodePath}/auth/token
token合法性驗證	{preNodePath}/auth/VerifyJWToken

新建一組 clientid, clientsecret

描述

此API可取得一組 clientid & clientsecret
HTTP 請求

POST {preNodePath}/auth/clientId
路徑參數

參數名稱描述

無
請求格式

無
請求欄位

欄位名稱描述

無

參數名稱	描述
無

欄位名稱	描述
無

回傳格式

{
  "msg": "",
  "client_id": "seq240418-102756",
  "client_secret": "h6bP6r9JQzmim9tgWJ7UkCIAaKeB2J9R"
}

回傳欄位

欄位名稱描述

$.msg 回傳訊息

$.client_id client id

$.client_secret client secret
回傳狀態碼

狀態碼錯誤代碼 (code) 描述

200 OK OK

400 BadRequest Bad Request.

403 AccessDenied Access denied.

500 InternalError An internal or unexpected error has occurred.

欄位名稱	描述
$.msg	回傳訊息
$.client_id	client id
$.client_secret	client secret

重建一組 clientid, clientsecret

描述

此API可取得一組 clientid & clientsecret 公司資料中舊的 client_id
HTTP 請求

PATCH {preNodePath}/auth/clientId/{clientId}
- 路徑參數
參數名稱描述

clientId 公司的 clientId

＊這個 clientId 必須是存在於公司資料中的 clientId。
請求格式

無
請求欄位

欄位名稱描述

無

參數名稱	描述
clientId	公司的 clientId

欄位名稱	描述
無

回傳格式

{
  "msg": "",
  "client_id": "seq240418-102756",
  "client_secret": "h6bP6r9JQzmim9tgWJ7UkCIAaKeB2J9R"
}

回傳欄位

欄位名稱描述

$.msg 回傳訊息

$.client_id client id

$.client_secret client secret

欄位名稱	描述
$.msg	回傳訊息
$.client_id	client id
$.client_secret	client secret

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
403	AccessDenied	Access denied.
404	NoSuchCompany	The specified company data does not exist.
500	InternalError	An internal or unexpected error has occurred.

取得 token

描述

此API可取得access token
HTTP 請求

POST {preNodePath}/auth/token
路徑參數

參數名稱描述

無
請求格式
```
x-www-form-urlencoded
```
請求欄位

欄位名稱描述

client_id 公司識別碼

client_secret 公司密鑰

grant_type 這個字串必須是 client_credentials

＊取用API資源需以公司為單位申請通行金鑰，其中包含公司識別碼和公司密鑰兩個部份。

參數名稱	描述
無

欄位名稱	描述
client_id	公司識別碼
client_secret	公司密鑰
grant_type	這個字串必須是 client_credentials

回傳格式

{
    "access_token": "ttttt",
    "expires_in": 1800,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "email profile"
}

回傳欄位

欄位名稱	描述
$.access_token	存取權杖
$.expires_in	過期時間（秒）
$.refreshexpiresin	更新權杖過期時間（秒），0表示不採用更新權杖機制
$.token_type	權杖類型
$.not-before-policy	啟用前策略時間（秒）
$.scope	權限範圍

回傳狀態碼

狀態碼錯誤代碼 (code) 描述

200 OK OK

400 BadRequest Bad Request.

403 AccessDenied Access denied.

500 InternalError An internal or unexpected error has occurred.

token 合法性驗證

描述

此API可驗證持有的 token 的合法性以及使用權限
HTTP 請求

POST {preNodePath}/auth/VerifyJWToken
- 路徑參數
參數名稱描述

無
請求格式

無
請求欄位

欄位名稱描述

無

參數名稱	描述
無

欄位名稱	描述
無

回傳格式

{
    "vaild": true,
    "client_id": "esgdevops01",
    "clientHost": "127.0.0.1",
    "role": {
    "roles": [
              "offline_access",
              "uma_authorization",
              "default-roles-demo"
        ]
    }
}

回傳欄位

欄位名稱描述

$.vaild 合法權限
回傳狀態碼

狀態碼錯誤代碼 (code) 描述

200 OK OK

400 BadRequest Bad Request.

403 AccessDenied Access denied.

500 InternalError An internal or unexpected error has occurred.

欄位名稱	描述
$.vaild	合法權限

一般服務功能API端點列表

功能	端點位置
新增公司資料	{baseUrl}/api/companies
修改公司資料	{baseUrl}/api/companies/{clientId}
查詢公司資料	{baseUrl}/api/companies/{clientId}
查詢公司清單	{baseUrl}/api/companies
新增產品碳足跡	{baseUrl}/api/2/footprints
修改產品碳足跡	{baseUrl}/api/2/footprints/{pfpId}
查詢產品碳足跡清單	{baseUrl}/api/2/footprints
查詢單一產品碳足跡	{baseUrl}/api/2/footprints/{pfpId}
產品碳足跡數交換事件	{baseUrl}/api/2/events
產品碳足跡使用記錄	{baseUrl}/api/accessevents
產品碳足跡使用用量	{baseUrl}/api/sumaccessevents
產品碳足跡使用次數	{baseUrl}/api/countaccessevents
產品碳足跡驗證	{baseUrl}/api/TproofVerify
新增產品碳足跡使用權限	{baseUrl}/api/pcfdatarights/{pfpId}
刪除產品碳足跡使用權限	{baseUrl}/api/pcfdatarights/{pfpId}
修改產品碳足跡使用權限	{baseUrl}/api/pcfdatarights/{pfpId}
查詢產品碳足跡使用權限	{baseUrl}/api/pcfdatarights/{pfpId}

新增公司資料

描述

新增公司資料（取得一組 clientid & clientsecret）。

＊配合 UI 流程調整使用者填寫公司資料後會一併取得 client_id & client_secret。
HTTP 請求

POST {baseUrl}/api/companies
路徑參數

參數名稱描述

無

參數名稱	描述
無

請求格式

{
    "companyName": "testCompanyName",
    "taxIDNumber": "00000000",
    "contactName": "testContactName",
    "contactEmail": "test@gmail.com",
    "agreeVer": true,
}

請求欄位

欄位名稱描述

無

欄位名稱	描述
無

回傳格式

{
    "companyName": "testCompanyName",
    "taxIDNumber": "00000000",
    "contactName": "testContactName",
    "contactEmail": "test@gmail.com",
    "companyId": "urn:uuid:067C346A-0202-4249-6EBA-F9A17A5512F6",
    "client_id": "seq240418-100023",
    "client_secret": "ArxlWyoS5r4ajaPpIFe0aizCRr7TiHJl"
}

回傳欄位

欄位名稱	描述
$.companyName	公司的名稱
$.taxIDNumber	公司的統一編號
$.contactName	公司的聯絡人姓名
$.contactEmail	公司的聯絡人 email
$.companyId	公司的 id
$.client_id	公司的 client_id
$.client_secret	公司的 client_secret

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
500	InternalError	An internal or unexpected error has occurred.

修改公司資料

描述修改公司資料

＊僅提供修改聯絡人資訊。
HTTP 請求

PATCH {baseUrl}/api/companies/{clientId}
路徑參數

參數名稱描述

clientId 公司的 client_id

參數名稱	描述
clientId	公司的 client_id

請求格式

{
    "contactName": "testContactName",
    "contactEmail": "test@gmail.com",
}

請求欄位

欄位名稱描述

無

欄位名稱	描述
無

回傳格式

{
    "contactName": "testContactName",
    "contactEmail": "test@gmail.com",
    "companyName": "testCompanyName",
    "taxIDNumber": "00000000",
    "companyId": "urn:uuid:067C346A-0202-4249-6EBA-F9A17A5512F6",
    "client_id": "seq240418-100023",
}

回傳欄位

欄位名稱	描述
$.companyName	公司的名稱
$.taxIDNumber	公司的統一編號
$.contactName	公司的聯絡人姓名
$.contactEmail	公司的聯絡人 email
$.companyId	公司的 id
$.client_id	公司的 client_id

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
500	InternalError	An internal or unexpected error has occurred.

查詢公司資料

描述查詢特定公司資料
HTTP 請求

GET {baseUrl}/api/companies/{clientId}
路徑參數

參數名稱描述

clientId 公司的 client_id
請求格式

無
請求欄位

欄位名稱描述

無

參數名稱	描述
clientId	公司的 client_id

欄位名稱	描述
無

回傳格式

{
    "serial": 46,
    "companyName": "testCompanyName",
    "taxIDNumber": "00000000",
    "contactName": "testContactName",
    "contactEmail": "test@gmail.com",
    "companyId": "urn:uuid:067C346A-0202-4249-6EBA-F9A17A5512F6",
    "client_id": "seq240418-100023",
}

回傳欄位

欄位名稱	描述
$.serial	公司的序號
$.companyName	公司的名稱
$.taxIDNumber	公司的統一編號
$.contactName	公司的聯絡人姓名
$.contactEmail	公司的聯絡人 email
$.companyId	公司的 id
$.client_id	公司的 client_id

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
404	NoSuchCompany	The specified company data does not exist.
500	InternalError	An internal or unexpected error has occurred.

查詢公司清單

描述查詢公司清單
HTTP 請求

GET {baseUrl}/api/companies

＊不提供聯絡人及聯絡資訊
路徑參數

參數名稱描述

無
請求格式 無
請求欄位

欄位名稱描述

無

參數名稱	描述
無

欄位名稱	描述
無

回傳格式

[
    {
    "serial": 46,
    "companyName": "testCompanyName",
    "taxIDNumber": "00000000",
    "companyId": "urn:uuid:067C346A-0202-4249-6EBA-F9A17A5512F6",
    "client_id": "seq240418-100023",
    }
]

回傳欄位

欄位名稱描述

公司資料的 array

欄位名稱	描述
	公司資料的 array

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
500	InternalError	An internal or unexpected error has occurred.

新增產品碳足跡

描述

新增產品碳足跡

＊ companyIds 㯗位會自動補上新增資料的所屬 companyId
HTTP 請求

POST {baseUrl}/api/2/footprints
路徑參數

參數名稱描述

無

參數名稱	描述
無

請求格式

{
    "id": "",
    "specVersion": "2.0.0",
    "version": 1,
    "created": "",
    "status": "Active",
    "companyName": "My Corp",
    "companyIds": [
        "urn:uuid:00000001-42A2-4267-A402-0ECFEFAD1619",
        "urn:uuid:00000002-42A2-4267-A402-0ECFEFAD1619",
        "urn:epc:id:sgln:4063973.00000.8"
    ],
    "productDescription": "Cote'd Or Ethanol",
    "productIds": [
        "urn:gtin:1300000000000",
        "urn:gtin:1400000000000"
    ],
    "productCategoryCpc": "123",
    "productNameCompany": "Green Ethanol",
    "comment": "xxx",
    "pcf": {
        "declaredUnit": "liter",
        "unitaryProductAmount": "12.0",
        "pCfExcludingBiogenic": "0.0",
        "fossilGhgEmissions": "0.123",
        "fossilCarbonContent": "0.0",
        "biogenicCarbonContent": "0.0",
        "landManagementGhgEmissions": "0.01",
        "characterizationFactors": "AR5",
        "crossSectoralStandardsUsed": [
            "GHG Protocol Product standard"
        ],
        "productOrSectorSpecificRules": [
            {
                "operator": "EPD International",
                "ruleNames": [
                "ABC 2021"
                ]
            }
        ],
        "boundaryProcessesDescription": "End-of-life included",
        "referencePeriodStart": "2022-01-01T00:00:00Z",
        "referencePeriodEnd": "2023-01-01T00:00:00Z",
        "geographyCountry": "AC",
        "secondaryEmissionFactorSources": [
            {
                "name": "Ecoinvent",
                "version": "1.2.3"
            }
        ],
        "exemptedEmissionsPercent": 3.1,
        "exemptedEmissionsDescription": "xxx",
        "packagingEmissionsIncluded": false,
        "primaryDataShare": 56.12,
        "assurance": {
            "coverage": "product line",
            "level": "reasonable",
            "boundary": "Cradle-to-Gate",
            "providerName": "My Auditor",
            "completedAt": "2022-12-08T14:47:32Z",
            "standardName": "ISO ...",
            "comments": "This is a comment"
        }
    },
    "extensions": [
        {
            "specVersion": "2.0.0",
            "dataSchema": "https://catalog.carbon-transparency.com/shipment/1.0.0/data-model.json",
            "data": {
                "shipmentId": "S1234567890",
                "consignmentId": "Cabc.def-ghi",
                "shipmentType": "PICKUP",
                "weight": 10,
                "transportChainElementId": "ABCDEFGHI"
            }
        }
    ]
}

請求欄位

完整欄位

＊M: 必填欄位；O: 選填欄位

欄位名稱	必填	描述
$.id	M	pfId 產品足跡識別碼 (uuid格式) ＃新增時由系統自動填入。
$.specVersion	M	對應 PCF Data Exchange 文件版號。＃目前僅支援 "2.0.0"。
$.precedingPfIds	O	前一個版本的 pfId ＃新增時由系統自動填入。
$.version	M	產品足跡版本＃資料型態: Integer。
$.created	M	資料製造日期＃新增時由系統自動填入。
$.updated	O	資料更新日期＃修改時由系統自動填入。
$.status	M	使用狀態＃由系統自動填入代碼。
$.statusComment	O	使用狀態說明
$.validityPeriodStart	O	資料有限期限開始時間
$.validityPeriodEnd	O	資料有限期限結束時間
$.companyName	M	公司名稱
$.companyIds	M	公司 Id ＃資料型態: Array。
$.productDescription	M	產品敘述
$.productIds	M	產品 Id ＃資料型態: Array。
$.productCategoryCpc	M	聯合國產品分類代碼 (CPC)
$.productNameCompany	M	商品名稱
$.comment	M	批注
$.pcf	M	產品碳足跡資料＃參閱 pcf 欄位解說。＃資料型態: JSON。
$.extensions	O	擴充資料＃資料型態: JSON。

pfp裡面 pcf 的內容

＊M: 必填欄位；O: 選填欄位

欄位名稱	必填	描述
$.declaredUnit	M	產品分析單位
$.unitaryProductAmount	M	產品包含的份量
$.pCfExcludingBiogenic	M	產品碳足跡 (不包含生物排放)
$.pCfIncludingBiogenic	O*	產品碳足跡 (包含生物排放)
$.fossilGhgEmissions	M	化石源燃燒所產生的碳排
$.fossilCarbonContent	M	產品包含的化石源碳含量
$.biogenicCarbonContent	M	產品包含的生物碳含量
$.dLucGhgEmissions	O*	土地轉化產生的碳排
$.landManagementGhgEmissions	O*	土地管理變化產生的碳排
$.otherBiogenicGhgEmissions	O*	與產品製造和運輸相關不包含土地轉化 (dLuc, iLud) 的碳排
$.iLucGhgEmissions	O	產品造成的土地轉化產生的碳排（非公司土地）
$.biogenicCarbonWithdrawal	O*	產品過程生物成因產生的碳排
$.aircraftGhgEmissions	O	使用飛機運輸造成的碳排
$.characterizationFactors	M	計算 PCF 的 GWP 特徵因子的 IPCC (AR5, AR6)
$.crossSectoralStandardsUsed	M	計算溫室氣體排放量的跨部份標準＃資料型態: Array。
$.productOrSectorSpecificRules	O	用於計算或分配溫室氣體排放的特定規則＃資料型態: Array。
$.biogenicAccountingMethodology	O*	遵循的標準必須是以下之一 (PEF, ISO 14067, GHGP)
$.boundaryProcessesDescription	M	每個週期的過程敘述
$.referencePeriodStart	M	週期時間開始
$.referencePeriodEnd	M	週期時間結束
$.geographyCountrySubdivision		國家, 城市; ISO 3166-2
$.geographyCountry		國家, ISO3166-2
$.geographyRegionOrSubregion		區域 (ASIA)
$.secondaryEmissionFactorSources	O	使用輔助數據計算（使用輔助計算必須提供參考數據）。＃資料型態: Array。
$.exemptedEmissionsPercent	M	從 PCF 排除的排放比例，數字介於(0~5)%之間
$.exemptedEmissionsDescription	M	排除 PCF 的理由
$.packagingEmissionsIncluded	M	包裝碳排是否包含在 PCF 中
$.packagingGhgEmissions	O	包裝產生的碳排
$.allocationRulesDescription	O	對應規則描述
$.uncertaintyAssessmentDescription	O	不確定因素的評估敘述
$.primaryDataShare	O*	主要數據的百分比＃資料型態: Number。
$.dqi	O*	存在primaryDataShare不用填 dpi ＃資料型態: JSON。
$.assurance	O	數據保證單位＃資料型態: JSON。

回傳格式

{
    "id" :  "d9be4477-e351-45b3-acd9-e1da05e6f633"
}

回傳欄位

欄位名稱描述

$.id 新增的產品碳足跡 id

欄位名稱	描述
$.id	新增的產品碳足跡 id

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
500	InternalError	An internal or unexpected error has occurred.

修改產品碳足跡

描述

修改產品碳足跡

＊當 pfpId 為 "Deprecated" 狀態時無法進行更動。

＊帳號所屬 companyId 不存在於該筆資料中不得修改資料。
HTTP 請求

PATCH {baseUrl}/api/2/footprints/{pfpId}
路徑參數

參數名稱描述

pfpId 要修改的碳足跡 id
請求格式

請參閱新增產品碳足跡 - 請求格式
請求欄位

請參閱新增產品碳足跡 - 請求欄位

參數名稱	描述
pfpId	要修改的碳足跡 id

回傳格式

{
    "id" :  "d9be4477-e351-45b3-acd9-e1da05e6f633"
}

回傳欄位

欄位名稱描述

$.id 新增的產品碳足跡 id

欄位名稱	描述
$.id	新增的產品碳足跡 id

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
404	NoSuchFootprint	The specified footprint does not exist.
500	InternalError	An internal or unexpected error has occurred.

查詢產品碳足跡清單

描述

查詢產品碳足跡清單
HTTP 請求

GET {baseUrl}/api/2/footprints?$filter={$filter}&limit={limit}
- $filter 使用說明：
  - 搜尋可以使用 created, updated, productCategoryCpc, geographyCountry, referencePeriodStart, referencePeriodEnd 這些屬性。
  - 搜尋條件可以使用 eq, lt, le, gt, ge。
  - 搜尋可以使用 companyIds, productIds 物件搜尋僅適用 eq。
  - 使用範例：
    - 搜尋聯合國產品分類代碼 (CPC)：
      
      $filter=productCategoryCpc eq '3342'
    - 搜尋國家：
      
      $filter=pcf/geographyCountry eq 'DE'
    - 搜尋週期時間區間：
      
      $filter=(pcf/referencePeriodStart ge '2023-01-01T00:00:00.000Z') and (pcf/referencePeriodEnd lt '2024-01-01T00:00:00.000Z')
    - 搜尋產品 Id：
      
      $filter=productIds/any(productId:(productId eq 'urn:...'))
- limit 使用說明：限制搜尋的筆數。
路徑參數

參數名稱描述

$filter 搜尋字串

limit 每次回應的資料量
請求格式

無
請求欄位

欄位名稱描述

無

參數名稱	描述
$filter	搜尋字串
limit	每次回應的資料量

欄位名稱	描述
無

回傳格式

{
    data:
    [
        {
            "id": "d9be4477-e351-45b3-acd9-e1da05e6f633",
            "specVersion": "2.0.0",
            "version": 1,
            "created": "",
            "status": "Active",
            "companyName": "My Corp",
            "companyIds": [
                "urn:uuid:00000001-42A2-4267-A402-0ECFEFAD1619",
                "urn:uuid:00000002-42A2-4267-A402-0ECFEFAD1619",
                "urn:epc:id:sgln:4063973.00000.8"
            ],
            "productDescription": "Cote'd Or Ethanol",
            "productIds": [
                "urn:gtin:1300000000000",
                "urn:gtin:1400000000000"
            ],
            "productCategoryCpc": "123",
            "productNameCompany": "Green Ethanol",
            "comment": "xxx",
            "pcf": {
                "declaredUnit": "liter",
                "unitaryProductAmount": "12.0",
                "pCfExcludingBiogenic": "0.0",
                "fossilGhgEmissions": "0.123",
                "fossilCarbonContent": "0.0",
                "biogenicCarbonContent": "0.0",
                "landManagementGhgEmissions": "0.01",
                "characterizationFactors": "AR5",
                "crossSectoralStandardsUsed": [
                    "GHG Protocol Product standard"
                ],
                "productOrSectorSpecificRules": [
                    {
                        "operator": "EPD International",
                        "ruleNames": [
                        "ABC 2021"
                        ]
                    }
                ],
                "boundaryProcessesDescription": "End-of-life included",
                "referencePeriodStart": "2022-01-01T00:00:00Z",
                "referencePeriodEnd": "2023-01-01T00:00:00Z",
                "geographyCountry": "AC",
                "secondaryEmissionFactorSources": [
                    {
                        "name": "Ecoinvent",
                        "version": "1.2.3"
                    }
                ],
                "exemptedEmissionsPercent": 3.1,
                "exemptedEmissionsDescription": "xxx",
                "packagingEmissionsIncluded": false,
                "primaryDataShare": 56.12,
                "assurance": {
                    "coverage": "product line",
                    "level": "reasonable",
                    "boundary": "Cradle-to-Gate",
                    "providerName": "My Auditor",
                    "completedAt": "2022-12-08T14:47:32Z",
                    "standardName": "ISO ...",
                    "comments": "This is a comment"
                }
            },
            "extensions": [
                {
                    "specVersion": "2.0.0",
                    "dataSchema": "https://catalog.carbon-transparency.com/shipment/1.0.0/data-model.json",
                    "data": {
                        "shipmentId": "S1234567890",
                        "consignmentId": "Cabc.def-ghi",
                        "shipmentType": "PICKUP",
                        "weight": 10,
                        "transportChainElementId": "ABCDEFGHI"
                    }
                }
            ]
        }
    ]
}

回傳欄位

欄位名稱描述

$.data 產品足跡的的 array

＊array 內容同新增、修改填入的 pfp 資料格式。

欄位名稱	描述
$.data	產品足跡的的 array

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
202	Accepted	Accepted
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
500	InternalError	An internal or unexpected error has occurred.

查詢單一產品碳足跡

描述:

查詢單一產品碳足跡
HTTP 請求

GET {baseUrl}/api/2/footprints/{pfpId}
路徑參數

參數名稱描述

pfpId 要查詢的碳足跡 id
請求格式

無
請求欄位

參數名稱描述

無
回傳格式

請參閱新增產品碳足跡 - 請求格式
回傳欄位

請參閱新增產品碳足跡 - 請求欄位

參數名稱	描述
pfpId	要查詢的碳足跡 id

參數名稱	描述
無

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
404	NoSuchFootprint	The specified footprint does not exist.
500	InternalError	An internal or unexpected error has occurred.

碳足跡數交換事件

描述:
1. 讓數據擁有者通知數據接收者產品足跡更新的訊息。
2. 讓數據接收者可以透過取得數據擁有者更新後的產品足跡。
HTTP 請求

POST {baseUrl}/api/2/events
路徑參數

無
請求格式

無
請求欄位

參數名稱描述

無
回傳格式

無
回傳欄位

無

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
400	NotImplemented	The specified Action or header you provided implies
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
500	InternalError	An internal or unexpected error has occurred.

產品碳足跡使用記錄

描述:

查詢公司的產品碳足跡使用記錄
HTTP 請求

GET {baseUrl}/api/2/accessevents?from={from}&to={to}
路徑參數

參數名稱描述

from 起始日期 (2023-09-19)

to 結束日期 (2023-09-19)
請求格式

無
請求欄位

欄位名稱描述

無

回傳格式

{
    data:
    [
        {
            "serial": 30,
            "companySn": 9,
            "rw": "READ",
            "size": 1633,
            "filter": "4FF1707D-AE9F-3FB7-3522-DC68B2B5AE96",
            "created": "2023-09-13 08:44:25"
        }
    ]
}

回傳欄位

欄位名稱描述

$.serial 序號

$.companySn 公司流水號

$.rw 使用方法 (INSERT/UPDATE/READ)

$.size 用量

$.filter 關鍵字句

$.created 使用時間

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
500	InternalError	An internal or unexpected error has occurred.

產品碳足跡使用用量

描述:

查詢公司的產品碳足跡使用用量，單位 bytes。
HTTP 請求

GET {baseUrl}/api/2/sumaccessevents?from={from}&to={to}
路徑參數

參數名稱描述

from 起始日期 (2023-09-19)

to 結束日期 (2023-09-19)
請求格式

無
請求欄位

欄位名稱描述

無
回傳格式
```
{
    data: xxx
}
```
回傳欄位

欄位名稱描述

$.data 區間用量

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
500	InternalError	An internal or unexpected error has occurred.

產品碳足跡使用次數

描述:

查詢公司的產品碳足跡使用次數，單位: 次數。
HTTP 請求

GET {baseUrl}/api/2/countaccessevents?from={from}&to={to}
路徑參數

參數名稱描述

from 起始日期 (2023-09-19)

to 結束日期 (2023-09-19)
請求格式

無
請求欄位

欄位名稱描述

無
回傳格式
```
{
    data: xxx
}
```
回傳欄位

欄位名稱描述

$.data 使用次數

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
500	InternalError	An internal or unexpected error has occurred.

產品碳足跡驗證

描述:

驗證使用者上傳碳足跡資料和線上資料是否一致。
HTTP 請求

POST {baseUrl}/api/2/TproofVerify/{pfpId}
路徑參數

參數名稱描述

pfpId 要修改的碳足跡 id
請求格式

請參閱新增產品碳足跡 - 請求格式
請求欄位

請參閱新增產品碳足跡 - 請求欄位
回傳欄位

欄位名稱描述

無

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
500	InternalError	An internal or unexpected error has occurred.

新增產品碳足跡使用權限

描述

新增產品碳足跡使用權限（設定碳足跡和公司的兩者間的使用權限）。
HTTP 請求

POST {baseUrl}/api/pcfdatarights/{pfpId}
路徑參數

參數名稱描述

pfpId 產品碳足跡的 id

請求格式

{
  "clientId": "seq240109-101705",
  "centerSn": "13,17"
}

請求欄位

欄位名稱描述

clientId 上傳此筆產品碳足跡公司的clientId

centerSn 可讀取此資料的公司 serial, 不限一個。
回傳格式

無
回傳欄位

無

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
500	InternalError	An internal or unexpected error has occurred.

刪除產品碳足跡使用權限

描述

刪除產品碳足跡使用權限（設定碳足跡和公司的兩者間的使用權限）。
HTTP 請求

DELETE {baseUrl}/api/pcfdatarights/{pfpId}
路徑參數

參數名稱描述

pfpId 產品碳足跡的 id
請求格式
```
{
  "clientId": "seq240109-101705",
}
```
請求欄位

欄位名稱描述

clientId 上傳此筆產品碳足跡公司的clientId
回傳格式

無
回傳欄位

無

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
500	InternalError	An internal or unexpected error has occurred.

修改產品碳足跡使用權限

描述

修改產品碳足跡使用權限（設定碳足跡和公司的兩者間的使用權限）。
HTTP 請求

PATCH {baseUrl}/api/pcfdatarights/{pfpId}
路徑參數

參數名稱描述

pfpId 產品碳足跡的 id
請求格式

無
請求欄位

無

回傳格式

{
    "clientId": "seq240109-101705",
    "centerSn": "13,17"
}

回傳欄位

無

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
500	InternalError	An internal or unexpected error has occurred.

查詢產品碳足跡使用權限

描述

查詢產品碳足跡使用權限（設定碳足跡和公司的兩者間的使用權限）。
HTTP 請求

GET {baseUrl}/api/pcfdatarights/{pfpId}
路徑參數

參數名稱描述

pfpId 產品碳足跡的 id
請求格式

無
請求欄位

無

回傳格式

{
    "supplySn": 20,
    "centerSn": "13,17"
}

回傳欄位

欄位名稱描述

supplySn 提供此筆碳足跡資料公司的 serial

centerSn 此筆碳足跡資料授權給這些公司的 serial

回傳狀態碼

狀態碼	錯誤代碼 (code)	描述
200	OK	OK
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
500	InternalError	An internal or unexpected error has occurred.

錯誤回應訊息

回應號碼	錯誤代碼 (code)	錯誤訊息 (message)
200	OK	OK
202	Accepted	Accepted
400	BadRequest	Bad Request.
401	TokenExpired	The specified access token has expired.
403	AccessDenied	Access denied.
404	NoSuchFootprint	The specified footprint does not exist.
500	InternalError	An internal or unexpected error has occurred.

欄位名稱	描述
$.serial	序號
$.companySn	公司流水號
$.rw	使用方法 (INSERT/UPDATE/READ)
$.size	用量
$.filter	關鍵字句
$.created	使用時間

欄位名稱	描述
clientId	上傳此筆產品碳足跡公司的clientId
centerSn	可讀取此資料的公司 serial, 不限一個。

欄位名稱	描述
supplySn	提供此筆碳足跡資料公司的 serial
centerSn	此筆碳足跡資料授權給這些公司的 serial

數位信任減碳雲資料交換 相關API說明

修訂紀錄

文件說明

常用規格

平台API服務類型

平台提供兩類API服務

身分驗證與請求流程

認證流程API端點列表

新建一組 clientid, clientsecret

重建一組 clientid, clientsecret

取得 token

token 合法性驗證

一般服務功能API端點列表

新增公司資料

修改公司資料

查詢公司資料

查詢公司清單

新增產品碳足跡

修改產品碳足跡

查詢產品碳足跡清單

查詢單一產品碳足跡

碳足跡數交換事件

產品碳足跡使用記錄

產品碳足跡使用用量

產品碳足跡使用次數

產品碳足跡驗證

新增產品碳足跡使用權限

刪除產品碳足跡使用權限

修改產品碳足跡使用權限

查詢產品碳足跡使用權限

錯誤回應訊息

數位信任減碳雲資料交換相關API說明