Shell B2B 移動支付卡交易資料 API - 快速入門指南

API 版本： 2.3.5 | 驗證： OAuth 2.0 | 狀態： 正式環境

概述

Shell 卡片交易資料 API 是一項基於 REST 的 API，可讓開發人員透過程式化方式擷取並分析 Shell 加油卡的交易資料。此 API 提供對定價交易、費用、按用量計價、獎勵規則、例外情況以及卡片使用摘要等資料。

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

主要功能

擷取含價格的交易明細，包括電動車交易
查閱包含銷售項目與費用的燃料交易明細
取得燃油及非燃油（NFR）交易的摘要資料
查詢按量計價與獎勵規則
檢索手續費項目與手續費摘要資料
查閱卡片與交易異常紀錄
分析卡片使用與支出資料
支援多付款人交易查詢

重要通知 - OAuth 2.0

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

新整合方案： 請從一開始就使用 OAuth 2.0
現有整合方案： 規劃您的 OAuth 2.0 遷移計畫
舊版方法： 基本驗證（Basic Auth）正逐步淘汰

請聯絡 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=您的-客戶端-secret"

回應：

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

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

範例：取得已定價交易

cURL 範例：

curl -X POST https://api-test.shell.com/test/transaction-data/v1/priced \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "Filters": {
 "ColCoCode": "5",
 "PayerNumber": "DE26667080",
 "InvoiceStatus": "A",
        "IncludeFees": true,
 "FromDate": "2024-12-01 00:00:00",
 "ToDate": "2025-01-20 00:00:00"
    },
    "Page": 1,
    "PageSize": 1
}'

回應範例：

{
  "RequestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
  "Status": "SUCCESS",
  "Data": [
    {
      "AccountName": "Blue Colour Ltd",
 "AccountId": 29484,
 "AccountNumber": "DE26667080",
 "AccountShortName": "Mathew",
 "Additional1": "GBALLEGO0002452",
 "Additional2": "GBALLEGO0002452",
 "Additional3": "GBALLEGO0002452",
 "Additional4": "GBALLEGO0002452",
 "AllowClearing": "Null",
 "AuthorisationCode": 300796,
 "TransactionStatus": "Y",
 "DriverName": "SATTY BHAMRA",
 "CardExpiryPeriod": 2204,
 "CardExpiry": "20220101",
 "CardGroupId": 40000,
 "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
 "IssuerCode": 7002,
 "CardPAN": "7002053465789891000",
 "ReleaseCode": 9,
 "CardSequenceNumber": 617,
      "CardType": "GB STD FLT NAT SINGLE R9",
 "ColCoCode": "014",
 "UnitDiscountInvoiceCurrency": -0.0051,
 "ColCoExchangeRate": 0.851858,
      "發票貨幣符號": "GBP",
 "更正標記": true,
 "CRM編號": 10,
 "客戶國家": "英國",
 "客戶貨幣代碼": "GBP",
 "客戶貨幣符號": "£",
 "以客戶貨幣計算的淨額回扣": 0,
 "以客戶貨幣計算的有效折扣": -0.22,
 "以客戶貨幣計算的有效單價折扣": -0.0051,
      "單價（以發票貨幣計）": 1.1024,
 "發票稅額": 0,
      "發票總金額": 57.25,
 "發票淨金額": 47.71,
 "客戶貨幣淨金額之增值稅": 9.54,
 "客戶零售單價（含稅）": 0,
      "客戶零售總值（含稅）": 57.52,
 "客戶零售總值（不含稅）": 47.93,
 "交易類型描述": 9.59,
 "以交易貨幣計算之淨額回饋": -0.22,
 "交易貨幣之實際折扣": -0.22,
 "發卡國與收款國匯率": 0,
 "卡片": [
 275549
 ],
 "交易貨幣之單位折扣幣": -0.005,
 "交易總金額": 57.25,
 "交易淨金額": 47.71,
 "交易稅額": 9.54,
 "淨金額之增值稅": 9.54,
      "Delco 標價單位淨額": 0,
 "Delco 零售價單位總額": 1.32888,
 "交易貨幣單位價格": 1.1074,
 "Delco 零售價格單位淨額": 1.1074,
 "Delco 零售總值總額（含稅）": 57.52,
 "Delco零售淨值總額": 47.93,
 "交易貨幣符號": "$",
 "折扣類型": 1,
      "爭議狀態": false,
 "是否為 Shell 站點": false,
 "車隊編號輸入": "YG67OUM",
 "入帳產品代碼": 23,
 "發佈日期": "20210802",
 "發佈時間": "14:15:22",
 "產品代碼": 30,
 "產品名稱": "無鉛汽油 - 中級辛烷值",
 "產品群組編號": 22,
 "入帳貨幣代碼": "GBP",
      "進帳站點描述": "Shell Broadway Ring",
 "地點": "Shell Broadway Ring",
 "站點名稱": "Shell Broadway Ring",
 "站點代碼": 32,
 "進帳站點編號": 15,
 "發票貨幣代碼": "GBP",
 "發票日期": "20210802",
 "發票編號": 3201016193,
 "燃油產品": true,
      "需繳付增值稅": "是",
 "付款方名稱": "Colours Services Ltd",
 "付款方編號": "GB12121212",
 "母客戶編號": "GB12121212",
 "付款方群組": "H312066",
 "付款方群組名稱": "12162566 - 燃油卡服務",
 "校驗位": 6,
      "淨發票標示": "Y",
 "Delco 代碼": 5,
 "網路代碼": 3,
      "採購國家": "英國",
 "據點國家": "英國",
 "增值稅國家": "英國",
 "Delco名稱": "Shell U.K. Oil Products Limited",
 "網路": "Shell",
      "里程表讀數輸入": 0,
 "原始銷售項目編號": "Null",
 "車隊編號說明": "YG67OUM",
 "父客戶編號": 6494,
 "PIN 標示": "Y, N",
 "產品群組名稱": "費用",
 "購買國家代碼": "GB",
      "數量": 43.28,
 "回扣率": 0.0022,
 "收據編號": 6803,
 "退款標記": "是",
 "站點群組 ID": 202,
      "SiteGroupName": "CZ 9100 ECONOMY NETWORK",
 "Latitude": 53.83606,
 "Longitude": -1.61854,
      "DelCo匯率": 0.851858,
 "歐元退款金額": -0.258259,
 "淨歐元金額": 56.01,
 "歐元增值稅金額": 11.2,
      "母公司名稱": "FUEL CARD SERVICES LTD",
 "已開立發票": false,
 "交易貨幣代碼": "GBP",
      "CreditDebitCode": "D 或 C",
 "TransactionDate": "20210801",
 "TransactionTime": "12:16:58",
 "TransactionItemId": "H305908971030",
 "交易識別碼": "H305908971030",
 "類型": "銷售",
 "交易行號": 1,
 "交易類型": "購買",
 "UTC偏移量": "Europe/London",
 "增值稅類別": "英國標準增值稅率",
 "VATRate": 0.2,
 "VehicleRegistration": "YG67OUM",
 "IsCancelled": "Y",
 "ColCoGrossAmount": 57.25,
 "ColCoNetAmount": 47.71,
 "ColCoVATAmount": 9.54,
 "OriginalCurrencySymbol": "$",
 "OriginalCurrencyCode": "$",
 "原始增值稅金額": 0,
 "壓印文字": "PARKLANE PROPERTIES LTD",
 "原始匯率": 0,
 "原始交易明細發票日期": "20220202",
 "FeeTypeId": 1,
 "LineItemDescription": true,
 "FeeRuleDescription": "簡單費用",
 "Frequency": 1,
 "FeeRuleId": 1,
 "SystemEntryDate": "20210828",
 "SystemEntryTime": "20:21:08",
 "IsManual": "Y",
 "原始交易項目編號": "Y",
 "原始交易項目發票編號": 6750802,
 "原始交易項目發票編號": 234,
 "付款人簡稱": "FUEL CARD SERVICES LTD",
 "ReverseCharge": "Y",
 "OriginalGrossAmount": 57.25,
      "原始淨金額": 57.25,
 "計量單位": "L",
 "道路類型": "國道",
 "客戶國家 ISO 代碼": "DE",
      "EVOperator": "Shell Recharge",
 "EVSerialId": "GBALLEGO0002452",
 "EVChargePointSerial": "GBALLEGO0002452",
 "EVChargePointConnectorType": 5,
 "EVChargePointConnectorTypeDescription": "直流 50 kW",
 "EVChargeDuration": "PT3205S",
 "EVChargeStartDate": "2021-08-01",
 "EVChargeStartTime": "20:08:01",
 "EVChargeEndDate": "2022-08-01",
 "EVChargeEndTime": "20:08:01",
 "HostingCollectingCompanyNumber": 0,
 "TransactionId": 0,
      "FuelOnly": true,
      "EVPrintedNumber": "ZZ2WJ53ZZ5",
 "IsRFID": true
    }
  ],
  "Page": 1,
  "PageSize": 1,
  "TotalPages": 5
}

API 端點參考

計費交易

端點	方法	說明
/transaction-data/v1/priced	POST	取得含 EV 交易的計費交易明細（OAuth 2.0）
/transaction-data/v1/pricedtransaction	POST	取得含銷售項目與費用的燃料交易明細，包含銷售項目與手續費（OAuth 2.0）
/transaction-data/v1/multipayerspricedtransactions	POST	取得多付款人的計費交易明細（OAuth 2.0）

常見使用情境：

依日期範圍擷取交易紀錄
依發票狀態篩選（已開立發票、未開立發票等）
依卡片主號 (PAN) 或車輛登記號碼搜尋
檢視電動車充電交易紀錄
查詢跨多個付款人的交易紀錄

交易摘要

端點	方法	說明
/transaction-data/v1/pricedtransactionssummary	POST	取得計費交易摘要資料，包含銷售項目與費用（OAuth 2.0）
/transaction-data/v1/cardusagesummary	POST	取得某張卡片的支出分析與使用摘要（OAuth 2.0）

回傳內容：

按期間彙總的交易資料
總交易量與總金額
按產品類型與類別細分
卡片層級支出分析

費用管理

端點	方法	說明
/transaction-data/v1/feessummary	POST	取得指定付款人（OAuth 2.0）的費用明細摘要資料

費用資訊：

擷取適用於交易的費用項目
各期間的所有費用摘要
按類型和類別劃分的費用明細
付款人層級費用分析

基於交易量的規則

端點	方法	說明
/transaction-data/v1/volumebasedpricing	POST	取得指定付款人的逾期費用規則設定（OAuth 2.0)
/transaction-data/v1/volumebasedbonus	POST	取得指定付款方（OAuth 2.0）的獎勵及關聯獎勵規則設定

基於交易量的功能：

存取基於交易量的定價規則
檢索獎勵計算規則
取得關聯獎勵配置

例外情況

端點	方法	說明
/transaction-data/v1/exceptions	POST	取得與卡片或交易相關的例外狀況 (OAuth 2.0)

例外情況類型：

交易驗證失敗
卡片使用異常
授權異常

常見使用案例

本節將常見的商業情境與相應的 API 端點進行對應，協助您快速辨識應使用哪些 API 來滿足您的特定需求。

使用案例 1：每日交易對帳

情境情： 您需要每日對車隊卡的所有交易進行對帳，以供會計用途。

建議使用的 API： /transaction-data/v1/priced

為何選擇此 API： 此端點提供全面的交易明細（包括電動車充電交易），支援靈活的日期篩選，並涵蓋已開立帳單與未開立帳單的交易。非常適合每日對帳，且針對大型資料集提供分頁功能支援。

關鍵參數：

PostingDateFrom 與 PostingDateTo — 設定為昨日日期
InvoiceStatus — 所有交易均設為「A」
PageSize — 設定為 100 以提升資料擷取效率

使用案例 2：發票驗證與核對

情境： 您收到一張發票，需要驗證所有交易明細，包括各項費用與收費項目。

建議使用的 API： /transaction-data/v1/pricedtransaction

為何選擇此 API： 專為提供詳細的燃油交易資訊而設計，包含銷售項目及所有相關費用。由於其結構與發票格式相符，因此非常適合用於發票驗證。

關鍵參數：

發票編號 — 待驗證的特定發票
發票日期 - 來自您的帳單的發票日期
IncludeFees - 設定為 true 以查看所有費用項目

用例 3：燃油消耗分析與報告

情境： 您需要分析過去一個月車隊的燃油消耗模式，以優化路線並降低成本。

建議使用的 API：

/transaction-data/v1/pricedtransactionssummary - 用於彙總資料

為何選擇這些 API: 摘要端點會按產品、站點群組及時間區間提供彙總數據，無需處理大量交易資料，非常適合進行趨勢分析。

關鍵參數：

PostingDateFrom 與 PostingDateTo — 設定為最近 30 天
ProductCode — 依特定燃料類型篩選
產品代碼 — 依特定燃料類型篩選

用例 4：多車隊管理

情境： 您管理多個子帳戶或付款人，並需要擷取所有帳戶的交易資料以進行合併報表彙整。

建議使用的 API： /transaction-data/v1/multipayerspricedtransactions

為何選用此 API： 專為透過單次 API 呼叫查詢多個付款方的交易而設計，能顯著減少請求次數，並提升多車隊情境下的效能。

關鍵參數：

帳戶 — 付款人 ID 與號碼的陣列（最多 10 位付款人）
發票狀態 — 所有交易均為「A」
PostingDateFrom 及 PostingDateTo — 報表期間

用例 5：異常監控與詐欺偵測

情境： 您希望識別異常的交易模式，例如高額交易、過量的燃油消費量，或使用情況異常的卡片，以防止詐欺或濫用。

建議使用的 API： /transaction-data/v1/exceptions

為何選擇此 API： 專為識別超過定義閾值的交易而設計，非常適合用於監控異常情況及潛在詐騙行為。

關鍵參數：

條件 - 設定閾值類型（ValueGreaterThan、VolumeGreaterThan 等）
值 - 定義閾值
輸出類型 - 交易異常請選「交易」
TransactionsFromDate 及 TransactionsToDate — 監控期間

用例 6：費用與收費分析

情境： 您需要了解帳戶所適用的一切費用與收費，以找出節省成本的機會或驗證帳單內容。

建議使用的 API： /transaction-data/v1/feessummary

為何選用此 API： 提供按費用類型、產品群組及費用群組彙總的費用資訊，便於分析費用結構並找出高成本領域。

關鍵參數：

InvoiceStatus - 「I」代表僅包含已開立發票的費用
FeeTypeGroup - 可依「卡片費用」、「帳戶費用」等項目進行篩選
PostingDateFrom 及 PostingDateTo — 分析期間

用例 7：個別卡片支出追蹤

情境： 駕駛員要求查詢過去 6 個月的交易紀錄，或您需要分析特定卡片的消費模式。

建議使用的 API： /transaction-data/v1/cardusagesummary

為何選用此 API： 提供過去 7 個月內單張卡片的詳細消費分析，並按網站和產品分組，非常適合用於卡片層級的報表編製。

關鍵參數：

CardId 或 PAN — 待分析的特定卡片
CardExpiry — 用於額外驗證
AccountId - 可選的帳戶篩選條件

用例 8：基於用量的定價資格檢查

情境： 您希望檢查您的帳戶是否符合基於用量的定價層級資格，並了解您當前的消耗量是否達到定義的閾值。

建議使用的 API： /transaction-data/v1/volumebasedpricing

為何選擇此 API： 顯示您的滯納金規則、階層配置及當前用量，協助您了解定價結構並規劃如何達到更優惠的階層。

關鍵參數：

PayerNumber - 您的付款帳戶
IncludeHistory - 設定為 true 以查看歷史計算結果
包含當期交易量 — 設定為 true 以進行按月

用例 9：獎金與回饋追蹤

情境： 您有基於交易量的獎金協議，並希望追蹤達成獎金門檻的進度，以及查看先前已賺取的獎金。

建議使用的 API： /transaction-data/v1/volumebasedbonus

為何選用此 API： 提供獎金規則、當期消耗量及歷史獎金計算的完整詳細資訊，讓您能優化採購以最大化獎金收益。

關鍵參數：

PayerNumber - 您的付款人帳戶
IncludeHistory - 設定為 true 以查看過往的獎金支付
IncludeCurrentPeriodVolume - 設定為 true 以追蹤當前期間的進度

使用範例

範例 1：取得已定價交易（包含 EV）

請求：

POST /transaction-data/v1/priced

{
  "PageSize": 1,
  "Page": 1,
  "Filters": {
    "ColCoCode": "5",
    "ColCoId": 5,
    "InvoiceStatus": "A",
    "PayerNumber": "DE26685263",
    "AccountId": 29484,
    "Account號碼": "DE26667080",
    "卡片PAN": "7002051006629890645",
    "FromDate": "2022-01-01 00:00:00",
    "ToDate": "2022-01-31 00:00:00",
    "IncludeFees": true
  }
}

回應：

{
  "RequestId": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
  "Status": "SUCCESS",
  "Data": [
    {
 "AccountName": "Blue Colour Ltd",
 "AccountId": 29484,
 "AccountNumber": "DE26667080",
 "AccountShortName": "Mathew",
 "Additional1": "GBALLEGO0002452",
 "Additional2": "GBALLEGO0002452",
      "Additional3": "GBALLEGO0002452",
 "Additional4": "GBALLEGO0002452",
 "AllowClearing": "Null",
 "AuthorisationCode": 300796,
      "交易狀態": "是",
 "駕駛員姓名": "SATTY BHAMRA",
 "卡片有效期": 2204,
 "卡片到期日": "20220101",
      "卡片群組編號": 40000,
 "卡片群組名稱": "006240 FIRE BRIGHT SOLUTIONS",
 "發卡機構代碼": 7002,
      "CardPAN": "7002053465789891000",
 "ReleaseCode": 9,
 "CardSequenceNumber": 617,
 "CardType": "GB STD FLT NAT SINGLE R9",
 "ColCoCode": "014",
 "UnitDiscountInvoiceCurrency": -0.0051,
 "ColCoExchangeRate": 0.851858,
 "Invoice貨幣符號": "GBP",
 "更正標記": true,
 "CRM編號": 10,
 "客戶國家": "英國",
      "客戶貨幣代碼": "GBP",
 "客戶貨幣符號": "£",
 "以客戶貨幣計算的淨額回饋": 0,
      "以客戶貨幣計算之實際折扣": -0.22,
 "以客戶貨幣計算之實際單位折扣": -0.0051,
 "以發票貨幣計算之單價": 1.1024,
      "發票稅額": 0,
 "發票總金額": 57.25,
 "發票淨金額": 47.71,
 "以客戶貨幣計算之淨金額所適用之增值稅": 9.54,
 "客戶退單價（含稅）單位」：0,
      "客戶零售總值（含稅）": 57.52,
 "客戶零售總值（不含稅）": 47.93,
 "交易類型描述": 9.59,
 "以交易貨幣計算之淨額回饋": -0.22,
      "有效折扣（交易貨幣）": -0.22,
 "發卡國至收款國匯率": 0,
 "卡片": [
 275549
      ],
 "每單位折扣（交易貨幣）": -0.005,
 "交易總金額": 57.25,
 "交易淨金額": 47.71,
 "交易稅額": 9.54,
 "淨額增值稅": 9.54,
 "Delco 標價單位淨額": 0,
 "Delco 零售價單位總額": 1.32888,
      "交易貨幣單位價格": 1.1074,
      "Delco 零售單價（淨額）": 1.1074,
 "Delco 零售總值（含稅）": 57.52,
 "Delco 零售總值（淨額）": 47.93,
 "交易貨幣符號": "$",
      "折扣類型": 1,
 "爭議狀態": false,
 "是否為加油站": false,
 "車隊編號輸入": "YG67OUM",
 "入庫商品代碼": 23,
 "過帳日期": "20210802",
 "發布時間": "14:15:22",
      "產品代碼": 30,
 "產品名稱": "無鉛汽油 - 中等辛烷值",
 "產品群組 ID": 22,
 "入帳貨幣代碼": "GBP",
 "入帳站點描述": "Shell Broadway Ring",
 "地點": "Shell Broadway Ring",
 "站點名稱": "Shell Broadway Ring",
 "站點代碼": 32,
 "入帳站點編號": 15,
 "發票貨幣代碼": "GBP",
      "發票日期": "20210802",
 "發票編號": 3201016193,
 "燃油產品": true,
 "適用增值稅": "是",
      "付款方名稱": "Colours Services Ltd",
 "付款方編號": "GB12121212",
 "母客戶編號": "GB12121212",
      "付款方群組": "H312066",
 "付款方群組名稱": "12162566 - 燃油卡服務",
 "校驗位": 6,
 "淨發票標示": "Y",
      "DelcoCode": 5,
 "NetworkCode": 3,
 "PurchasedInCountry": "英國",
 "SiteCountry": "英國",
 "VATCountry": "英國",
 "供應商名稱": "Shell U.K. Oil Products Limited",
 "網路": "Shell",
      "里程表輸入值": 0,
 "原始銷售項目編號": "Null",
 "車隊編號說明": "YG67OUM",
 "父客戶編號": 6494,
 "PIN 指標": "是, 否",
 "產品群組名稱": "費用",
 "購買國家代碼": "GB",
 "數量": 43.28,
 "返利率": 0.0022,
 "收據編號": 6803,
 "退款標記": "Y",
 "據點群組編號": 202,
 "據點群組名稱": "CZ 9100 ECONOMY NETWORK",
 "緯度": 53.83606,
 "經度": -1.61854,
 "DelCo匯率": 0.851858,
 "歐元退款金額": -0.258259,
 "淨歐元金額": 56.01,
      "歐元增值稅金額": 11.2,
 "母客戶名稱": "FUEL CARD SERVICES LTD",
 "已開立發票": false,
 "交易貨幣代碼": "GBP",
      "CreditDebitCode": "D 或 C",
 "TransactionDate": "20210801",
 "TransactionTime": "12:16:58",
 "TransactionItemId": "H305908971030",
 "TrnIdentifier": "H305908971030",
      "Type": "SALE",
 "TransactionLine": 1,
 "TransactionType": "Purchase",
 "UTCOffset": "Europe/London",
 "VATCategory": "英國標準增值稅率",
      "增值稅率": 0.2,
 "車輛登記號碼": "YG67OUM",
 "是否已取消": "Y",
 "ColCo總金額": 57.25,
      "ColCo淨金額": 47.71,
 "ColCo增值稅金額": 9.54,
 "原始貨幣符號": "$",
 "原始貨幣代碼": "$",
      "原始增值稅金額": 0,
 "浮雕文字": "PARKLANE PROPERTIES LTD",
 "原始匯率": 0,
 "原始交易明細發票日期": "20220202",
      "費用類型編號": 1,
 "明細項目描述": true,
 "費用規則描述": "簡單費用",
 "頻率": 1,
 "費用規則編號": 1,
      "系統入帳日期": "20210828",
 "系統入帳時間": "20:21:08",
 "是否手動": "Y",
      "原始交易明細編號": "Y",
 "原始交易明細發票編號": 6750802,
 "原始交易明細發票編號": 234,
      "付款人簡稱": "FUEL CARD SERVICES LTD",
 "反向徵稅": "Y",
 "原始總金額": 57.25,
 "原始淨金額": 57.25,
 "計量單位": "L",
 "道路類型": "國道",
 "客戶國家 ISO 代碼": "DE",
 "電動車營運商": "Shell Recharge",
      "EVSerialId": "GBALLEGO0002452",
 "EVChargePointSerial": "GBALLEGO0002452",
      "EVChargePointConnectorType": 5,
 "EVChargePointConnectorTypeDescription": "直流 50 kW",
 "EVChargeDuration": "PT3205S",
      "EVChargeStartDate": "2021-08-01",
 "EVChargeStartTime": "20:08:01",
      "EVChargeEndDate": "2022-08-01",
 "EVChargeEndTime": "20:08:01",
      "主機收費公司編號": 0,
 "交易編號": 0,
 "僅燃料": true,
 "電動車列印編號": "ZZ2WJ53ZZ5",
 "是否RFID": true
    }
  ],
  "Page": 3,
  "PageSize": 30,
  "TotalPages": 5
}

範例 2：取得燃料交易明細

請求：

POST /transaction-data/v1/pricedtransaction

{
  "Filters": {
    "ColCoCode": 14,
    "InvoiceStatus": "A",
    "PayerId": 12345,
    "PayerNumber": "NL10042616"
  },
  "Page": 1,
  "PageSize": 50
}

回應：

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Transactions": [
 {
 "Type": "SalesItem /FeeItem",
 "CardId": 0,
 "CardPAN": "7002051006629891000",
          "CardExpiry": "2026-06-16",
 "TransactionDate": "2026-06-16",
 "TransactionTime": "string",
 "UTCOffset": "字串",
 "車隊編號輸入": "XYZ1234",
 "里程表讀數輸入": 12345,
 "駕駛人姓名": "ANDREW GILBERRY",
 "車輛登記號碼": "MV65YLH",
 "發票貨幣代碼": "GBP",
 "發票貨幣符號": "$",
          "交易貨幣代碼": "GBP",
 "交易貨幣符號": "$",
 "交易淨金額": 0,
 "交易稅額": 0,
          "交易總金額": 0,
 "發票淨金額": 0,
          "發票稅額": 0,
 "發票總額": 0,
 "採購國家": "德國",
 "帳戶編號": 29484,
          "帳戶編號": "GB99215176",
 "帳戶名稱": "MATTHEW ALGIE & COMPANY LIMITED",
 "帳戶簡稱": "字串",
 "數量": 0,
 "燃料產品": true,
          "交易貨幣單位價格": 0,
 "發票貨幣單位價格": 0,
 "交易貨幣單位折扣": 0,
 "發票貨幣單位折扣": 0,
          "IsInvoiced": true,
 "InvoiceNumber": "S04500493",
 "InvoiceDate": "字串",
          "站點代碼": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
 "站點名稱": "050001 -\tCHARNOCK RICHARD NTHBOUND MWSA 0755",
 "SiteCountry": "德國",
 "Location": {
 "Latitude": "37.4224764",
 "Longitude": "122.0842499"
 },
 "卡片群組名稱": "006240 FIRE BRIGHT SOLUTIONS",
          "收據編號": "1234",
 "產品代碼": "10 - TMF 費用",
 "產品名稱": "無鉛汽油 - 高辛烷值",
 "產品群組 ID": 1,
 "產品群組名稱": "父級產品群組",
 "DelCo匯率": 0,
 "ColCo匯率": 0,
 "是否為Shell站點": true,
 "網路": "100013\tSTEINDORFER",
 "站點群組 ID": 202,
 "站點群組名稱": "CZ 9100 ECONOMY NETWORK",
 "過帳日期": "字串",
 "發卡機構代碼": "7002",
          "PurchasedInCountryCode": "NL",
 "CustomerCountryCode": "NL",
 "CustomerCountry": "荷蘭",
 "ReleaseCode": "8",
 "CardGroupId": "字串",
 "CardSequenceNumber": "2",
 "校驗位": "字串",
 "車隊 ID 說明": "字串",
 "增值稅率": "0.20（20%）",
 "增值稅類別": "1-零稅率",
          "增值稅計稅金額": 0,
 "增值稅國家": "荷蘭",
 "交易貨幣有效折扣": 0,
 "交易類型": "實體卡交易時為購買，否則留空",
 "PIN 指標": "“已使用 PIN 碼”",
 "VATApplicable": "Y",
 "NetInvoiceIndicator": "Y",
 "CustomerCurrencyCode": "GBP",
          "客戶貨幣符號": "£",
 "客戶貨幣單位折扣額": 0,
 "客戶貨幣折扣額": 0,
 "客戶貨幣淨金額之增值稅額": 0,
          "折扣類型": "每單位 2 便士",
 "交易狀態": "U",
 "銷售項目 ID": 18315958002,
          "付款方群組": "字串",
 "付款方群組名稱": "12119008 - 殼牌集團",
 "退款標記": "字串",
 "原始銷售項目編號": "字串",
 "Delco名稱": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
 "DelcoCode": "14",
 "PayerNumber": "NL10042616",
 "PayerName": "V.M. LE COMTE",
 "CardExpiryPeriod": "1901",
 "AuthorisationCode": "1011256",
 "TransactionId": "io9KVXk1UkW57XWKyeaHHg",
 "TransactionLine": "1",
 "AllowClearing": "Y",
 "CRMNumber": "字串",
 "爭議狀態": "無爭議",
 "退款率": 28.279,
 "發卡行至收款行匯率": 1,
 "淨歐元金額": 0,
 "歐元增值稅金額": 0,
 "父客戶編號": "字串",
 "父客戶名稱": "字串",
 "母客戶 ID": 0,
 "來源據點編號": "100021",
 "來源據點描述": "HN3 INTI_02-82.02",
 "來源貨幣代碼": "GBP",
          "入帳產品代碼": "30",
 "借貸代碼": "D",
 "更正標記": "Y",
 "附加資訊1": "字串",
 "附加資訊 2": "字串",
 "附加資訊 3": "字串",
 "附加資訊 4": "字串",
 "客戶貨幣淨金額回扣": -0.735,
 "交易貨幣淨金額回扣": "AVEE PTUAZONW CUBFAO COSFS",
 "交易識別碼": "字串",
 "卡片類型": "字串",
 "Delco 標價單位淨額": 30.5,
 "Delco 零售價單位淨額": 1.921,
 "Delco 零售價單位總額": 0,
          "Delco零售價值總額（淨額）": 0,
 "Delco零售價值總額（總額）": 0,
 "客戶零售價格單位（總額）": 0,
 "客戶零售價值總額（淨額）": 0,
          "EVPrintedNumber": "3792",
 "IsRFID": true,
 "TokenTypeDescription": "字串"
 }
 ]
    }
  ],
  "Page": 1,
  "PageSize": 1,
  "TotalPages": 15
}

範例 3：取得已定價交易摘要

請求：

POST /transaction-data/v1/pricedtransactionssummary

{
    "Filters": {
 "ColCoCode": 9,
 "PayerId": 12,
 "InvoiceStatus": "A",
 "FromDate": "2024-03-20",
 "ToDate": "2024-09-17",
 "PurchasedInCountryCode": "AT"
    }
}

回應：

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "ProductId": 1234,
 "ProductCode": "10",
      "ProductName": "柴油 AGO",
 "ProductGroupId": 1,
 "ProductGroupName": "燃料",
 "TotalFuelQuantity": 1250.75,
      "總淨金額": 5420.50,
 "總毛金額": 6504.60,
 "發票貨幣代碼": "GBP",
 "發票貨幣符號": "£",
      "客戶零售淨額總計": 5420.50,
 "客戶零售毛額總計": 6504.60
    }
  ]
}

範例 4：取得定價摘要

請求：

 POST /transaction-data/v1/pricedsummary
 
 {
  "篩選條件": {
    "ColCoCode": 86,
    "付款人編號": "GB000000123",
    "卡片編號": 275549,
    "FromDate": "20240225",
    "ToDate": "20240225",
    "FuelOnly": false
  }
}

回應：

{
    "RequestId": "5f1bded6-416d-4478-ab7f-33905d7b5d4b",
    "Status": "SUCCESS",
    "Data": [
 {
 "CustomerRetailValueTotalGross": 114.13,
            "CustomerRetailValueTotalNet": 95.11,
 "InvoiceCurrencyCode": "EUR",
 "InvoiceCurrencySymbol": "€",
 "ProductCode": "21",
            "ProductGroupId": 3,
 "ProductGroupName": "汽油",
 "ProductId": 21,
 "ProductName": "無鉛 - 高辛烷值",
            "站點群組 ID": 104,
 "站點群組名稱": "奧地利預設殼牌加油站",
            "TotalFuelQuantity": 17.0,
 "TotalGrossAmount": 114.13,
 "TotalNetAmount": 95.11
 }
    ]
}

範例 5：取得多付款人定價交易

請求：

POST /transaction-data/v1/multipayerspricedtransactions

{
  "ColCoCode": 86,
  "Accounts": [
    {
 "PayerId": 12345,
 "PayerNumber": "GB987654322"
    },
    {
 "PayerId": 12346,
 "Payer號碼": "GB000000124"
    }
  ],
  "發票狀態": "A",
  "起始日期": "20220101",
  "截止日期": "20220131",
  "PageSize": 50,
  "Page": 1
}

回應：

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
      "交易記錄": [
 {
 "類型": "銷售明細"
 }
 ],
 "卡片編號": 275549,
      "CardPAN": "7002051006629891000",
 "CardExpiry": "20250812",
 "TransactionDate": "20250812",
 "TransactionTime": "14:30:45",
 "UTCOffset": "+01:00:00",
 "FleetIdInput": "XYZ1234",
      "里程表讀數輸入值": 12345,
 "駕駛員姓名": "ANDREW GILBERRY",
 "車輛牌照號碼": "MV65YLH",
 "發票貨幣代碼": "GBP",
      "發票貨幣符號": "£",
 "交易貨幣代碼": "GBP",
 "交易貨幣符號": "£",
 "交易淨額": 47.71,
 "交易稅額": 9.54,
 "交易總額": 57.25,
 "發票淨額": 47.71,
 "發票稅額": 9.54,
 "發票總額": 57.25,
 "採購國家": "德國",
 "帳戶編號": 29484,
 "帳戶號碼": "GB99215176",
 "帳戶名稱": "MATTHEW ALGIE & COMPANY LIMITED",
 "帳戶簡稱": "MATTHEW",
 "數量": 43.28,
 "FuelProduct": true,
 "UnitPriceInTransactionCurrency": 1.1074,
 "UnitPriceInInvoiceCurrency": 1.1024,
 "UnitDiscountTransactionCurrency": -0.005,
      "單價折扣（發票貨幣）": -0.0051,
 "已開立發票": true,
 "發票編號": "S04500493",
 "發票日期": "20250815 09:30:00",
 "據點代碼": "050001",
 "據點名稱": "CHARNOCK RICHARD NTHBOUND MWSA 0755",
 "據點國家": "德國",
 "位置": {
 "緯度": "53.83606",
 "經度": "-1.61854"
 },
 "卡片群組名稱": "006240 FIRE BRIGHT SOLUTIONS",
 "收據編號": "6803",
      "產品代碼": "10",
 "產品名稱": "無鉛汽油 - 高辛烷值",
 "產品群組 ID": 2,
 "產品群組名稱": "所有燃料",
 "DelCo 匯率": 0.851858,
      "ColCo匯率": 0.851858,
 "是否為殼牌站點": true,
 "網路": "SHELL",
 "站點群組ID": 202,
      "站點群組名稱": "CZ 9100 ECONOMY NETWORK",
 "發佈日期": "20250812 14:30:45",
      "發卡機構代碼": "7002",
 "購買國家代碼": "DE",
 "客戶國家代碼": "NL",
 "客戶國家": "荷蘭",
 "發行代碼": "8",
 "卡片群組 ID": "40000",
 "卡片序號": "617",
 "校驗位": "6",
      "車隊編號說明": "YG67OUM",
 "增值稅率": 0.2,
 "增值稅類別": "1-標準稅率",
      "淨金額之增值稅": 9.54,
 "增值稅國家": "荷蘭",
 "交易貨幣之有效折扣": -0.22,
      "交易類型": "購買",
 "PIN 指標": "已使用 PIN 碼",
 "適用增值稅": "是",
 "淨發票指標": "否",
 "客戶貨幣代碼": "GBP",
      "客戶貨幣符號": "£",
 "客戶貨幣單位折扣率": -0.0051,
 "客戶貨幣折扣率": -0.22,
 "客戶貨幣淨金額之增值稅": 9.54,
 "折扣類型": "每單位 2 便士",
 "交易狀態": "I",
      "銷售項目編號": 18315958002,
      "付款方群組": "H312066",
 "付款方群組名稱": "12119008 - 殼牌集團",
 "退款標記": "N",
      "原始銷售項目編號": null,
 "Delco名稱": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
 "Delco代碼": "014",
 "付款人號碼": "GB987654322",
 "付款人名稱": "V.M. LE COMTE",
 "卡片有效期": "2504",
 "授權碼": "011256",
      "交易編號": "io9KVXk1UkW57XWKyeaHHg",
 "交易行號": "1",
 "允許結算": "是",
 "CRM編號": null,
 "爭議狀態": "無爭議",
 "回扣率": 28.279,
      "發卡行至收卡行匯率": 1,
 "淨歐元金額": 56.01,
 "歐元增值稅金額": 11.2,
 "母客戶編號": "GB12121212",
 "母客戶名稱": "FUEL CARD SERVICES LTD",
 "母客戶編號": 6494,
 "入帳據點編號": "100021",
 "入帳據點描述": "HN3 INTI_02-82.02",
 "入帳貨幣代碼": "GBP",
 "入帳產品代碼": "30",
      "CreditDebitCode": "D",
 "CorrectionFlag": "N",
 "Additional1": "GBALLEGO0002452",
 "Additional2": null,
      "Additional3": null,
 "Additional4": null,
 "以客戶貨幣計算之淨金額回扣": -0.735,
 "以交易貨幣計算之淨金額回扣": -0.735,
 "TrnIdentifier": "H305908971030",
 "CardType": "GB STD FLT NAT SINGLE R9",
      "Delco 標價單位淨額": 30.5,
 "Delco 零售價單位淨額": 1.1074,
 "Delco 零售價單位總額": 1.32888,
 "Delco 零售總值淨額": 47.93,
 "DelcoRetailValueTotalGross": 57.52,
      "CustomerRetailPriceUnitGross": 1.32888,
 "CustomerRetailValueTotalNet": 47.93,
 "EVPrintedNumber": "3792",
 "IsRFID": true,
      "TokenTypeDescription": "車隊卡"
    }
  ],
  "Page": 1,
  "PageSize": 20,
  "TotalPages": 15,
  "TotalRecords": 300
}

範例 6：取得基於用量的定價規則

請求：

POST /transaction-data/v1/volumebasedpricing

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "IncludeHistory": true,
  "IncludeCurrentPeriodVolume": true
}

回應：

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Configuration": [
 {
 "PricingAccountId": 123456,
          "定價帳戶編號": "GB000000123",
 "定價帳戶簡稱": "ABCD1234",
 "定價帳戶全名": "ABCD1234",
 "費用規則 ID": 12345,
 "費用規則說明": "NL/GAGO/D018/UP0.0120>1",
 "費用規則生效日期": "20231223",
 "費用規則終止日期": "20231223",
 "BonusPaidTo": "1-支付給付款人",
 "BonusPaidToAccountId": 123456,
 "BonusPaidToAccountNumber": "GB000000123",
 "BonusPaidToAccountShortName": "12345",
 "BonusPaidToAccountFullName": "GB000000123",
 "Frequency": "3-每週 – 星期一",
 "NextCalculationDate": "20231223",
          "上次計算日期": "20231223",
 "費用規則基礎": "3-一次性付款",
 "費用規則貨幣代碼": "GBP",
          "費用規則貨幣符號": "£",
 "費用規則生效日期": "20231223",
 "費用規則失效日期": "20231223",
 "費用規則地點": [
            {
 "DelcoId": 866,
 "Country": "英國",
 "CountryCode": "UK",
 "FuelNetworkId": 100007,
 "NetworkName": "VALERO",
 "SiteGroupId": 100007,
 "SiteGroupName": "VALERO ENERGY LTD",
 "SiteCode": 999493,
 "站點識別碼": 100007,
 "站點名稱": "VALERO ENERGY LTD"
 }
 ],
 "收費規則產品": [
 {
 "產品群組 ID": 3,
 "產品群組名稱": "汽油",
 "產品代碼": "30（柴油 AGO）",
 "產品 ID": "30（柴油 AGO）",
 "產品名稱": "柴油 AGO"
            }
 ],
 "FeeRuleTiers": [
 {
 "TierMinimum": 1234,
 "TierMaximum": 1234,
 "Value": 1234.12
 }
 ]
 }
      ],
 "當期消耗量": [
 {
          "費用規則 ID": 12345,
 "費用規則說明": "NL/GAGO/D018/UP0.0120>1",
 "價格規則 ID": 100005,
 "價格規則說明": "PL/GAGO/GMOT/UL0.055",
 "總成交量": 10000.78,
 "下次手續費生成日期": "20231223"
 }
 ],
 "歷史紀錄": [
 {
 "起始日期": "20231223",
 "ToDate": "20231223",
 "FeesRuleID": 8081,
 "FeesRuleDescription": "PT/P067/D120/P4.0",
          "總交易量": 12356.66
 }
 ],
 "警告": [
 {
          "Message": "系統因升級而暫停服務。",
 "Type": "系統中斷"
 }
 ]
    }
  ]
}

範例 7：取得基於交易量的獎金規則

請求：

POST /transaction-data/v1/volumebasedbonus

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "IncludeHistory": true,
  "IncludeCurrentPeriodVolume": true
}

回應：

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "Configuration": [
 {
 "PricingAccountId": 123456,
 "PricingAccountNumber": "GB000000123",
 "PricingAccountShortName": "MATTHEW",
 "PricingAccountFullName": "MATTHEW",
          "費用規則 ID": 1,
 "費用規則說明": "NL/GAGO/D018/UP0.0120>1",
 "費用規則生效日期": "20231223",
          "費用規則終止日期": "20231223",
 "獎金支付對象": "1-支付給付款人",
 "獎金支付對象帳戶 ID": 123456,
 "獎金支付對象帳戶號碼": "GB000000123",
 "BonusPaidToAccountShortName": "12345",
 "BonusPaidToAccountFullName": "GB000000123",
 "Frequency": "3-每週 – 週一",
 "下次計算日期": "20231223",
 "上次計算日期": "20231223",
 "費用規則基礎": "3-一次性付款",
 "費用規則貨幣代碼": "GBP",
          "費用規則貨幣符號": "£",
 "費用規則生效日期": "20231223",
 "費用規則失效日期": "20231223",
 "費用規則地點": [
            {
 "DelcoId": 866,
 "Country": "英國",
 "CountryCode": "UK",
 "FuelNetworkId": 100007,
 "NetworkName": "VALERO",
              "站點群組 ID": 100007,
 "站點群組名稱": "VALERO ENERGY LTD",
 "站點代碼": 999493,
 "站點 ID": 100007,
 "站點名稱": "VALERO ENERGY LTD"
 }
 ],
 "收費規則產品": [
 {
 "產品群組 ID": 3,
              "產品群組名稱": "汽油",
 "產品代碼": "30（柴油 AGO）",
 "產品編號": "30（柴油 AGO）",
 "產品名稱": "柴油 AGO"
 }
 ],
 "費用規則級距": [
 {
 "級距下限": 1234,
 "級距上限": 1234,
 "數值": 1234.12
            }
 ],
 "AssociatedAccounts": [
 {
              "關聯帳戶 ID": 12345,
 "關聯帳戶號碼": "GB000000123",
 "關聯帳戶簡稱": "帳戶簡稱",
 "關聯帳戶全稱": "帳戶全稱"
 }
 ]
        }
 ],
 "當期用量": [
 {
 "費用規則編號": 12345,
 "費用規則說明": "NL/GAGO/D018/UP0.0120>1",
 "月份": 1,
 "年份": 2018,
 "總交易量": 10000.78
 }
 ],
      "HistoricalBonusPaid": [
 {
 "PayerId": 12345,
          "付款人編號": "GB000000123",
 "付款人簡稱": "Jorden",
 "付款人全名": "MATTHEW",
          "帳戶 ID": 123456,
 "帳戶號碼": "GB000000123",
 "帳戶簡稱": "SALT",
          "帳戶全名": "ABCD1234",
 "發票帳戶 ID": 12345,
 "發票帳戶號碼": "GB000000123",
 "發票帳戶簡稱": "DFE1234",
 "發票帳戶全名": "AZAD PVT LMT",
 "手續費規則 ID": 12345,
 "費用規則說明": "NL/GAGO/D018/UP0.0120>1",
 "起始日期": "20231223",
 "截止日期": "20231223",
          "BonusPaidTo": "5-支付給關聯客戶",
 "FeeItemId": 12345,
 "FeeRuleBasis": "2-溢價百分比",
 "FeeItemCurrencyCode": "GBP",
 "費用項目貨幣符號": "$",
 "按比例計算的交易量": 123.12,
 "總交易量": 123.12,
 "費用產品": "1562-Shell 柴油紅利」，
 「發票總金額」：123.12，
 「發票淨金額」: 123.12,
 "發票增值稅金額": 123.12,
 "費用是否已取消": true,
 "費用項目分級比例計算量": 123.12,
 "費用項目分級總量": 123.12,
 "分級最低量": 123,
 "分級費率": 123.12
 }
 ]
    }
  ],
  "Warnings": [
    {
 "Message": "系統正在進行升級，暫停服務。",
 "Type": "系統停機"
    }
  ]
}

範例 8：取得手續費摘要

請求：

POST /transaction-data/v1/feessummary

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "CardId": 275549,
  "InvoiceStatus": "I",
  "FromDate": "20240101",
  "ToDate": "20240131",
  "FeeTypeGroup": "卡片費用"
}

回應：

{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
 "FeeTypeGroup": "卡片費用",
 "FeeTypeId": 1,
 "FeeType": "卡片年費",
 "ProductId": 1234,
 "ProductCode": "FEE",
 "ProductName": "卡片費用",
 "TotalFeeAmount": 125.00,
      "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "£"
    }
  ]
}

範例 9：取得交易例外狀況

請求：

POST /transaction-data/v1/exceptions

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "付款人編號": "GB000000123",
  "交易起始日期": "20231223",
  "交易結束日期": "20240131",
  "金額": 100,
  "條件": 5,
  "OutputType": "Transaction"
}

回應：

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "CardsExceptions": [
 {
 "AccountId": 29484,
 "CardId": 1234,
 "PAN": "ABCD1234",
 "DriverName": "ANDREW GILBERRY",
 "VRN": "34235",
 "PayerId": 123455,
          "付款人編號": "GB000000123",
 "帳戶編號": "GB99215176",
 "帳戶簡稱": "MATTHEW",
 "付款人簡稱": "MATTHEW",
 "日期": 2,
 "週": 2,
 "月份": 5,
 "年份": 2017,
 "交易總數": 4,
 "銷售總項項目數": 4,
 "總數量": 261,
 "總金額": 100.21,
 "貨幣代碼": "GBP",
 "貨幣符號": "$"
 }
 ],
      "交易例外": [
 {
 "銷售項目 ID": 18315958002,
 "卡片 ID": 1234,
          "ProductId": 2,
 "TransactionGUID": "ABCD1234",
 "TransactionDate": "20231223",
          "CustomerInvoiceValueTotalGross": 123.12,
 "CardPAN": "7002051006629891000",
 "CardExpiry": "20311223 12:12:12",
 "交易時間": "12:12:12",
 "UTC 偏移量": "+12:12:12",
 "車隊編號 (輸入值)": "XYZ1234",
 "里程表讀數 (輸入值)": 1234,
          "DriverName": "SALT",
 "VehicleRegistration": "MV65YLH",
 "InvoiceCurrencyCode": "GBP",
 "InvoiceCurrencySymbol": "$",
          "交易貨幣代碼": "GBP",
          "交易貨幣符號": "£",
 "交易淨金額": 123.12,
 "交易稅額": 123.12,
 "交易總金額": 123.12,
          "發票淨額": 123.12,
 "發票稅額": 123.12,
 "發票總額": 123.1,
 "採購國家": "法國",
 "帳戶 ID": 1234,
 "帳戶號碼": "GB99215176",
 "帳戶名稱": "MATTHEW ALGIE & COMPANY LIMITED",
 "帳戶簡稱": "MATTHEW ALGIE & COMPANY LIMITED",
          "數量": 123.12,
 "燃料產品": true,
 "交易貨幣單價": 123.12,
 "發票貨幣單價": 123.12,
          "交易貨幣單位折扣": 123.12,
 "發票貨幣單位折扣": 123.12,
 "已開立發票": true,
 "發票編號": "S04500493",
          "發票日期": "20231223",
 "據點代碼": "50001",
 "據點名稱": "CHARNOCK RICHARD NTHBOUND MWSA 0755",
 "SiteCountry": "德國",
 "Location": {
 "Lat": "37.4224764",
 "Lng": "122.0842499"
          },
 "卡組名稱": "006240 FIRE BRIGHT SOLUTIONS",
 "收據編號": "1234",
 "產品代碼": "TMF 費用",
 "產品名稱": "無鉛汽油 - 高辛烷值",
          "產品群組 ID": 1234,
 "產品群組名稱": "父級產品群組",
 "DelCo 匯率": 123.12,
          "ColCoExchangeRate": 123.12,
 "IsShellSite": true,
 "Network": "Shell PH",
 "站點群組編號": 202,
 "站點群組名稱": "CZ 9100 ECONOMY NETWORK",
 "發佈日期": "20231223 12:12:12",
          "發卡機構代碼": "7077 = CRT",
 "購買國家代碼": "NL",
 "客戶國家代碼": "NL",
 "客戶國家": "荷蘭",
          "ReleaseCode": "8 for 702188",
 "CardGroupId": "200",
 "CardSequenceNumber": "2",
 "CheckDigit": "GHE1234",
 "車隊編號說明": "範例說明",
 "增值稅率": 0.2,
 "增值稅類別": "3-免增值稅",
 "增值稅淨金額": 12.21,
 "增值稅國家": "荷蘭",
          "有效交易貨幣折扣率": 0,
 "交易類型": "實體卡交易，否則留空",
 "PIN 指標": "是",
          "VATApplicable": "Y",
 "NetInvoiceIndicator": "Y",
 "CustomerCurrencyCode": "GBP",
 "CustomerCurrencySymbol": "£",
 "EffectiveUnitDiscountInCustomerCurrency": 123.12,
 "有效折扣（以客戶貨幣計）": 123.12,
 "淨金額之增值稅（以客戶貨幣計）": 123.12,
 "折扣類型": "3-百分比",
 "交易狀態": "U",
 "付款方群組": "12119008",
 "退款標記": "N",
 "原始銷售項目 ID": "1231",
 "Delco 名稱": "SHELL NEDERLAND VERKOOPMAATSCHAPPIJ BV",
 "DelcoCode": "NL10042616",
 "PayerName": "V.M. LE COMTE",
 "卡片有效期": "1901",
 "授權碼": "11256",
 "交易編號": "io9KVXk1UkW57XWKyeaHHg",
 "交易行號": "1",
          "允許結算": "Y",
 "CRM編號": "ABCD1234",
 "爭議狀態": "6\t退款至網站",
 "回扣率": 28.279,
          "發卡行至收單行匯率": 1,
 "淨歐元金額": 37.93,
 "歐元退款金額": 0,
 "歐元增值稅金額": 7.96,
          "ParentCustomerNumber": "DRG1234"
 }
      ]
    }
  ]
}

範例 10：取得卡片使用摘要

請求：

POST /transaction-data/v1/cardusagesummary

{
  "ColCoId": 1,
  "ColCoCode": 86,
  "PayerId": 12345,
  "PayerNumber": "GB000000123",
  "AccountId": 1234,
  "AccountNumber": "GB000000123",
  "CardId": 1234,
  "PAN": "7882861007636000020",
  "CardExpiry": "20311223"
}

回應：

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Data": [
    {
 "使用摘要": [
 {
 "日期": "20170930",
 "產品編號": 1,
 "產品代碼": "2",
 "ProductName": "柴油 AGO",
 "IsFuelProduct": true,
 "SiteGroupId": 1234,
 "SiteGroupName": "UK 9500 高速公路網絡",
 "總體積": 123.12,
 "總毛重": 123.12,
 "總淨重": 123.12,
 "CurrencyCode": "GBP",
 "CurrencySymbol": "£",
 "ProductGroupId": 1234,
 "ProductGroupName": "機動車汽油"
 }
 ]
    }
  ]
}

錯誤處理

常見錯誤代碼

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

最佳實務

1. 採用 OAuth 2.0 驗證

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

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

2. 使用請求 ID

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

3. 實作分頁

對於大型交易資料集，請使用分頁以避免超時：

設定適當的 PageSize（建議：50-100 筆記錄）
依序或並行處理頁面
處理回應中的 TotalPages 與 TotalRecords

4. 謹慎使用日期篩選器

查詢交易資料時：

限制日期範圍以避免結果集過大
一致地使用 FromDate 和 ToDate 篩選條件
為提升效能，請考慮按月或按週進行查詢

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

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

6. 快取參考資料

快取基於用量的定價與獎勵規則，以減少 API 呼叫次數：

這些規則很少變更
請定期（例如每日）刷新快取
僅在需要時使用 IncludeHistory 參數

SDK 與程式碼範例

Shell 提供官方 SDK 及詳盡的程式碼範例，以加速您與交易資料 API 的整合。

可用的 SDK 語言

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

查看官方 SDK 與文件

支援與資源

技術支援

支援： Shell 技術支援
OAuth 2.0 遷移： OAuth 2.0 遷移支援

文件

取得協助

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

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

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

選擇語言

Shell 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：燃油消耗分析與報告

用例 5：異常監控與詐欺偵測

用例 6：費用與收費分析

用例 7：個別卡片支出 追蹤

用例 8：基於用量的定價資格檢查

用例 9：獎金與回饋追蹤

使用範例

範例 1：取得已定價交易（包含 EV）

請求：

回應：

範例 2：取得燃料交易明細

請求：

回應：

範例 3：取得已定價交易摘要

請求：

回應：

範例 4：取得定價摘要

請求：

回應：

範例 5：取得多付款人定價交易

請求：

回應：

範例 6：取得基於用量的定價規則

請求：

回應：

範例 7：取得基於交易量的獎金規則

請求：

回應：

範例 8：取得手續費摘要

請求：

回應：

範例 9：取得交易例外狀況

請求：

回應：

範例 10：取得卡片使用摘要

請求：

回應：

錯誤處理

常見錯誤代碼

最佳實務

1. 採用 OAuth 2.0 驗證

2. 使用請求 ID

3. 實作分頁

4. 謹慎使用日期篩選器

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

6. 快取參考資料

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

用例 7：個別卡片支出追蹤