b2c-custom-api-development

自定义 API 开发技能

此技能将指导你为 Salesforce B2C Commerce 开发自定义 API。自定义 API 可让你将自定义脚本代码作为 SCAPI 框架下的 REST 端点公开。

**提示：**如果未全局安装 b2c CLI，请改用 npx @salesforce/b2c-cli（例如，npx @salesforce/b2c-cli code deploy）。

范围与依据

此技能提供针对 CLI 的工作流和自定义 API 开发快速入门模式。它涵盖 OpenAPI 3.0 契约结构、OAuth 作用域配置、cartridge 路径解析规则以及断路器行为。不过，平台特定的验证规则、操作限制、安全方案要求和 Script API 集成模式可能会随着 Commerce Cloud 版本的更新而变化。回答涉及特定 API 版本或框架行为的问题，或生成用户将要运行的代码之前，请通过 b2c docs search / b2c docs read（CLI）或 docs_search / docs_read（MCP）确认当前的平台具体信息。官方文档是自定义 API 契约规范、运行时行为以及此处未涵盖的 B2C Commerce 平台细节的权威来源。

权威文档（请通过以下文档确认平台具体信息）：

• commerce-api/custom-apis - 概述、cartridge 解析、操作限制
• commerce-api/custom-api-components-references - schema.yaml 和 script.js 要求
• commerce-api/custom-api-authentication - OAuth 作用域规则、安全方案
• commerce-api/custom-api-caching - 缓存行为和配置
• commerce-api/custom-api-remote-includes - 远程包含模式
• commerce-api/custom-api-circuit-breaker - 当前阈值和行为
• commerce-api/custom-api-troubleshooting - 常见问题和解决方案
• commerce-api/custom-api-status-report - 注册状态详情
• dw.system.RESTResponseMgr - Script API 响应管理器
• dw.system.Request - Script API 请求对象
• dw.system.RESTErrorResponse - Script API 错误响应
• dw.system.RESTSuccessResponse - Script API 成功响应

概述

自定义 API URL 的结构如下：

https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/{apiVersion}/organizations/{organizationId}/{endpointPath}

创建自定义 API 需要以下三个组成部分：

1. API 契约 - OAS 3.0 schema 文件（YAML）
2. API 实现 - 使用 B2C Commerce Script API 的脚本
3. API 映射 - 将端点绑定到实现的 api.json 文件

Cartridge 结构

/my-cartridge
    /cartridge
        package.json
        /rest-apis
            /my-api-name              # API name (lowercase alphanumeric and hyphens only)
                api.json              # Mapping file
                schema.yaml           # OAS 3.0 contract
                script.js             # Implementation

**重要：**API 目录名称只能包含小写字母数字字符和连字符。

组件 1：API 契约（schema.yaml）

最小示例，仅供说明；请通过 b2c docs read commerce-api/custom-api-components-references 和 b2c docs read commerce-api/custom-apis 确认当前的 schema 验证规则、安全方案结构和作用域命名要求。

最小示例：

openapi: 3.0.0
info:
  version: 1.0.0
  title: My Custom API
components:
  securitySchemes:
    ShopperToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
          scopes:
            c_my_scope: My custom scope
  parameters:
    siteId:
      name: siteId
      in: query
      required: true
      schema:
        type: string
        minLength: 1
paths:
  /my-endpoint:
    get:
      operationId: getMyData
      parameters:
        - $ref: '#/components/parameters/siteId'
      responses:
        '200':
          description: Success
security:
  - ShopperToken: ['c_my_scope']

关键要求：

• Shopper API 使用 ShopperToken（需要 siteId），Admin API 使用 AmOAuth2
• 自定义作用域必须以 c_ 开头，最多 25 个字符
• 自定义参数必须带有 c_ 前缀

Cartridge 路径要求（平台查找 rest-apis/ 文件夹的位置）

仅用于说明平台的 cartridge 解析规则；请通过 b2c docs read commerce-api/custom-apis 确认当前运行时行为和站点上下文处理方式。

调用形式	搜索的 Cartridge 路径
Shopper API（ShopperToken）——始终限定站点	店铺站点的 cartridge 路径（即签发 SLAS 令牌的站点）
Admin API（AmOAuth2），带有 siteId=<storefront-site>	该店铺站点的 cartridge 路径
Admin API（AmOAuth2），带有 siteId=Sites-Site（特殊的 BM/组织站点）	Business Manager cartridge 路径
Admin API（AmOAuth2），省略 siteId	Business Manager cartridge 路径

Admin API 可以在站点或组织上下文中调用——siteId 参数是可选的，其中一个特殊值可显式指定组织上下文：

• 传入真实的店铺站点 ID（例如 siteId=RefArch）会在该站点的上下文中运行调用，并通过该站点的 cartridge 路径解析 cartridge。
• 传入 siteId=Sites-Site 是针对 Business Manager / 组织站点调用 Admin API 的字面方式。Sites-Site 并非真实的店铺站点，而是代表 BM/组织级操作的系统定义站点。平台会通过 BM cartridge 路径解析 cartridge。
• 完全省略 siteId 等同于组织上下文，也会通过 BM cartridge 路径解析。

BM cartridge 路径是最容易踩坑的地方：如果你的 Admin API 用于组织级操作（使用 siteId=Sites-Site 或省略 siteId 调用），包含 rest-apis/ 的 cartridge 必须位于 BM cartridge 路径中。常见症状包括“使用店铺 siteId 调用时可以正常注册，但在组织上下文中返回 404”，或在组织上下文的 b2c scapi custom status 中始终看不到它。

使用 CLI 管理 cartridge 路径（无需在 BM 中点击）：

# Inspect the current BM cartridge path
b2c sites cartridges list --bm

# Add a cartridge to BM for org-context Admin APIs
b2c sites cartridges add my_admin_api_cartridge --bm --position first

# Add a cartridge to a storefront site (for Shopper APIs or site-scoped Admin APIs)
b2c sites cartridges add my_api_cartridge --site-id RefArch --position first

更新任何 cartridge 路径后，请重新激活代码版本（b2c code deploy --reload 或 b2c code activate <version>），以便平台重新注册端点。

若要在 Business Manager 中手动设置 BM cartridge 路径：Administration > Sites > Manage Sites > Business Manager（页眉中的链接）> Settings > Cartridges。

完整的架构示例以及 Shopper API 和 Admin API 的差异，请参阅 契约参考。

组件 2：实现（script.js）

仅用于说明 Script API 的用法；请通过 b2c docs read commerce-api/custom-api-components-references 以及 dw.system.RESTResponseMgr / dw.system.Request 的 Script API 文档，确认当前的 Custom API 集成模式、RESTResponseMgr 要求和请求对象方法。

var RESTResponseMgr = require('dw/system/RESTResponseMgr');

exports.getMyData = function() {
    var myParam = request.getHttpParameterMap().get('c_my_param').getStringValue();
    var result = { data: 'my data', param: myParam };
    RESTResponseMgr.createSuccess(result).render();
};
exports.getMyData.public = true;  // Required

关键要求：

• 为导出的函数标记 .public = true
• 使用 RESTResponseMgr.createSuccess() 返回响应
• 使用 RESTResponseMgr.createError() 返回错误响应（RFC 9457 格式）

有关缓存、远程 includes 和外部服务调用，请参阅 实现参考。

组件 3：映射（api.json）

{
  "endpoints": [
    {
      "endpoint": "getMyData",
      "schema": "schema.yaml",
      "implementation": "script"
    }
  ]
}

**重要提示：**实现名称不得包含文件扩展名。

开发工作流

1. 按照 rest-apis/{api-name}/ 结构创建 cartridge
2. 定义契约（schema.yaml），包含端点和安全设置
3. 编写逻辑（script.js），并导出函数
4. 创建映射（api.json），将端点绑定到实现
5. 部署并激活代码版本（--reload）以注册端点——首次注册以及任何契约（schema.yaml / api.json）变更时都必须执行
6. 检查注册状态并进行测试
7. 对于已注册端点后续的 script.js 修改，无需使用 --reload 即可重新部署——仅实现内容变更时无需重新激活

部署

# Deploy and activate to (re-)register endpoints
b2c code deploy ./my-cartridge --reload

# Deploy without re-activation (fine for implementation-only edits to already-registered endpoints)
b2c code deploy ./my-cartridge

# Check registration status
b2c scapi custom status --tenant-id zzpq_013

# Show failed registrations with error reasons
b2c scapi custom status --tenant-id zzpq_013 --status not_registered --columns apiName,endpointPath,errorReason

需要重新激活代码版本时（--reload）

自定义 API 端点注册会在代码版本激活时重建，而不是在每次上传文件时重建。这意味着：

更改	是否需要重新激活？
新端点、新 API 或首次注册	是
编辑 schema.yaml（路径、参数、安全设置、作用域、请求/响应结构）	是
编辑 api.json（端点 → 实现的映射）	是
在站点或 BM cartridge 路径中添加/移除 cartridge	是
编辑 script.js（或任何实现/库代码），用于已注册的端点	否 — 新代码会实时生效；直接部署，无需使用 --reload

因此，在常规迭代已注册端点的实现时，可以反复部署，无需承担重新激活的开销。只有在契约发生变化，或端点尚未注册时，才需要使用 --reload（或 b2c code activate <version>）。

身份验证设置

对于 Shopper API

1. 使用自定义作用域创建 SLAS 客户端：

   b2c slas client create --default-scopes --scopes "c_my_scope"
   

2. 通过 SLAS 客户端凭据获取令牌
3. 在所有请求中包含 siteId

对于 Admin API

1. 在 Account Manager API Client（角色：“Salesforce Commerce API”）上配置自定义作用域（c_my_admin_scope）
2. 使用 Account Manager OAuth 获取令牌，并包含两种必需的作用域类型：
   • 租户作用域：SALESFORCE_COMMERCE_API:<tenant_id> — 授予对租户的访问权限
   • 自定义 Admin 作用域：c_my_admin_scope — 如 schema.yaml 中所声明
3. 在请求中省略 siteId（或使用 siteId=Sites-Site）以采用组织上下文

# b2c auth token accepts multiple scopes (repeat --auth-scope or comma-separate).
# It does NOT auto-inject the tenant scope, so list it explicitly:
TOKEN=$(b2c auth token \
  --auth-scope "SALESFORCE_COMMERCE_API:zzpq_013" \
  --auth-scope c_my_admin_scope)

**租户作用域为何重要：**SCAPI 子命令（b2c scapi custom status、b2c scapi schemas list）会为你注入 SALESFORCE_COMMERCE_API:<tenant_id>，但 b2c auth token 和原始 curl 请求只会发送你传入的作用域。缺少租户作用域的令牌对任何 Admin API（自定义或系统 API）的请求都会返回 403。

有关 curl 示例和身份验证设置，请参阅测试参考。

故障排查

错误	原因	解决方案
400 Bad Request	参数无效/未知	在 schema 中定义所有参数
401 Unauthorized	令牌无效	检查令牌是否有效
403 Forbidden	缺少作用域	验证令牌中的作用域。对于 Admin API，令牌需要同时包含**SALESFORCE_COMMERCE_API:<tenant_id> 和你的自定义作用域**
404 Not Found	尚未注册	检查 b2c scapi custom status
500 Internal Error	脚本错误	检查 b2c logs get --level ERROR
503 Service Unavailable	熔断器已开启	修复错误并等待重置

注册问题

• Shopper API 端点未显示：确认 cartridge 位于站点的 cartridge 路径中（b2c sites cartridges list --site-id <site>），然后重新激活代码版本。
• Admin API 端点调用时使用了 storefront siteId：确认 cartridge 位于该站点的 cartridge 路径中。
• Admin API 端点使用 siteId=Sites-Site（或省略 siteId）调用时返回 404 / 始终无法注册：cartridge 必须位于Business Manager cartridge 路径中。使用 b2c sites cartridges list --bm 检查，并通过 b2c sites cartridges add <cartridge> --bm --position first 添加。之后重新激活代码版本。请参阅上文的 Cartridge 路径要求。
• **检查日志：**使用 b2c logs get，或在 Log Center 中筛选 CustomApiRegistry

相关技能

• b2c-cli:b2c-code - 部署 cartridge 并激活代码版本
• b2c-cli:b2c-scapi-custom - 检查 Custom API 注册状态
• b2c-cli:b2c-slas - 创建 SLAS 客户端以测试 Shopper API
• b2c:b2c-webservices - 外部调用的服务配置

参考文档

• 契约参考 - 完整的 schema.yaml 示例、Shopper 与 Admin API
• 实现参考 - script.js 模式、缓存、远程包含项
• 测试参考 - 身份验证设置、curl 示例