殼牌 B2B 移動服務過路費交易資料 API - 快速入門指南

API 版本： 1.0.0 | 驗證方式： OAuth 2.0 | 狀態： 正式上線

概述

Shell B2B 移動服務過路費交易資料 API 是一項基於 REST 的 API，為 Shell 移動服務客戶提供對過路費交易記錄及相關資料的全面存取權限。此 API 讓開發人員能夠透過程式化方式擷取、篩選及分析過路費交易資料，以進行帳戶對帳、帳單驗證、費用管理及合規要求等用途。

主要功能

依帳號擷取通行費交易資料
依日期範圍篩選交易（起始與結束日期）
依發票狀態及 VRN（車輛登記號碼）搜尋
多欄位進階排序功能
支援大型資料集的分頁功能
靈活的欄位篩選功能，以優化回應載荷
包含進出點在內的全面性收費詳情
支援多個收費網路和營運商

驗證

OAuth 2.0 （標準驗證方法）

Shell 收費交易資料 API 使用 OAuth 2.0 客戶端憑證流程 進行安全驗證。

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
RequestId: eb621f45-a543-4d9a-a934-2f223b263c42

存取權杖管理

存取權杖管理最佳實務：

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

環境

此 API 提供兩種環境：

環境	基礎 URL	用途
正式環境	https://api.shell.com/toll-data/v1	正式生產環境
測試 (UAT)	https://api-test.shell.com/toll-data/v1	測試與開發環境

OAuth 憑證 URL：

環境	憑證 URL
生產環境	https://api.shell.com/v2/oauth/token
測試 (UAT)	https://api-test.shell.com/v2/oauth/token

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

快速入門

1. 取得您的 OAuth 憑證

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=您的-client-id&client_secret=您的-client-secret"

回應：

{
  "access_token": "eyJhbGciOi*******5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 899
}

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

範例：搜尋過路費交易

cURL 範例：

curl -X POST https://api-test.shell.com/toll-data/v1/transactions/search \
  -H "Authorization: Bearer eyJhbGci******NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -H "RequestId: eb621f45-a543-4d9a-a934-2f223b263c42" \
  -d '{
    "篩選條件": {
 "ColCoCode": 86,
 "PayerNumber": "NL20016398",
        "AccountNumber": "NL20027701",
 "Filter": "All",
 "FromDate": "2026-01-01",
 "ToDate": "2026-01-31"
    },
    "Page": 1,
    "每頁筆數": 10
}'

回應範例：

{
  "請求編號": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Page": 1,
  "TotalRecords": 150,
  "TotalPages": 15,
  "PageSize": 10,
  "Data": [
    {
 "NetworkDescription": "Societa Autostradali",
 "TollChargerCode": "410|610",
      "DelcoCode": "714",
 "DelcoName": "Shell Fleet Solutions Consorzio",
 "NetworkCode": "TLI",
 "Network": "euroShell Consortio",
 "PurchasedInCountry": "Italy",
      "購買國家代碼": "IT",
 "卡號": "707737*******334272",
      "卡片識別碼": 123456789,
 "卡片群組名稱": "Shell Fleet Solutions Consorzio",
 "車輛登記號碼": "KN 00000",
      "成本中心": "100",
 "系統錄入日期": "20260123",
 "系統錄入時間": "13:14:25",
 "交易日期": "20260120",
      "交易時間": "10:30:00",
 "過帳日期": "20260123",
 "過帳時間": "00:00:00",
 "付款人編號": "NL20016398",
 "帳戶號碼": "NL20027701",
 "帳戶名稱": "測試帳戶名稱",
 "起始日期": "20260120",
      "開始時間": "06:47:41",
 "結束日期": "20260120",
 "結束時間": "07:30:15",
 "收費站入口": "ROMA NORD",
      "收費站出口": "BRENNERO",
 "行駛距離": "71.6",
 "路線描述": "ROMA NORD - BRENNERO",
 "交易類型": "道路稅",
 "產品代碼": "14",
      "產品描述": "道路稅",
 "交易淨金額": "127.1",
 "交易稅額": "0.0",
 "交易總金額": "127.1",
      "交易貨幣代碼": "EUR",
 "交易狀態": "報表中",
 "發票編號": "8600397548",
 "發票日期": "20260125",
      "發票狀態": "已開立發票",
 "付款方式": "後付",
 "OBU 序號": "00049000000836932426",
 "排放標準": "歐盟 6 期",
      "合約編號": "fb75eb53-46eb-450b-862e-6045002c3fa8",
      "ShellTransactionID": "04176c5c-e7b2-49c8-bcb3-23d07ba583f2",
 "TollOperator": "Toll4Europe",
 "TollDomain": "Toll4Europe",
      "費率相關資訊": "車輛類別：2，軸數：2，道路類別：高速公路",
 "附加交易資訊": "位置：1",
 "TC發票編號": "12343343",
      "TCInvoiceDate": "20260123"
    }
  ]
}

API 端點參考

通行費交易

端點	方法	說明
/toll-data/v1/transactions/search	POST	透過彈性篩選與分頁功能擷取收費交易資料

常見使用情境：

依日期範圍擷取收費交易紀錄
依發票狀態篩選（已開立發票、未開立發票、全部)
依車輛登記號碼 (VRN) 搜尋
依卡片群組篩選
依多項條件排序交易紀錄
選取特定欄位以優化回應大小

常見使用案例

本節將常見的商業情境與 API 使用模式對應起來，協助您快速了解如何根據特定需求使用 API。

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

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

建議使用的 API： /toll-data/v1/transactions/search

為何選擇此 API： 此端點提供詳盡的收費交易明細，具備靈活的日期篩選功能，同時支援已開立發票與未開立發票的交易，並針對大型資料集提供分頁功能。非常適合用於每日對帳工作流程。

關鍵參數：

FromDate 與 ToDate — 進行每日對帳時，請設定為昨日的日期
Search.InvoiceStatus — 選擇「全部」以同時包含已開立發票與未開立發票的交易
PageSize — 設定為 100 以提升資料擷取效率
篩選 - 選擇「全部」以取得完整的交易明細

用例 2：發票驗證與核對

情境： 您收到一張發票，需要核對所有過路費交易明細及費用。

建議使用的 API： /toll-data/v1/transactions/search

為何選擇此 API： 此 API 提供詳細的收費交易資訊，包括發票編號、日期、金額及收費網路詳情。由於其結構與發票格式相符，非常適合用於發票驗證。

關鍵參數：

Search.發票狀態 — 設定為「已開立發票」以僅擷取已開立發票的交易
起始日期 與 結束日期 - 設定為發票週期日期
篩選 - 指定「發票編號、發票日期、交易總金額」等欄位，進行針對性驗證

用例 3：車隊車輛過路費使用分析

情境： 您需要分析車隊中特定車輛的過路費使用模式，以優化路線並降低過路費成本.

推薦 API： /toll-data/v1/transactions/search

為何選擇此 API： 此 API 允許根據車輛登記號碼（VRN）進行篩選，並提供包含進出點、行駛距離及過路費等詳細路線資訊，非常適合進行車輛層級的分析。

關鍵參數：

Search.車輛登記號碼 — 指定要分析的 VRN
起始日期 及 至日期 — 設定為分析期間（例如：過去 30 天）
排序選項 — 若要進行時間順序分析，請設定為 1（按交易日期升序）
篩選條件 - 包含「RouteDescription、DistanceDriven、TollGateEntry、TollGateExit、TransactionGrossAmount」等欄位

用例 4：卡組費用追蹤

情境： 您管理多個卡組，並需要按卡組追蹤過路費支出，以進行預算分配及成本中心報表編製。

建議使用的 API： /toll-data/v1/transactions/search

為何選擇此 API： 此 API 支援依卡組篩選，並包含成本中心資訊，非常適合用於卡組層級的費用追蹤與報表編製。

關鍵參數：

Search.CardGroup - 指定卡組名稱，或使用「All」以涵蓋所有卡組
FromDate 與 ToDate — 設定為報表期間
篩選條件 — 包含「CardGroupName、成本中心、交易總金額、交易淨金額、交易稅額"
排序選項 - 為進行費用分析，請選取 3（按交易金額升序排序）

用例 5：多帳戶通行費報表

情境： 您管理多個帳戶，並需要針對所有帳戶彙總生成合併通行費報表。

建議使用的 API： /toll-data/v1/transactions/search

為何選用此 API： 此 API 支援在單次請求中查詢多個帳戶（建議 2 至 5 個），可減少 API 呼叫次數，並提升多帳戶情境下的效能。

關鍵參數：

AccountNumber - 提供以逗號分隔的帳戶號碼（為獲得最佳效能，建議最多 2 至 5 個）
FromDate 與 ToDate — 設定為報表期間
PageSize - 為獲得更佳效能，請使用較大的頁大小（例如 100-500）以獲得更佳效能

用例 6：未開立發票交易監控

情境： 您希望監控未開立發票的通行費交易，以預測即將開立的發票並管理現金流。

建議使用的 API： /toll-data/v1/transactions/search

為何選用此 API： 此 API 支援依發票狀態篩選，便於識別尚未開立發票的交易，並預估即將產生的費用。

關鍵參數：

Search.InvoiceStatus — 設定為「未開立發票」以篩選待計費項目
FromDate 與 ToDate — 設定為當前計費週期
篩選條件 — 包含「交易日期、交易總金額、帳號、車輛登記號碼」

用例 7：收費網路使用分析

情境： 您需要分析車隊最常使用的收費網路及營運商，以便協商更優惠的費率或優化路線。

推薦 API： /toll-data/v1/transactions/search

為何選擇此 API： 此 API 提供詳細的收費網路資訊，包括網路描述、收費營運商、收費點代碼及網路代碼，非常適合用於網路使用分析。

關鍵參數：

FromDate 及 ToDate — 設定為分析期間（例如：每季）
篩選條件 - 包含「NetworkDescription、TollOperator、TollChargerCode、Network、TransactionGrossAmount」
每頁資料量 - 若需全面擷取資料，請使用較大的頁碼大小

使用範例

範例 1：依帳戶與日期範圍搜尋過路費交易

請求：

POST /toll-data/v1/transactions/search

{
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "NL20016398",
    "AccountNumber": "NL20027701",
    "Filter": "All",
    "FromDate": "2026-01-01",
    "ToDate": "2026-01-31"
  },
  "Page": 1,
  "PageSize": 10
}

回應：

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Page": 1,
  "TotalRecords": 150,
  "TotalPages": 15,
  "PageSize": 10,
  "Data": [
    {
      "NetworkDescription": "Societa Autostradali",
 "TollChargerCode": "410|610",
 "DelcoCode": "714",
 "DelcoName": "Shell Fleet Solutions Consorzio",
      "NetworkCode": "TLI",
 "Network": "euroShell Consortio",
 "PurchasedInCountry": "Italy",
 "PurchasedInCountryCode": "IT",
      "CardNumber": "707737*******334272",
 "CardId": 123456789,
 "CardGroupName": "Shell Fleet Solutions Consorzio",
      "車輛登記號碼": "KN 00000",
 "成本中心": "100",
 "系統錄入日期": "20260123",
 "系統錄入時間": "13:14:25",
      "交易日期": "20260120",
 "交易時間": "10:30:00",
 "過帳日期": "20260123",
 "過帳時間": "00:00:00",
 "付款人編號": "NL20016398",
 "帳戶編號": "NL20027701",
 "帳戶名稱": "測試帳戶名稱",
 "開始日期": "20260120",
 "StartTime": "06:47:41",
 "EndDate": "20260120",
      "結束時間": "07:30:15",
 "收費站入口": "ROMA NORD",
 "收費站出口": "BRENNERO",
      "行駛距離": "71.6",
 "路線描述": "羅馬北站 - 布倫納站",
 "交易類型": "道路稅",
 "產品代碼": "14",
      "產品描述": "道路稅",
 "交易淨金額": "127.1",
 "交易稅額": "0.0",
 "交易總金額": "127.1",
      "交易貨幣代碼": "EUR",
 "交易狀態": "報表中",
 "發票編號": "8600397548",
 "發票日期": "20260125",
      "發票狀態": "已開立發票",
 "付款方式": "後付",
      "OBU 序列號": "00049000000836932426",
 "排放標準": "歐盟 6 期",
 "合約 ID": "fb75eb53-46eb-450b-862e-6045002c3fa8",
 "ShellTransactionID": "04176c5c-e7b2-49c8-bcb3-23d07ba583f2",
 "收費營運商": "Toll4Europe",
      "收費區域": "Toll4Europe",
 "費率相關資訊": "車輛類別：2，軸數：2，道路類別：高速公路",
      "AdditionalTransactionInfo": "位置：1",
 "TCInvoiceNumber": "12343343",
 "TCInvoiceDate": "20260123"
    }
  ]
}

範例 2：依車輛登記號碼 (VRN) 篩選交易紀錄

請求：

POST /toll-data/v1/transactions/search

{
  "篩選條件": {
    "ColCoCode": 86,
    "付款人編號": "NL20016398",
    "帳號": "NL20027701",
    "Filter": "VehicleRegistration, RouteDescription, TransactionGrossAmount, TransactionDate",
    "FromDate": "2026-01-01",
    "ToDate": "2026-03-31",
    "Search": {
 "VehicleRegistrationNumber": "KN 00000",
      "發票狀態": "全部"
    }
  },
  "頁碼": 1,
  "每頁筆數": 50
}

回應：

{
  "請求編號": "9d2dee33-7803-485a-a2b1-2c7538e597ee",
  "Status": "SUCCESS",
  "Page": 1,
  "TotalRecords": 45,
  "TotalPages": 1,
  "PageSize": 50,
  "Data": [
    {
 "VehicleRegistration": "KN 00000",
 "RouteDescription": "羅馬北 - 布倫納",
      "交易總金額": "127.1",
 "交易日期": "20260120"
    },
    {
 "車輛登記號碼": "KN 00000",
 "路線描述": "米蘭東站 - 維羅納南站",
 "交易總金額": "85.4",
      "交易日期": "20260125"
    }
  ]
}

範例 3：依卡片群組搜尋

請求：

POST /toll-data/v1/transactions/search

{
  "篩選條件": {
    "ColCoCode": 86,
    "付款人編號": "NL20016398",
    "帳號": "NL20027701",
    "篩選條件": "CardGroupName, VehicleRegistration, TransactionGrossAmount, TransactionDate",
    "FromDate": "2026-01-01",
    "ToDate": "2026-01-31",
    "Search": {
 "CardGroup": "Shell Fleet Solutions Consorzio",
 "InvoiceStatus": "All"
    }
  },
  "Page": 1,
  "PageSize": 30
}

回應：

{
  "RequestId": "5f1bded6-416d-4478-ab7f-33905d7b5d4b",
  "Status": "SUCCESS",
  "Page": 1,
  "TotalRecords": 87,
  "TotalPages": 3,
  "PageSize": 30,
  "Data": [
    {
 "CardGroupName": "Shell Fleet Solutions Consorzio",
      "車輛登記號碼": "KN 00000",
 "交易總金額": "127.1",
 "交易日期": "20260120"
    },
    {
      "CardGroupName": "Shell Fleet Solutions Consorzio",
 "VehicleRegistration": "LM 11111",
 "TransactionGrossAmount": "95.8",
 "TransactionDate": "20260122"
    }
  ]
}

範例 4：包含特定欄位的多個帳戶

請求：

POST /toll-data/v1/transactions/search

{
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "NL20016398",
    "AccountNumber": "NL20027701, NL20027702",
    "Filter": "AccountNumber, AccountName, TransactionDate, TransactionGrossAmount, VehicleRegistration",
    "FromDate": "2026-01-01",
    "ToDate": "2026-01-31"
  },
  "Page": 1,
  "PageSize": 100
}

回應：

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Page": 1,
  "TotalRecords": 245,
  "TotalPages": 3,
  "PageSize": 100,
  "Data": [
    {
 "AccountNumber": "NL20027701",
 "AccountName": "測試帳戶名稱",
      "交易日期": "20260120",
 "交易總金額": "127.1",
 "車輛登記號碼": "KN 00000"
    },
    {
 "帳戶號碼": "NL20027702",
      "帳戶名稱": "第二個帳戶名稱",
 "交易日期": "20260121",
 "交易總金額": "98.5",
 "車輛登記號碼": "PQ 22222"
    }
  ]
}

錯誤處理

常見錯誤代碼

HTTP 狀態碼	錯誤代碼	說明	解決方案
200	不適用	狀態：成功	不適用
400	E0001	驗證錯誤	檢查請求參數，確保已提供所有必填欄位且內容有效
401	E0003	未經授權	確認 OAuth 憑證有效且未過期
404	E0005	未找到	確認端點 URL 及資源是否存在
500	E0002	未知錯誤 / 內部伺服器錯誤	請提供 RequestId 並聯絡技術支援
503	E0012	服務不可用 / 連線錯誤	請稍後重試；若問題持續，請聯絡技術支援

錯誤回應範例

驗證錯誤 (E0001)：

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "FAILED",
  "Errors": [
    {
 "Code": "E0001",
 "Title": "驗證錯誤",
 "Detail": "以下欄位值缺失或無效：ColCoCode",
 "AdditionalInfo": null
    }
  ]
}

未授權錯誤 (E0003)：

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "FAILED",
  "Errors": [
    {
 "Code": "E0003",
 "Title": "未經授權",
 "Detail": "提供的憑證無效，或使用者無權執行此操作",
 "AdditionalInfo": null
    }
  ]
}

最佳實務

1. 使用 OAuth 2.0 驗證

重要： 請務必使用 OAuth 2.0 驗證。實施適當的憑證管理：

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

2. 務必包含 RequestId

請務必在標頭中包含唯一的 RequestId（UUID 格式），以確保端對端的可追溯性。這對於故障排除和技術支援至關重要。

3. 實作錯誤處理機制

實作穩健的錯誤處理機制：

檢查每個回應中的「Status」欄位
記錄 RequestId 以利疑難排解
針對暫時性錯誤 (503) 實作重試邏輯
透過檢查輸入參數來處理驗證錯誤 (E0001)

支援與資源

技術支援

支援服務： Shell 技術支援
電子郵件： api@shell.com

文件

API 入口網站

尋求協助

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

您的 client_id（切勿分享您的 client_secret 或存取憑證）
API 回應中的 RequestId
請求的時間戳記
環境（生產／測試）
收到的錯誤代碼與訊息

最後更新日期： 2026 年 8 月 4 日
文件版本： 1.0
API 版本： 1.0.0

選擇語言

殼牌 B2B 移動服務過路費交易資料 API - 快速入門指南

概述

主要功能

驗證

OAuth 2.0 （標準驗證方法）

OAuth 2.0 流程

步驟 1：取得存取憑證

步驟 2：在 API 請求中使用存取令牌

存取權杖管理

環境

快速入門

1. 取得您的 OAuth 憑證

2. 取得存取憑證

cURL 範例：

回應：

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

cURL 範例：

回應範例：

API 端點參考

通行費交易

常見使用案例

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

用例 2：發票驗證與核對

用例 3：車隊車輛過路費使用分析

用例 4：卡組費用追蹤

用例 5：多帳戶通行費 報表

用例 6：未開立發票交易監控

用例 7：收費網路使用分析

使用範例

範例 1：依帳戶與日期範圍搜尋過路費交易

請求：

回應：

範例 2：依車輛登記號碼 (VRN) 篩選交易紀錄

請求：

回應：

範例 3：依卡片群組搜尋

請求：

回應：

範例 4：包含特定欄位的多個帳戶

請求：

回應：

錯誤處理

常見錯誤代碼

錯誤回應範例

驗證錯誤 (E0001)：

未授權錯誤 (E0003)：

最佳實務

1. 使用 OAuth 2.0 驗證

2. 務必包含 RequestId

3. 實作錯誤處理機制

支援與資源

技術支援

文件

尋求協助

關於我們

聯絡人

登入您的帳戶

用例 5：多帳戶通行費報表