b2c-scapi-custom

B2C SCAPI 自定义 API 技能

使用 b2c CLI 插件管理 SCAPI 自定义 API 端点并检查其注册状态。

如果 B2C MCP 可用，注册状态优先使用 scapi_custom_apis_get_status 查询，实时契约优先使用 scapi_schemas_list 查询。要执行 Admin 自定义 API，请阅读 skill://mcp/b2c-mcp-scapi/SKILL.md；在调用端点之前，先在程序中通过 scapi.request 获取契约。读取架构需要 sfcc.scapi-schemas； 执行需要已声明的 c_* 作用域。不支持 Shopper 执行。

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

配置

tenantId、shortCode、clientId 和 clientSecret 等值会从 dw.json / SFCC_* 环境变量 / 当前活动实例 / 配置插件中解析。以下示例展示最精简的用法；只有在需要覆盖已配置的值时才添加标志——通常不需要传入 --client-id / --client-secret / --tenant-id / --short-code。如果缺少必需值，CLI 会提供可操作的错误提示，指出对应的标志、环境变量和配置键。

运行 b2c setup inspect 查看解析后的配置，以及每个值的来源（可使用 --json 进行脚本处理；默认情况下，机密信息会保持遮蔽）。有关优先级规则和故障排除，请参阅 b2c-cli:b2c-config 技能。

Tenant ID 与 Organization ID

Tenant ID 用于标识你的 B2C Commerce 实例。它与 Organization ID 不同：

• Tenant ID：zzxy_prd（dw.json 中的 tenantId 值，或通过 --tenant-id 覆盖）
• Organization ID：f_ecom_zzxy_prd（用于 SCAPI URL，带有 f_ecom_ 前缀）

根据主机名推导 Tenant ID

对于沙盒实例，可将主机名中的连字符替换为下划线来推导 Tenant ID：

主机名	Tenant ID
zzpq-013.dx.commercecloud.salesforce.com	zzpq_013
zzxy-001.dx.commercecloud.salesforce.com	zzxy_001
abcd-dev.dx.commercecloud.salesforce.com	abcd_dev

对于生产实例，请使用你的 realm 和实例标识符（例如 zzxy_prd）。

示例

获取自定义 API 端点状态

# list all Custom API endpoints for the configured tenant
b2c scapi custom status

# list with JSON output
b2c scapi custom status --json

# target a different tenant than the active config
b2c scapi custom status --tenant-id zzxy_prd

按状态筛选

# list only active endpoints
b2c scapi custom status --status active

# list only endpoints that failed to register
b2c scapi custom status --status not_registered

按类型或站点分组

# group endpoints by API type (Admin vs Shopper)
b2c scapi custom status --group-by type

# group endpoints by site
b2c scapi custom status --group-by site

自定义输出列

# show extended columns (includes error reasons, sites, etc.)
b2c scapi custom status --extended

# select specific columns to display
b2c scapi custom status --columns type,apiName,status,sites

# available columns: type, apiName, apiVersion, cartridgeName, endpointPath, httpMethod, status, sites, securityScheme, operationId, schemaFile, implementationScript, errorReason, id

调试注册失败的问题

# quickly find and diagnose failed Custom API registrations
b2c scapi custom status --status not_registered --columns type,apiName,endpointPath,errorReason

配置覆盖

Tenant ID 和 short code 可通过标志或环境变量覆盖：

• --tenant-id / SFCC_TENANT_ID / dw.json 中的 tenantId
• --short-code / SFCC_SHORTCODE / dw.json 中的 shortCode

更多命令

有关可用命令和选项的完整列表，请参阅 b2c scapi custom --help。

OAuth 作用域（手动获取令牌）

b2c scapi custom status 会自动注入所需作用域——域作用域 sfcc.custom-apis 和 Tenant 作用域 SALESFORCE_COMMERCE_API:<tenant_id>。运行此命令时无需传入这些作用域。

当你手动获取令牌（使用 b2c auth token 或 curl）以直接调用自定义 Admin API 时，不会发生此类注入——你必须自行列出 Tenant 作用域和你的作用域。b2c auth token 支持多个作用域（重复使用 --auth-scope 或以逗号分隔）：

# Token for calling a custom Admin API endpoint
b2c auth token \
  --auth-scope "SALESFORCE_COMMERCE_API:zzpq_013" \
  --auth-scope c_my_admin_scope

缺少 Tenant 作用域的令牌会返回 403。有关完整的请求示例，请参阅 b2c:b2c-custom-api-development（测试参考）。

相关技能

• b2c:b2c-custom-api-development - 创建自定义 API 端点（架构、脚本、映射）
• b2c-cli:b2c-code - 部署和激活代码版本（触发注册）