壳牌 B2B 出行卡管理 API - 快速入门指南

API 版本： 3.1.5 | 身份验证： OAuth 2.0 | 状态： 生产环境

概述

壳牌卡片管理 API 是一个基于 REST 的 API，允许开发者通过编程方式管理壳牌加油卡。该 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 的迁移
旧版方法： 基本认证和 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/test/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": {
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"CardStatus": ["ACTIVE"]
},
"Page": "1",
"PageSize": "50"
}'

响应示例：

{
"RequestId": "233e4567-e89b-12d3-a456-426614174000",
"Status": "SUCCESS",
"Data": [
{
"CardId": 125,
"PAN": "7002861007636000020",
"MaskedPAN": "7002861**000020",
"DriverName": "ROBERT SMITH",
"VehicleRegistrationNumber": "MV65YLH",
"StatusDescription": "Active",
"ExpiryDate": "20250531",
"CardTypeCode": "7077861",
"CardTypeName": "壳牌卡"
}
],
"Page": 1,
"PageSize": 50,
"TotalPages": 1,
"TotalRecords": 1
}

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 （收款公司代码）
付款人编号或付款人ID
账户号
卡类型和配置
送货地址详情

卡片状态管理

端点	方法	描述
/card-management/v1/updatestatus	POST	冻结、解冻或注销卡片（OAuth 2.0）
/card-management/v1/schedulecardblock	POST	安排卡片冻结/解冻请求（OAuth 2.0）

状态操作：

锁定 - 暂时锁定卡片
解锁 - 重新激活已被冻结的卡片
卡片损坏 - 报告卡片损坏并申请补发
TEMP_BLOCK_CUSTOMER - 由客户发起的临时冻结
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
{
"Filters": {
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"CardStatus": ["ACTIVE"],
"ExpiringInDays": 30
},
"Page": "1",
"PageSize": "100"
}

示例 2：临时冻结卡片

POST /card-management/v1/updatestatus
{
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"Cards": [
{
"CardId": 125,
"Action": "TEMP_BLOCK_CUSTOMER",
"Reason": "卡片暂时遗失"
}
]
}

示例 3：注销卡片

POST /card-management/v1/cancel
{
"ColCoCode": 86,
"PayerNumber": "PH50000843",
"Cards": [
{
"CardId": 125,
"CardExpiryDate": "20231231"
}
],
"ReasonText": "丢失",
"RequestId": "1"
}

错误处理

常见错误代码

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. 实现分页

对于大型数据集，请使用分页以避免超时

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 技术支持

文档

服务条款
API 参考

获取帮助

联系支持时，请提供：

您的 client_id（切勿透露您的 client_secret 或访问令牌）
API 响应中的 RequestId
请求的时间戳
环境（生产/测试）

最后更新时间： 2026年6月15日
文档版本： 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：获取访问令牌