殼牌 B2B 移動支付卡管理 API - 快速入門指南

API 版本： 3.1.5 | 驗證： OAuth 2.0 | 狀態： 生產環境

概述

Shell 卡片管理 API 是一項基於 REST 的 API，可讓開發人員透過程式化方式管理 Shell 加油卡。此 API 支援卡片搜尋、訂購、狀態更新、取消以及其他各種卡片管理操作。

注意： 本指南僅涵蓋採用 OAuth 2.0 驗證的端點（基礎路徑：/card-management/v1）。舊版 Basic Auth 端點（/fleetmanagement/v1/card）因正在逐步淘汰，故未包含在內。

主要功能

透過靈活的篩選條件搜尋及篩選加油卡
訂購新卡並追蹤訂單狀態
封鎖、解除封鎖、及註銷卡片
更新卡片寄送地址
管理卡片自動續期設定
在卡片群組與帳戶間移動卡片
申請 PIN 碼提醒

重要通知 - OAuth 2.0

重要：OAuth 2.0 現已成為標準驗證方式

新增整合功能： 從一開始就使用 OAuth 2.0
現有整合： 規劃您的 OAuth 2.0 遷移計畫
舊版方法： 基本驗證 (Basic Auth) 與 API 金鑰即將逐步淘汰

請聯絡 Shell 技術支援以取得您的 OAuth 2.0 憑證 (client_id 和 client_secret)。

驗證

OAuth 2.0（標準驗證方法）

Shell 卡片管理 API 使用 OAuth 2.0 客戶端憑證流程 進行安全驗證。

警告： 所有客戶應規劃採用 OAuth 2.0 驗證。這是 Shell 卡片管理 API 建議採用且符合未來發展趨勢的認證方法。舊版認證方法正逐步淘汰中。

OAuth 2.0 流程

步驟 1：取得存取憑證

向 OAuth 憑證端點請求存取憑證：

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=您的-客戶-ID&client_secret=您的-客戶-密鑰

步驟 2：在 API 請求中使用存取憑證

Authorization: Bearer <存取憑證>
Content-Type: application/json

存取憑證管理

存取憑證管理最佳實務：

存取憑證的有效期限有限（通常為 15 分鐘）
實作憑證快取機制，以避免不必要的憑證請求
在過期前刷新令牌，以確保服務不中斷
切勿分享您的 client_secret 或將其嵌入客戶端程式碼中

OAuth 2.0 採用策略

為何要遷移至 OAuth 2.0？

安全性優勢：

業界標準的認證協定
有效期有限的存取憑證可降低安全風險
每次請求均不傳輸憑證
更完善地支援存取憑證輪替與撤銷

營運優勢：

提升可擴展性與效能
更完善的監控與稽核能力
簡化的憑證管理
具備前瞻性的整合能力

遷移路徑

若您目前仍在使用舊式驗證方法，請遵循此遷移路徑：

向 Shell 技術支援
在您的應用程式中實作 OAuth 憑證管理
在測試／沙盒環境中進行徹底測試
在過渡期間並行執行 （OAuth + 舊版）
監控並驗證 OAuth 整合
驗證完成後 切換為僅使用 OAuth
遷移成功後停用舊版驗證機制

環境

此 API 提供兩種環境：

環境	基礎 URL	用途
生產環境	https://api.shell.com	正式生產環境
測試（沙盒）	https://api-test.shell.com/test	測試與開發環境

提示： 在移轉至生產環境前，請務必先在 測試環境 中測試您的整合功能。

快速入門

1. 取得您的 OAuth 憑證

聯絡 Shell 技術支援
申請 OAuth 2.0 憑證 (client_id 和 client_secret)
檢視服務條款

2. 取得存取憑證

首先，取得您的 OAuth 存取憑證：

cURL 範例：

curl -X POST https://api-test.shell.com/v2/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=您的-客戶端-ID&client_secret=您的-客戶端-密鑰"

回應：

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 899
}

3. 發出您的第一個 API 請求

範例：搜尋有效卡片

cURL 範例：

curl -X POST https://api-test.shell.com/test/card-management/v1/search \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "Filters": {
 "PayerNumber": "CZ00000927",
        "AccountNumber": "CZ00000927",
 "ColCoCode": 32,
 "CardStatus": [
 "Active"
 ]
 
 },
    "Page": 1,
    "PageSize": 1
}'

回應範例：

{
    "Page": 1,
    "TotalRecords": 7994,
    "TotalPages": 7994,
    "PageSize": 1,
    "Data": [
 {
 "AccountId": 1227,
 "AccountName": "Dominica1_C_1",
            "AccountNumber": "CZ00000927",
 "AccountShortName": "Dominica1_1",
 "BundleId": null,
 "CardBlockSchedules": null,
            "CardGroupId": null,
 "CardGroupName": null,
 "CardId": 491623,
 "CardTypeCode": "7027329",
            "CardTypeId": 11120,
 "CardTypeName": "CZ SFA NAT SIN - CHIP",
 "ColCoCountryCode": "CZ",
            "建立日期": "20220810 23:53:25",
 "駕駛員姓名": "SHELL973169581",
 "生效日期": "20220810",
            "ExpiryDate": "20260831",
 "FleetIdInput": true,
 "IsCRT": false,
 "IsFleet": true,
            "IsInternational": false,
 "IsNational": true,
 "IsPartnerSitesIncluded": false,
 "IsShellSitesOnly": true,
 "IssueDate": "20220812",
            "IsSuperseded": false,
 "IsVirtualCard": false,
 "LastModifiedDate": "20230614 00:05:16",
            "最後使用日期": null,
 "當地貨幣代碼": "CZK",
 "當地貨幣符號": "Kč",
 "里程表輸入": true,
            "PAN": "7027329200001461736",
 "MaskedPAN": "7027329******461736",
            "PANID": 17268839,
 "PurchaseCategoryCode": "2",
 "PurchaseCategoryId": 102,
 "PurchaseCategoryName": "2 - 所有燃料產品、汽車相關商品及 TMF",
            "Reason": "已排定解鎖",
 "ReissueSetting": "True",
 "StatusDescription": "Active",
            "StatusId": 1,
 "TokenTypeID": 503742,
 "TokenTypeName": "CZ SFA NAT SIN – CHIP",
 "VRN": "VRN347886994",
 "ClientReferenceId": null,
 "IsEMVContact": true,
 "IsEMVContactless": false,
 "IsRFID": false,
 "RFIDUID": null,
            "EMAID": null,
 "EVPrintedNumber": null,
 "CardMediaCode": "100999",
 "MediumTypeID": 1,
 "MediumType": "加油卡"
 }
    ],
    "RequestId": "5a474d3e-70f4-4f7d-9416-5d5475b33e4f",
    "Status": "SUCCESS"
}

API 端點參考

卡片搜尋與擷取

端點	方法	描述
/card-management/v1/search	POST	使用彈性篩選條件搜尋卡片（OAuth 2.0）
/card-management/v1/details	POST	取得單張加油卡的詳細資訊（OAuth 2.0）

常見使用情境：

依卡片狀態搜尋（ACTIVE、BLOCKED、EXPIRED、等）
依駕駛人姓名或車輛登記號碼篩選
依 PAN（後 4 位數字）搜尋
尋找將於 X 天內過期的卡片

卡片摘要

端點	方法	說明
/card-management/v1/summary	POST	取得加油卡的高階摘要（OAuth 2.0）

回傳內容：

按狀態劃分的卡片總數
依卡片類型劃分的統計摘要
有效與失效卡片分佈

卡片訂購

端點	方法	說明
/card-management/v1/ordercard	POST	訂購一張或多張加油卡（OAuth 2.0）
/card-management/v1/ordercardenquiry	POST	查詢卡片訂購狀態（OAuth 2.0）

訂購卡片所需資訊：

ColCoCode（收款公司代碼）
付款人編號或付款人識別碼
帳戶號碼
卡片類型與設定
送達地址詳情

卡片狀態管理

端點	方法	說明
/card-management/v1/updatestatus	POST	封鎖、解鎖或取消卡片（OAuth 2.0）
/card-management/v1/schedulecardblock	POST	排程卡片封鎖／解鎖請求（OAuth 2.0）

狀態操作：

封鎖 - 暫時封鎖卡片
解除封鎖 - 重新啟用已封鎖的卡片
卡片損壞 - 通報卡片損壞並申請補發
客戶臨時停用 - 由客戶發起的臨時封鎖
TEMP_BLOCK_SHELL - 由發卡機構發起的臨時封鎖

注意： 卡片註銷屬永久性措施，無法撤銷。

其他端點

類別	端點	方法	說明
取消	/card-management/v1/cancel	POST	取消一張或多張卡片
卡片移轉	/card-management/v1/move	POST	將卡片移轉至另一個卡片群組或帳戶
PIN 碼管理	/card-management/v1/pinreminder	POST	為卡片請求 PIN 碼提醒
寄送地址	/card-management/v1/deliveryaddressupdate	POST	更新卡片寄送地址
自動續期	/card-management/v1/autorenew	POST	更新重新發卡指標

使用範例

範例 1：搜尋即將過期的卡片

POST /card-management/v1/search

{
    "篩選條件": {
 "付款人編號": "CZ00000927",
 "帳號": "CZ00000927",
 "公司代碼": 32,
        "CardStatus": [
 "Active"
 ],
 "ExpiringInDays" : 70
 
 },
    "Page": 1,
    "PageSize": 1
}

範例 2：暫時封鎖卡片

POST /card-management/v1/updatestatus

{

  "Cards": [
    {
      "CardId": 125,
 "ColCoCode": 86,
 "PayerNumber": "PH50000843",
    },
    "ReasonId": 1236,
    "ReasonText": "解除停用",
    "TargetStatus": "Unblock"

  ]
}

範例 3：取消卡片

POST /card-management/v1/cancel

{
 
 "Cards": [
    {
 "CardId": 125,
 "CardExpiryDate": "20231231",
      "ColCoCode": 86,
 "PayerNumber": "PH50000843",
    }
  ],
  "ReasonText": "遺失",
  "RequestId": "1"
}

錯誤處理

常見錯誤代碼

HTTP 狀態碼	錯誤代碼	說明	解決方案
200	不適用	狀態：成功	不A
400	E0001	驗證錯誤	檢查請求參數
401	E0003	未授權	確認 OAuth 憑證是否有效
403	E0003	禁止存取	請檢查使用者權限
404	E0005	資源未找到	請確認端點 URL 及資源是否存在
500	E0002	未知錯誤 / 內部伺服器錯誤	請聯絡技術支援

最佳實務

1. 採用 OAuth 2.0 驗證

重要： 所有客戶均應遷移至 OAuth 2.0 驗證。實施適當的憑證管理：

快取存取憑證並重複使用直至過期
在憑證過期前刷新憑證（建議在過期前 60 秒進行）
安全儲存客戶端憑證（使用環境變數或機密管理器）
切勿在客戶端程式碼中記錄或洩露存取憑證

2. 使用請求 ID

務必包含唯一的 RequestId（GUID 格式），以確保端到端可追溯性

3. 實作分頁功能

針對大型資料集，請使用分頁功能以避免超時

4. 在沙盒環境中進行測試

在移轉至生產環境前，務必先在測試／沙盒環境中測試整合

SDK 與程式碼範例

Shell 提供官方 SDK 及完整的程式碼範例，以加速您與卡片管理 API 的整合。

可用的 SDK 程式語言

Python - 支援 OAuth 2.0 的全功能 SDK
TypeScript - 具備完整類型定義的類型安全 SDK
Java - 企業級級 SDK
C#/.NET - 完整的 .NET 整合
PHP - 易於使用的 PHP 函式庫
Ruby - 實現無縫整合的 Ruby gem

查看官方 SDK 與文件

支援與資源

技術支援

支援： Shell 技術支援

文件

取得協助

聯絡支援服務時，請提供：

您的 client_id（切勿分享您的 client_secret 或存取憑證）
API 回應中的 RequestId
請求的時間戳記
環境（生產／測試）

最後更新日期： 2026年7月1日
文件版本： 1.0
API 版本： 3.1.5

選擇語言

殼牌 B2B 移動支付卡管理 API - 快速入門指南

概述

主要功能

重要通知 - OAuth 2.0

驗證

OAuth 2.0（標準驗證方法）

OAuth 2.0 流程

步驟 1： 取得存取憑證

步驟 2：在 API 請求中使用存取憑證

存取憑證管理

OAuth 2.0 採用策略

為何要遷移至 OAuth 2.0？

安全性優勢：

營運優勢：

遷移路徑

環境

快速入門

1. 取得您的 OAuth 憑證

2. 取得存取憑證

cURL 範例：

回應：

3. 發出您的第一個 API 請求

cURL 範例：

回應範例：

API 端點參考

卡片搜尋與擷取

卡片摘要

卡片訂購

卡片狀態管理

其他端點

使用範例

範例 1：搜尋即將過期的卡片

範例 2：暫時封鎖卡片

範例 3：取消卡片

錯誤處理

常見錯誤代碼

最佳實務

1. 採用 OAuth 2.0 驗證

2. 使用請求 ID

3. 實作分頁功能

4. 在沙盒環境中進行測試

SDK 與程式碼範例

可用的 SDK 程式語言

支援與資源

技術支援

文件

取得協助

關於我們

聯絡人

登入您的帳戶

步驟 1：取得存取憑證