b2c-scapi-admin

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SCAPI Admin APIs

This skill guides you through consuming Admin APIs for backend integrations, data synchronization, and management operations. Admin APIs are designed for server-to-server integration, not storefront use.

Note: For shopper-facing APIs (products, baskets, checkout), see b2c-scapi-shopper. This skill focuses on admin/backend operations.

本技能将指导您如何使用Admin APIs进行后端集成、数据同步和管理操作。Admin APIs专为服务器到服务器的集成设计，不适合前端商城使用。

注意： 面向购物者的API（如商品、购物车、结账）请查看 b2c-scapi-shopper 。本技能专注于管理员/后端操作。

Overview

概述

Admin APIs are designed for backend systems and integrations:

Client: Backend services, ETL pipelines, management tools
Authentication: Account Manager OAuth (client credentials)
Response Time: < 60 seconds (HTTP 504 if exceeded)
Usage: Moderate frequency, batch operations preferred

Admin APIs专为后端系统和集成场景设计：

客户端：后端服务、ETL管道、管理工具
身份验证：Account Manager OAuth（客户端凭证）
响应时间：< 60秒（超过则返回HTTP 504）
使用建议：中等调用频率，优先使用批量操作

Base URL Structure

基础URL结构

https://{shortCode}.api.commercecloud.salesforce.com/{apiFamily}/{apiName}/v1/organizations/{organizationId}/{resource}

Example:

https://kv7kzm78.api.commercecloud.salesforce.com/product/products/v1/organizations/f_ecom_zzte_053/products/25518823M

Note: Admin APIs typically don't require

siteId

parameter (unlike Shopper APIs).

https://{shortCode}.api.commercecloud.salesforce.com/{apiFamily}/{apiName}/v1/organizations/{organizationId}/{resource}

示例：

https://kv7kzm78.api.commercecloud.salesforce.com/product/products/v1/organizations/f_ecom_zzte_053/products/25518823M

注意： 与Shopper APIs不同，Admin APIs通常不需要

siteId

参数。

Authentication

身份验证

Admin APIs use Account Manager OAuth with client credentials flow.

Admin APIs采用Account Manager OAuth的客户端凭证流进行身份验证。

Get Admin Token via CLI

通过CLI获取管理员令牌

bash

undefined

bash

undefined

Get admin token (uses clientId/clientSecret from dw.json)

获取管理员令牌（使用dw.json中的clientId/clientSecret）

b2c auth token

Get token with specific scopes

获取带有特定权限范围的令牌

b2c auth token --auth-scope sfcc.orders --auth-scope sfcc.products

Get token as JSON (includes expiration)

以JSON格式获取令牌（包含过期时间）

b2c auth token --json


See [b2c-config skill](../../b2c-cli/skills/b2c-config/SKILL.md) for configuration details.

b2c auth token --json


配置详情请查看[ b2c-config 技能](../../b2c-cli/skills/b2c-config/SKILL.md)。

Get Token Programmatically

以编程方式获取令牌

bash

curl "https://account.demandware.com/dwsso/oauth2/access_token" \
  --request 'POST' \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data "grant_type=client_credentials" \
  --data-urlencode "scope=SALESFORCE_COMMERCE_API:${TENANT_ID} ${SCOPES}"

Example:

bash

CLIENT_ID="your-client-id"
CLIENT_SECRET="your-client-secret"
TENANT_ID="zzte_053"
SCOPES="sfcc.orders sfcc.products"

TOKEN=$(curl -s "https://account.demandware.com/dwsso/oauth2/access_token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=SALESFORCE_COMMERCE_API:$TENANT_ID $SCOPES" \
  | jq -r '.access_token')

bash

curl "https://account.demandware.com/dwsso/oauth2/access_token" \
  --request 'POST' \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data "grant_type=client_credentials" \
  --data-urlencode "scope=SALESFORCE_COMMERCE_API:${TENANT_ID} ${SCOPES}"

示例：

bash

CLIENT_ID="your-client-id"
CLIENT_SECRET="your-client-secret"
TENANT_ID="zzte_053"
SCOPES="sfcc.orders sfcc.products"

TOKEN=$(curl -s "https://account.demandware.com/dwsso/oauth2/access_token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=SALESFORCE_COMMERCE_API:$TENANT_ID $SCOPES" \
  | jq -r '.access_token')

Dual Scope Requirement

双重权限范围要求

Admin APIs require two types of scopes:

Tenant scope:
```
SALESFORCE_COMMERCE_API:{tenant_id}
```
- grants access to the tenant
API-specific scopes:
```
sfcc.catalogs
```
,
```
sfcc.orders.rw
```
, etc. - grants API access

scope=SALESFORCE_COMMERCE_API:zzte_053 sfcc.catalogs sfcc.products.rw

See OAuth Scopes Reference for the complete scope list.

Admin APIs需要两种类型的权限范围：

租户权限范围：
```
SALESFORCE_COMMERCE_API:{tenant_id}
```
- 授予租户访问权限
API特定权限范围：
```
sfcc.catalogs
```
、
```
sfcc.orders.rw
```
等 - 授予对应API的访问权限

scope=SALESFORCE_COMMERCE_API:zzte_053 sfcc.catalogs sfcc.products.rw

完整的权限范围列表请查看 OAuth Scopes Reference 。

Account Manager Setup

Account Manager 设置

Log into Account Manager
Navigate to API Client > Add API Client
Configure:
- Display Name and Password (client secret)
- Assign Organizations (your B2C instances)
- Role: "Salesforce Commerce API"
- Token Endpoint Auth Method:
```
client_secret_post
```
- Access Token Format:
```
JWT
```
- Allowed Scopes: Add required scopes
Copy the Client ID

登录Account Manager
导航至API Client > Add API Client
配置以下内容：
- 显示名称和密码（客户端密钥）
- 分配组织（您的B2C实例）
- 角色："Salesforce Commerce API"
- 令牌端点认证方式：
```
client_secret_post
```
- 访问令牌格式：
```
JWT
```
- 允许的权限范围：添加所需的权限范围
复制客户端ID

API Families

API 家族

Products API

Manage product catalog data.

javascript

// Get product
const product = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/products/v1/organizations/${orgId}/products/${productId}`,
    {
        headers: { 'Authorization': `Bearer ${adminToken}` }
    }
).then(r => r.json());

// Update product
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/products/v1/organizations/${orgId}/products/${productId}`,
    {
        method: 'PATCH',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            name: { default: 'Updated Product Name' },
            shortDescription: { default: 'New description' }
        })
    }
);

Required Scopes:

Read:
```
sfcc.products
```
Write:
```
sfcc.products.rw
```

管理商品目录数据。

javascript

// 获取商品
const product = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/products/v1/organizations/${orgId}/products/${productId}`,
    {
        headers: { 'Authorization': `Bearer ${adminToken}` }
    }
).then(r => r.json());

// 更新商品
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/products/v1/organizations/${orgId}/products/${productId}`,
    {
        method: 'PATCH',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            name: { default: 'Updated Product Name' },
            shortDescription: { default: 'New description' }
        })
    }
);

所需权限范围：

读取：
```
sfcc.products
```
写入：
```
sfcc.products.rw
```

Catalogs API

Manage catalog structure and assignments.

javascript

// List catalogs
const catalogs = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/catalogs/v1/organizations/${orgId}/catalogs`,
    {
        headers: { 'Authorization': `Bearer ${adminToken}` }
    }
).then(r => r.json());

// Get catalog details
const catalog = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/catalogs/v1/organizations/${orgId}/catalogs/${catalogId}`,
    {
        headers: { 'Authorization': `Bearer ${adminToken}` }
    }
).then(r => r.json());

Required Scopes:

Read:
```
sfcc.catalogs
```
Write:
```
sfcc.catalogs.rw
```

管理目录结构与分配。

javascript

// 列出目录
const catalogs = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/catalogs/v1/organizations/${orgId}/catalogs`,
    {
        headers: { 'Authorization': `Bearer ${adminToken}` }
    }
).then(r => r.json());

// 获取目录详情
const catalog = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/catalogs/v1/organizations/${orgId}/catalogs/${catalogId}`,
    {
        headers: { 'Authorization': `Bearer ${adminToken}` }
    }
).then(r => r.json());

所需权限范围：

读取：
```
sfcc.catalogs
```
写入：
```
sfcc.catalogs.rw
```

Orders API

Retrieve and manage orders.

javascript

// Get order by number
const order = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/checkout/orders/v1/organizations/${orgId}/orders/${orderNo}?siteId=${siteId}`,
    {
        headers: { 'Authorization': `Bearer ${adminToken}` }
    }
).then(r => r.json());

// Update order status
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/checkout/orders/v1/organizations/${orgId}/orders/${orderNo}?siteId=${siteId}`,
    {
        method: 'PATCH',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            status: 'completed',
            shippingStatus: 'shipped'
        })
    }
);

Required Scopes:

Read:
```
sfcc.orders
```
Write:
```
sfcc.orders.rw
```

检索和管理订单。

javascript

// 根据订单号获取订单
const order = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/checkout/orders/v1/organizations/${orgId}/orders/${orderNo}?siteId=${siteId}`,
    {
        headers: { 'Authorization': `Bearer ${adminToken}` }
    }
).then(r => r.json());

// 更新订单状态
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/checkout/orders/v1/organizations/${orgId}/orders/${orderNo}?siteId=${siteId}`,
    {
        method: 'PATCH',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            status: 'completed',
            shippingStatus: 'shipped'
        })
    }
);

所需权限范围：

读取：
```
sfcc.orders
```
写入：
```
sfcc.orders.rw
```

Inventory Availability API

Manage product inventory.

javascript

// Get inventory for a product
const availability = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/inventory/availability/v1/organizations/${orgId}/availability-records/search`,
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            skus: ['SKU001', 'SKU002'],
            locationIds: ['warehouse-1']
        })
    }
).then(r => r.json());

// Update inventory
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/inventory/availability/v1/organizations/${orgId}/availability-records`,
    {
        method: 'PATCH',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            records: [{
                sku: 'SKU001',
                locationId: 'warehouse-1',
                onHand: 100,
                effectiveDate: new Date().toISOString()
            }]
        })
    }
);

Required Scopes:

Read:
```
sfcc.inventory.availability
```
Write:
```
sfcc.inventory.availability.rw
```

管理商品库存。

javascript

// 获取商品库存
const availability = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/inventory/availability/v1/organizations/${orgId}/availability-records/search`,
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            skus: ['SKU001', 'SKU002'],
            locationIds: ['warehouse-1']
        })
    }
).then(r => r.json());

// 更新库存
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/inventory/availability/v1/organizations/${orgId}/availability-records`,
    {
        method: 'PATCH',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            records: [{
                sku: 'SKU001',
                locationId: 'warehouse-1',
                onHand: 100,
                effectiveDate: new Date().toISOString()
            }]
        })
    }
);

所需权限范围：

读取：
```
sfcc.inventory.availability
```
写入：
```
sfcc.inventory.availability.rw
```

Inventory IMPEX API

High-performance bulk inventory import. Use for 1000+ SKU updates.

Critical Requirements:

Files > 100MB MUST be gzip compressed
Use newline-delimited JSON (NDJSON), not comma-separated arrays
Don't run imports during location graph changes
Use delta imports (changed data only) for best performance
Future quantity values must be > 0

javascript

// Step 1: Initiate import
const importJob = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/${orgId}/availability-records/imports`,
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({})
    }
).then(r => r.json());

// Step 2: Prepare newline-delimited JSON
const ndjsonData = inventoryRecords
    .map(r => JSON.stringify({
        recordId: r.recordId || crypto.randomUUID(),
        sku: r.sku,
        locationId: r.locationId,
        onHand: r.quantity,
        effectiveDate: new Date().toISOString()
    }))
    .join('\n');

// Step 3: Upload data to the uploadLink
await fetch(importJob.uploadLink, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: ndjsonData
});

// Step 4: Monitor status
const status = await fetch(importJob.importStatusLink, {
    headers: { 'Authorization': `Bearer ${adminToken}` }
}).then(r => r.json());

Required Scope:

sfcc.inventory.impex-inventory

Note: Inventory IMPEX logs don't appear in Log Center. Use correlation IDs and monitor import status directly.

See Integration Patterns Reference for bulk import best practices.

高性能批量库存导入。适用于1000+ SKU的更新场景。

关键要求：

大于100MB的文件必须使用gzip压缩
使用换行分隔的JSON（NDJSON）格式，而非逗号分隔的数组
请勿在位置图变更期间运行导入任务
优先使用增量导入（仅导入变更数据）以获得最佳性能
未来库存数量值必须大于0

javascript

// 步骤1：启动导入任务
const importJob = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/${orgId}/availability-records/imports`,
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({})
    }
).then(r => r.json());

// 步骤2：准备换行分隔的JSON数据
const ndjsonData = inventoryRecords
    .map(r => JSON.stringify({
        recordId: r.recordId || crypto.randomUUID(),
        sku: r.sku,
        locationId: r.locationId,
        onHand: r.quantity,
        effectiveDate: new Date().toISOString()
    }))
    .join('\n');

// 步骤3：将数据上传至uploadLink
await fetch(importJob.uploadLink, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: ndjsonData
});

// 步骤4：监控任务状态
const status = await fetch(importJob.importStatusLink, {
    headers: { 'Authorization': `Bearer ${adminToken}` }
}).then(r => r.json());

所需权限范围：

sfcc.inventory.impex-inventory

注意： Inventory IMPEX的日志不会出现在日志中心。请使用关联ID并直接监控导入状态。

批量导入最佳实践请查看 Integration Patterns Reference 。

Customers API

Manage customer data.

javascript

// Search customers
const customers = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/customer/customers/v1/organizations/${orgId}/customer-search?siteId=${siteId}`,
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            query: {
                textQuery: { fields: ['email'], searchPhrase: 'john@example.com' }
            }
        })
    }
).then(r => r.json());

Required Scopes:

Read:
```
sfcc.shopper-customers
```
Write:
```
sfcc.shopper-customers.rw
```

管理客户数据。

javascript

// 搜索客户
const customers = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/customer/customers/v1/organizations/${orgId}/customer-search?siteId=${siteId}`,
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            query: {
                textQuery: { fields: ['email'], searchPhrase: 'john@example.com' }
            }
        })
    }
).then(r => r.json());

所需权限范围：

读取：
```
sfcc.shopper-customers
```
写入：
```
sfcc.shopper-customers.rw
```

Promotions API

Manage promotions and campaigns.

javascript

// Get promotion
const promotion = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/pricing/promotions/v1/organizations/${orgId}/promotions/${promotionId}?siteId=${siteId}`,
    {
        headers: { 'Authorization': `Bearer ${adminToken}` }
    }
).then(r => r.json());

// Update promotion
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/pricing/promotions/v1/organizations/${orgId}/promotions/${promotionId}?siteId=${siteId}`,
    {
        method: 'PATCH',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            enabled: true,
            startDate: '2024-06-01T00:00:00Z',
            endDate: '2024-06-30T23:59:59Z'
        })
    }
);

Required Scopes:

Read:
```
sfcc.promotions
```
Write:
```
sfcc.promotions.rw
```

管理促销活动与营销活动。

javascript

// 获取促销活动
const promotion = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/pricing/promotions/v1/organizations/${orgId}/promotions/${promotionId}?siteId=${siteId}`,
    {
        headers: { 'Authorization': `Bearer ${adminToken}` }
    }
).then(r => r.json());

// 更新促销活动
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/pricing/promotions/v1/organizations/${orgId}/promotions/${promotionId}?siteId=${siteId}`,
    {
        method: 'PATCH',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            enabled: true,
            startDate: '2024-06-01T00:00:00Z',
            endDate: '2024-06-30T23:59:59Z'
        })
    }
);

所需权限范围：

读取：
```
sfcc.promotions
```
写入：
```
sfcc.promotions.rw
```

Request Tracking

请求追踪

Correlation IDs

关联ID

Include correlation IDs for tracking requests across systems:

javascript

const correlationId = crypto.randomUUID();

const response = await fetch(url, {
    headers: {
        'Authorization': `Bearer ${adminToken}`,
        'correlation-id': correlationId
    }
});

console.log(`Request ${correlationId} completed`);
// Search Log Center: externalID:({correlationId})

添加关联ID以跨系统追踪请求：

javascript

const correlationId = crypto.randomUUID();

const response = await fetch(url, {
    headers: {
        'Authorization': `Bearer ${adminToken}`,
        'correlation-id': correlationId
    }
});

console.log(`Request ${correlationId} completed`);
// 在日志中心搜索：externalID:({correlationId})

Verbose Logging

详细日志

Enable verbose logging for debugging:

javascript

const response = await fetch(url, {
    headers: {
        'Authorization': `Bearer ${adminToken}`,
        'sfdc_verbose': 'true'
    }
});

Check Log Center under

scapi.verbose

category.

Note: Some Admin APIs (CDN Zones, Inventory, Shopper Context) don't log to Log Center.

启用详细日志以进行调试：

javascript

const response = await fetch(url, {
    headers: {
        'Authorization': `Bearer ${adminToken}`,
        'sfdc_verbose': 'true'
    }
});

在日志中心的

scapi.verbose

分类下查看日志。

注意： 部分Admin APIs（如CDN Zones、Inventory、Shopper Context）不会记录到日志中心。

Error Handling

错误处理

Common Errors

常见错误

Status	Meaning	Action
400	Bad Request	Check request body/parameters
401	Unauthorized	Token expired - get new token
403	Forbidden	Missing scope or tenant access
404	Not Found	Resource doesn't exist
429	Rate Limited	Implement backoff
500	Server Error	Retry with backoff
504	Timeout	Request took > 60 seconds

状态码	含义	处理方式
400	请求错误	检查请求体/参数
401	未授权	令牌过期 - 获取新令牌
403	禁止访问	缺少权限范围或租户访问权限
404	资源不存在	资源不存在
429	请求频率超限	实现退避策略
500	服务器错误	退避后重试
504	请求超时	请求耗时超过60秒

Rate Limiting

请求频率限制

Admin APIs have lower rate limits than Shopper APIs. For bulk operations:

Use batch endpoints when available
Implement exponential backoff for 429 responses
Consider inventory IMPEX for large data imports
Spread operations over time for non-urgent updates

Admin APIs的频率限制低于Shopper APIs。对于批量操作：

尽可能使用批量端点
针对429响应实现指数退避策略
对于大型数据导入，考虑使用Inventory IMPEX
对于非紧急更新，分散操作时间

Related Skills

Reference Documentation

参考文档

OAuth Scopes Reference - Complete admin scope reference
Integration Patterns - ETL, sync, and bulk import patterns

OAuth Scopes Reference - 完整的管理员权限范围参考
Integration Patterns - ETL、同步和批量导入模式

b2c-scapi-admin

Original

Translation

SCAPI Admin APIs

SCAPI Admin APIs

Overview

概述

Base URL Structure

基础URL结构

Authentication

身份验证

Get Admin Token via CLI

通过CLI获取管理员令牌

Get admin token (uses clientId/clientSecret from dw.json)

获取管理员令牌（使用dw.json中的clientId/clientSecret）

Get token with specific scopes

获取带有特定权限范围的令牌

Get token as JSON (includes expiration)

以JSON格式获取令牌（包含过期时间）

Get Token Programmatically

以编程方式获取令牌

Dual Scope Requirement

双重权限范围要求

Account Manager Setup

Account Manager 设置

API Families

API 家族

Products API

Products API

Catalogs API

Catalogs API

Orders API

Orders API

Inventory Availability API

Inventory Availability API

Inventory IMPEX API

Inventory IMPEX API

Customers API

Customers API

Promotions API

Promotions API

Request Tracking

请求追踪

Correlation IDs

关联ID

Verbose Logging

详细日志

Error Handling

错误处理

Common Errors

常见错误

Rate Limiting

请求频率限制

Related Skills

相关技能

Reference Documentation

参考文档