B2B Mobility Customer Data v3.0.5 | B2B 行動服務客戶資料快速入門指南

B2B Mobility 客戶資料快速入門

簡介

B2B Mobility 客戶資料 API 是一項 RESTful 服務，可讓您在 Shell Cards 平台內查詢及管理客戶帳戶詳細資料、卡片群組及相關設定。此 API 提供靈活的搜尋功能，支援分頁，並讓您能擷取帳戶資訊、卡片寄送地址、價格清單及卡片類型。此外，它亦支援建立與更新卡片群組，以及在群組間移動卡片等操作。

優勢	說明
全面的帳戶管理	存取詳細的客戶帳戶資訊，包括帳單、卡片摘要及狀態
卡片群組操作	建立、更新及終止卡片群組，並具備靈活的卡片移動功能
價格清單存取	擷取包含客戶專屬折扣的國內及國際價格清單
彈性搜尋	支援多重搜尋條件及分頁功能，可查詢資料

驗證

此 API 同時支援基本驗證 (Basic Authentication) 與 OAuth 2.0。為提升安全性，建議採用 OAuth 2.0 作為驗證方式。

遷移說明

此 API 現已支援 OAuth 2.0 驗證。若您目前仍在使用基本驗證，我們建議您遷移至 OAuth 2.0 以提升安全性。基礎 URL 已更新，所有端點現均以 /v1 路徑進行版本標示。請參閱《OAuth 2.0 遷移支援》以獲取詳細的遷移指引。

授權流程

申請客戶端 ID 與密鑰

請聯絡 Shell API 團隊以申請 OAuth 驗證權限。 Shell API 團隊將提供 Client ID 和 Secret。

請求 Bearer 憑證

取得憑證後，請使用您的憑證向 Shell 驗證 API 的 OAuth 憑證端點發送請求，並附上您的憑證。

請求範例：

curl --location --request POST 'https://api-test.shell.com/v2/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=**************' \
--data-urlencode 'client_secret=**************' \
--data-urlencode 'grant_type=client_credentials'

您將在回應中收到一個 Bearer 憑證：

{
   "access_token": "**************",
   "expires_in": "899",
   "token_type": "Bearer"
}

注意： Bearer 憑證的過期時間以秒為單位表示。

授權 API 請求

呼叫 Shell API 時，請在請求的標頭中包含以下內容。

Authorization: Bearer access_token

基礎 URL

環境	URL
測試	https://api-test.shell.com/test
正式環境	https://api.shell.com

核心整合

1. 取得已登入使用者詳細資料

說明： 此端點會擷取已登入使用者的資料，包括可存取的付款人、帳戶及角色。此操作應在成功驗證後呼叫，以取得後續 API 呼叫所需的 PayerId。

路徑： POST /user-management/v1/loggedinuser

範例請求

curl --location 'https://api-test.shell.com/test/user-management/v1/loggedinuser' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "IncludePayerGroup": false,
    "IncludeEIDDetails": false,
    "RequestedAPIName": "v1/Card/OrderCard"
  }
}'

請求參數

參數	類型	必填	說明
RequestId	字串	是	用於請求追蹤的強制性 UUID（RFC 4122）
IncludePayerGroup	布林值	否	若為 true，則包含付款人群組資訊（預設：false）
IncludeEIDDetails	布林值	否	若為 true，則包含電子發票資料（預設：false）

回應範例

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "UserName": "John123",
 "DisplayName": "John A.",
      "HasAPIAccess": true,
 "Payers": [
 {
 "IsDefault": true,
 "ColcoId": 1,
 "ColcoCode": 86,
          "付款人 ID": 1234,
 "付款人編號": "GB000000123",
 "付款人名稱": "MATTHEW ALGIE & COMPANY LIMITED"
 }
 ]
    }
  ]
}

回應欄位

欄位	類型	說明
UserName	字串	已登入使用者的識別碼
DisplayName	字串	已登入使用者的名稱
HasAPIAccess	布林值	若使用者具備存取所請求 API 的權限，則為 True
PayerId	整數	用於後續請求的付款人 ID
付款人編號	字串	用於後續請求的付款人編號

2. 查詢客戶帳戶

說明： 此端點允許透過 Shell Cards Platform 查詢客戶帳戶詳細資訊，並支援靈活的搜尋條件與分頁功能。請使用前一步驟取得的 PayerId。

路徑： POST /customer-management/v1/accounts

範例請求

curl --location 'https://api-test.shell.com/test/customer-management/v1/accounts' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "Status": "ACTIVE",
    "IncludeCardSummary": true
  },
  "Page": 1,
  "PageSize": 50
}'

請求參數

參數	類型	必填	說明
ColCoCode	整數	是	收款公司代碼（殼碼）
付款人編號	字串	是	客戶的付款人編號
狀態	字串	否	帳戶狀態篩選條件（ACTIVE、已封鎖、已取消等）
IncludeCardSummary	布林值	否	是否包含卡片摘要詳細資訊（預設：true）
Page	整數	否	頁碼（預設：1）
PageSize	整數	否	每頁記錄數（預設：50）

範例回應

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "AccountId": 1,
 "AccountNumber": "GB000000124",
 "AccountFullName": "Acme Corporation",
      "Status": "Active",
 "CurrencyCode": "EUR",
 "TotalCards": 1000,
 "TotalActiveCards": 500
    }
  ],
  "Page": 1,
  "TotalRecords": 100,
  "TotalPages": 2,
  "PageSize": 50
}

回應欄位

欄位	類型	說明
AccountId	整數	帳戶識別碼
AccountNumber	字串	帳戶號碼
AccountFullName	字串	帳戶全名
Status	字串	帳戶當前狀態
CurrencyCode	字串	ISO 貨幣代碼
TotalCards	整數	該帳戶下的卡片總數
TotalActiveCards	整數	有效卡片數量

3. 查詢卡片群組

說明： 此端點可透過靈活的搜尋條件與分頁功能，從 Shell Cards Platform 擷取卡片群組的詳細資訊。卡片群組有助於整理帳戶內的卡片。

路徑： POST /customer-management/v1/cardgroups

範例請求

curl --location 'https://api-test.shell.com/test/customer-management/v1/cardgroups' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "Status": "ACTIVE"
  },
  "Page": 1,
  "PageSize": 50
}'

請求參數

參數	類型	必填	說明
ColCoCode	整數	是	收款公司代碼
PayerNumber	字串	是	客戶的付款人編號
狀態	字串	是	卡組狀態（ACTIVE、TERMINATED、 ALL)
卡組名稱	字串	否	依卡組名稱篩選（至少 2 個字元）

範例回應

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "CardGroupId": 40000,
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "Status": "ACTIVE",
      "PrintOnCard": true,
 "CardTypeId": 1234,
 "TotalCards": 1234,
 "ActiveCards": 999
    }
  ],
  "Page": 1,
  "TotalRecords": 100,
  "TotalPages": 2,
  "PageSize": 50
}

回應欄位

欄位	類型	說明
CardGroupId	整數	卡片群組識別碼
CardGroupName	字串	卡片群組名稱
Status	字串	卡片群組狀態
TotalCards	整數	該群組中的卡片總數
ActiveCards	整數	該群組中的活躍卡片數量

4. 建立卡片群組

說明： 此端點會在 Shell Cards Platform 中建立一個新的卡片群組，並可選擇將最多 500 張卡片移入新建立的群組。卡片移動請求在驗證後會被排入佇列。

路徑： POST /customer-management/v1/createcardgroup

範例請求

curl --location 'https://api-test.shell.com/test/customer-management/v1/createcardgroup' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "ColCoCode": 86,
  "PayerNumber": "GB000000123",
  "AccountNumber": "GB000000124",
  "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
  "PrintOnCard": true,
  "Cards": [
    {
 "AccountNumber": "GB99215176",
 "PAN": "7002051006629890645"
    }
  ]
}'

請求參數

參數	類型	必填	說明
ColCoCode	整數	是	收款公司代碼
PayerNumber	字串	是	客戶的付款人編號
帳戶號碼	字串	是	客戶的帳戶號碼
卡組名稱	字串	是	新卡組的名稱（1-40 個字元）
PrintOnCard	布林值	是	是否要在卡片上壓印卡組名稱
Cards	陣列	否	待移轉的卡片清單（最多 500 張）

範例回應

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "MainReference": 1234,
 "NewCardGroupReference": 5672,
 "SuccessfulRequests": [
 {
 "PAN": "7002051123456789145",
 "Reference": 12345
 }
 ],
 "ErrorCards": []
    }
  ]
}

回應欄位

欄位	類型	說明
主參考編號	整數	用於追蹤整體請求的參考編號
NewCardGroupReference	整數	用於建立卡片群組的參考編號
SuccessfulRequests	陣列	已成功排入佇列的卡片移動請求清單
ErrorCards	陣列	驗證失敗的卡片清單

錯誤處理

此 API 使用標準的 HTTP 狀態碼。若發生錯誤，回應正文中將提供更多詳細資訊。

錯誤代碼	說明	解決方案
E0001	驗證錯誤	檢查請求參數中是否有遺漏或無效的值
E0003	未經授權	請驗證憑證，並確保使用者具備執行該操作的權限
E0005	資源未找到	請確認所請求的資源確實存在且可存取
9015	卡片群組名稱重複	請為該客戶使用唯一的卡片群組名稱

選擇語言

B2B Mobility Customer Data 3.0.5

B2B Mobility 客戶資料快速入門

簡介

驗證

遷移說明

授權流程

基礎 URL

核心整合

1. 取得已登入使用者詳細資料

範例請求

請求參數

回應範例

回應欄位

2. 查詢客戶帳戶

範例請求

請求參數

範例回應

回應欄位

3. 查詢卡片群組

範例請求

請求參數

範例回應

回應欄位

4. 建立卡片群組

範例請求

請求參數

範例回應

回應欄位

錯誤處理

關於我們

聯絡人

登入您的帳戶