cj-dropshipping-api

打通CJ Dropshipping全链路，搜品、下单、跟踪一键调用

SKILL.md

GitHub

CJ Dropshipping API V2.0

accio-mcp-cli 仅用于 CJ OAuth 认证和读取存储的令牌（start_cj_auth、get_cj_access_token）。其余所有功能——商品搜索、订单、物流、Webhook、伙伴刊登——均遵循第 2 节起的 REST API：使用 get_cj_access_token 获取的 CJ-Access-Token 请求头调用 https://developers.cjdropshipping.com/api2.0/v1/...。

两个认证调用的 CLI 参数（如 --port、--raw、--refresh），请参阅 accio-mcp-cli 技能。

1. 认证（仅限 accio-mcp-cli）

执行一次 OAuth，然后在每次 REST 请求前读取令牌。

accio-mcp-cli call start_cj_auth
accio-mcp-cli call get_cj_access_token
步骤 命令
启动 OAuth（用户在浏览器中完成授权链接） accio-mcp-cli call start_cj_auth
读取存储的令牌对 accio-mcp-cli call get_cj_access_token

将返回的 accessToken 作为 CJ-Access-Token 用于下方所有 REST 调用。如需完整的网关 JSON，请在 get_cj_access_token 后附加 --raw。

返回数据示例（字段可能有所差异；使用 --raw 可获取精确的 MCP 结果）：

{
  "provider": "cj",
  "accessToken": "...",
  "accessTokenExpiryDate": "...",
  "refreshToken": "...",
  "refreshTokenExpiryDate": "..."
}

2. 商品管理与刊登

所有商品接口均需要：

  • CJ-Access-Token: YOUR_ACCESS_TOKEN

2.1 获取分类列表

接口： GET https://developers.cjdropshipping.com/api2.0/v1/product/getCategory

返回 CJ 分类树。

2.2 获取商品列表（V2）

接口： GET https://developers.cjdropshipping.com/api2.0/v1/product/listV2

新集成的主要商品搜索/列表接口。

查询参数：

  • page：页码，默认 1，最小 1，最大 1000
  • size：每页数量，默认 20，最小 1，最大 100
  • keyWord：搜索关键词，匹配商品名称或 SKU
  • categoryId：分类 ID 过滤
  • countryCode：仅返回指定国家有库存的商品
  • minPrice：最低价格
  • maxPrice：最高价格
  • features：可选扩展参数，用于展开商品/分类详情

2.3 获取商品详情

接口： GET https://developers.cjdropshipping.com/api2.0/v1/product/query

获取单个商品及其规格信息。

查询参数：

  • pid：商品 ID。从 pid、productSku、variantSku 中选一个
  • productSku：商品 SKU。从 pid、productSku、variantSku 中选一个
  • variantSku：规格 SKU。从 pid、productSku、variantSku 中选一个
  • countryCode：可选，库存国家过滤
  • features：可选，已记录的支持值：
    • enable_combine
    • enable_video
    • enable_inventory

重要说明： 本接口请勿使用未记录的查询参数，如 productId 或 variantId。

2.4 获取所有规格

接口： GET https://developers.cjdropshipping.com/api2.0/v1/product/variant/query

查询参数：

  • pid：从 pid、productSku、variantSku 中选一个
  • productSku：从 pid、productSku、variantSku 中选一个
  • variantSku：从 pid、productSku、variantSku 中选一个
  • countryCode：可选，库存国家过滤

2.5 获取规格详情

接口： GET https://developers.cjdropshipping.com/api2.0/v1/product/variant/queryByVid

查询参数：

  • vid：规格 ID
  • features：可选。使用 enable_inventory 可包含库存详情

2.6 按规格 ID 获取库存

接口： GET https://developers.cjdropshipping.com/api2.0/v1/product/stock/queryByVid

查询参数：

  • vid：规格 ID

2.7 按 SKU 获取库存

接口： GET https://developers.cjdropshipping.com/api2.0/v1/product/stock/queryBySku

查询参数：

  • sku：SKU 或 SPU

2.8 按商品 ID 获取库存

接口： GET https://developers.cjdropshipping.com/api2.0/v1/product/stock/getInventoryByPid

查询参数：

  • pid：商品 ID

2.9 添加到我的商品

接口： POST https://developers.cjdropshipping.com/api2.0/v1/product/addToMyProduct

请求体：

{
  "productId": "CJ_PRODUCT_ID"
}

2.10 查询我的商品

接口： GET https://developers.cjdropshipping.com/api2.0/v1/product/myProduct/query

查询参数：

  • keyword：SKU/SPU/商品名称
  • categoryId：分类过滤
  • startAt：开始时间
  • endAt：结束时间
  • isListed：刊登状态过滤
  • visiable：可见性过滤
  • hasPacked：打包状态过滤
  • hasVirPacked：虚拟打包状态过滤

2.11 商品评价

接口： GET https://developers.cjdropshipping.com/api2.0/v1/product/productComments

查询参数：

  • pid：商品 ID
  • score：可选评分过滤
  • pageNum：页码，默认 1
  • pageSize：每页数量，默认 20

2.12 批量刊登

接口： POST https://developers.cjdropshipping.com/api2.0/v1/product/listed/listedByPids

将 CJ 商品刊登到第三方店铺（如 Shopify）。

请求头：

  • CJ-Access-Token: USER_TOKEN

请求体：

{
  "shopIds": ["..."],
  "productIds": ["..."],
  "formula": {
    "formulaType": 1,
    "formulaNumber": 15,
    "shippingFrom": "CN",
    "shippingTo": "US",
    "isLogistics": 1
  },
  "templateShopCategoryVOList": [
    {
      "shopId": "...",
      "deliveryProfileId": "..."
    }
  ]
}

注意：Shopify 平台通常必须提供 deliveryProfileId，否则会触发 7001001 错误。

2.13 查询平台分类树

接口： POST https://developers.cjdropshipping.com/api2.0/v1/product/listed/getPlatformCategoryTree

获取目标平台的分类/集合（如 Shopify Collections）。

2.14 查询供应商列表

接口： POST https://developers.cjdropshipping.com/api2.0/v1/product/listed/queryVendors

获取指定店铺的可用供应商列表。

2.15 获取 CJ 默认配送模板

接口： POST https://developers.cjdropshipping.com/api2.0/v1/product/listed/getCjDefaultDeliveryProfile

返回默认配送模板，可用作 createDeliveryProfile 的基础。

2.16 创建配送模板

接口： POST https://developers.cjdropshipping.com/api2.0/v1/product/listed/createDeliveryProfile

在目标 Shopify 店铺中创建新的配送模板。需要提供 locationIds 列表和 zones（含国家和省份）。

2.17 更新配送模板

接口： POST https://developers.cjdropshipping.com/api2.0/v1/product/listed/updateDeliveryProfile

更新现有配送模板。

2.18 删除配送模板

接口： POST https://developers.cjdropshipping.com/api2.0/v1/product/listed/removeDeliveryProfile

删除配送模板。

2.19 查询店铺仓库位置

接口： POST https://developers.cjdropshipping.com/api2.0/v1/shop/location/queryList

列出店铺的所有履约仓库位置。用于识别"CJ Dropshipping"位置 ID（fromCj: true 的位置）。

2.20 查询国家与省份

接口： POST https://developers.cjdropshipping.com/api2.0/v1/shop/property/queryCountries

返回支持的国家及其省份/州列表，构建配送模板的 zones 对象时必须调用。

3. 订单处理（购物）

3.1 创建订单 V2

接口： POST https://developers.cjdropshipping.com/api2.0/v1/shopping/order/createOrderV2

请求头：

  • CJ-Access-Token: YOUR_ACCESS_TOKEN

请求体：

{
  "orderNumber": "YOUR_ORDER_ID_123",
  "shippingZip": "10001",
  "shippingCountryCode": "US",
  "shippingCountry": "United States",
  "shippingProvince": "New York",
  "shippingCity": "New York",
  "shippingAddress": "123 Main St",
  "shippingCustomerName": "John Doe",
  "shippingPhone": "1234567890",
  "remark": "Dropshipping order",
  "fromCountryCode": "CN",
  "logisticName": "CJPacket Sensitive",
  "payType": "1",
  "products": [
    {
      "vid": "CJ_VARIANT_ID",
      "quantity": 1
    }
  ]
}

payType：1（URL 支付）、2（余额支付）、3（仅创建）

3.2 获取订单详情/列表

接口： GET https://developers.cjdropshipping.com/api2.0/v1/shopping/order/list （注：搜索用 list，获取单条详情用 queryById；若 list 不是标准路径，请查阅文档确认确切路径）

列表接口： GET https://developers.cjdropshipping.com/api2.0/v1/shopping/order/list（标准 V2 模式，支持按 orderNumber、cjOrderCode、status 等过滤）

查询参数：

  • page: 1
  • size: 20
  • orderNumber：您的订单 ID
  • cjOrderCode：CJ 订单 ID
  • status：订单状态（如 '10' 表示已支付）

3.3 确认订单（支付）

若使用了 payType=3，通过以下接口确认/支付： 接口： POST https://developers.cjdropshipping.com/api2.0/v1/shopping/pay/payBalance

请求体：

{
  "orderIdList": ["CJ_ORDER_ID_1", "CJ_ORDER_ID_2"]
}

4. 物流

4.1 运费计算

接口： POST https://developers.cjdropshipping.com/api2.0/v1/logistic/freightCalculate

请求体：

{
  "startCountryCode": "CN",
  "countryCode": "US",
  "products": [
    {
      "vid": "CJ_VARIANT_ID",
      "quantity": 1
    }
  ]
}

4.2 物流跟踪

接口： GET https://developers.cjdropshipping.com/api2.0/v1/logistic/trackInfo

查询参数：

  • trackNumber：追踪号（批量查询可重复：?trackNumber=A&trackNumber=B）

4.3 查询配送模板（伙伴）

接口： POST https://developers.cjdropshipping.com/api2.0/v1/product/listed/queryDeliveryProfiles

获取刊登时需绑定的 Shopify 配送模板。

4.4 查询收件国家信息

接口： POST https://developers.cjdropshipping.com/api2.0/v1/product/listed/getReceiverCountryInfo

5. Webhook

配置 Webhook 以接收实时更新。

接口： POST https://developers.cjdropshipping.com/api2.0/v1/webhook/set

请求体：

{
  "product": { "type": "ENABLE", "callbackUrls": ["https://your-domain.com/webhook/product"] },
  "stock": { "type": "ENABLE", "callbackUrls": ["https://your-domain.com/webhook/stock"] },
  "order": { "type": "ENABLE", "callbackUrls": ["https://your-domain.com/webhook/order"] },
  "logistics": { "type": "ENABLE", "callbackUrls": ["https://your-domain.com/webhook/logistics"] }
}

事件类型：

  • product：价格/库存变更（请查阅文档确认具体 payload 类型）
  • stock：库存更新
  • order：状态变更（已支付、已发货、已完成）
  • logistics：物流跟踪更新

6. 账号设置

6.1 获取账号设置

接口： GET https://developers.cjdropshipping.com/api2.0/v1/setting/get

返回账号信息、API 配额及当前 Webhook 配置。

6.2 设置 Webhook 回调

接口： POST https://developers.cjdropshipping.com/api2.0/v1/setting/setCallback

请求体：

{
  "product": {"type": "ENABLE", "urls": ["..."]},
  "stock": {"type": "ENABLE", "urls": ["..."]},
  "order": {"type": "ENABLE", "urls": ["..."]},
  "logistic": {"type": "ENABLE", "urls": ["..."]}
}

7. 店铺 API（伙伴模式）

这些接口用于管理店铺连接和设置。

7.1 查询店铺列表

接口： GET /shop/getShops

说明： 返回用户已授权的店铺列表。成功状态码为 0。 注意： 相对路径，基础 URL 需通过伙伴系统确认。

8. API 参考（详细）

伙伴/ERP 集成的详细文档：

本节提供伙伴/刊登 API 接口摘要。

8.1 批量刊登商品（listedByPids）

接口： POST /product/listed/listedByPids

请求体（JSON）：

字段 类型 必填 说明
shopIds Set<String> 是 目标店铺 ID（如 ["shop_id"]）。
productIds List<String> 是 要刊登的 CJ 商品 ID。
formula Object 是 刊登定价公式。
formula.formulaType Integer 是 0-固定，1-加价，2-百分比，3-推荐。
formula.formulaNumber BigDecimal 是 公式数值/倍数（类型非 3 时必填）。
formula.shippingFrom String 是 发货国代码（如 "CN"）。
formula.shippingFromName String 是 发货国名称（如 "China"）。
formula.shippingTo String 是 目的国代码（如 "US"）。
formula.shippingToName String 是 目的国名称（如 "United States"）。
formula.logisticsMaxDay Integer 是 最长送达天数（如 30）。
formula.logisticsMaxPrice BigDecimal 是 最高物流费用（如 100.00）。
formula.logisticsType Integer 是 物流类型（如 0）。
formula.isLogistics Integer 是 1：含物流费，0：不含。
templateShopCategoryVOList List<Object> 否 Shopify 店铺必填。
templateShopCategoryVOList[].shopId String 是 店铺 ID。
templateShopCategoryVOList[].deliveryProfileId String 是 Shopify 配送模板 ID。

请求示例：

{
  "shopIds": ["2603221653513529700"],
  "productIds": ["1772614144538193920"],
  "formula": {
    "formulaType": 3,
    "shippingFrom": "CN",
    "shippingFromName": "China",
    "shippingTo": "US",
    "shippingToName": "United States",
    "logisticsMaxDay": 30,
    "logisticsMaxPrice": 100.00,
    "logisticsType": 0,
    "isLogistics": 1
  },
  "templateShopCategoryVOList": [
    {
      "shopId": "2603221653513529700",
      "deliveryProfileId": "112235774194"
    }
  ]
}

8.2 查询平台分类树

接口： POST /product/listed/getPlatformCategoryTree

请求体（JSON）：

字段 类型 必填 说明
shopId String 是 目标店铺 ID。
countryCode String 否 按国家站点过滤。
pageNum Integer 否 默认 1。

响应数据（data 字段）： 包含 categoryVOS 列表。对于 Shopify：

  • categoryLevel 0：自定义集合（Custom Collections）。
  • categoryLevel 1：智能集合（Smart Collections）。

8.3 查询店铺配送模板

接口： POST /product/listed/queryDeliveryProfiles

请求体（JSON）：

字段 类型 必填 说明
shopId String 否 目标店铺 ID。
forceRefresh Boolean 否 强制刷新缓存。

8.4 获取访问令牌（伙伴模式）

接口： POST /authentication/getAccessToken

成功响应（data 字段）：

  • accessToken：用于 CJ-Access-Token 请求头的令牌。
  • accessTokenExpiryDate：令牌过期时间戳。
  • refreshToken：用于刷新会话的令牌。
  • openId：用户在平台中的唯一标识。

8.5 店铺 API - 获取店铺列表

接口： GET /shop/getShops

响应示例：

{
  "success": true,
  "code": 0,
  "data": [
    {
      "shopId": "...",
      "shopName": "...",
      "platformName": "Shopify",
      "currencyCode": "USD"
    }
  ]
}

常见错误码

  • 200：成功
  • 1600100：参数错误
  • 1601000：用户不存在
  • 500：系统错误（请稍后重试）

9. 故障排查与常见错误

9.1 错误码 400：请求参数错误

  • 原因：formula 中缺少必填字段（如 shippingFrom、shippingTo），或 Shopify 店铺缺少 templateShopCategoryVOList。
  • 解决：确保所有必填字段均已填写。Shopify 平台需提供有效的 deliveryProfileId。

9.2 错误码 7001001：模板缺少配送模板

  • 原因：Shopify 店铺要求为商品分配配送模板，但未传入 deliveryProfileId。
  • 解决：通过 /product/listed/queryDeliveryProfiles 查询可用模板，并将 ID 传入 templateShopCategoryVOList。

9.3 错误码 7001003：配送模板不包含应用创建的仓库位置

  • 原因：Shopify 配送模板未启用"CJ Dropshipping"仓库位置。
  • API 自动修复：
    1. 通过 /api/shop/location/queryList 查询所有位置，找到 fromCj: true 的位置。
    2. 通过 /api/product/listed/createDeliveryProfile 创建新配送模板，或更新现有模板，将该位置 ID 加入 locationIds。
    3. 对于有省份的国家（如美国），需在 zones.countries 数组中明确提供所有省份。
  • 手动修复：引导用户进入 Shopify 后台 > 设置 > 配送与交付，编辑配送模板，将"CJ Dropshipping"位置添加进去。

10. 最佳实践

  1. 检查 deliveryProfileOpen：通过 getShops 查询店铺时，若 deliveryProfileOpen=1，刊登时必须提供 deliveryProfileId。
  2. 缓存访问令牌：不要每次调用都重新获取令牌，将其存储至接近过期时再刷新。
  3. 遵守速率限制：遵循 setting/get 接口返回的 QPS 限制。
  4. 使用 Webhook：优先使用 Webhook 而非轮询获取订单状态更新。
  5. 记录请求 ID：在响应中记录 requestId，方便与 CJ 客服协作排查问题。

11. Shopify 配送模板自动化工作流

在 Shopify 上刊登商品时，按以下自动化流程处理配送模板：

  1. 检查要求：通过 /shop/getShops 获取店铺列表。若目标店铺的 deliveryProfileOpen: 1，则需继续处理配送模板。
  2. 识别 CJ 仓库位置：调用 /shop/location/queryList，找到 fromCj: true 的位置，保存该 id（即 CJ 应用仓库位置 ID）。
  3. 查询省份（如需）：若发货目的地为美国等需要强制填写省份的国家，调用 /shop/property/queryCountries 获取省份代码列表。
  4. 配置配送模板：
    • 调用 /product/listed/queryDeliveryProfiles 查看现有模板。
    • 若有效模板已包含 CJ 位置，直接使用其 ID。
    • 否则，使用 CJ 位置 ID 和所需的国家/省份 zones 调用 /product/listed/createDeliveryProfile 创建新模板。
  5. 执行刊登：调用 /product/listed/listedByPids 时，将配送模板 ID 通过 templateShopCategoryVOList 传入。

Похожие навыки: other

limits-colimits

Context management for Claude Code. Hooks maintain state via ledgers and handoffs. MCP execution without context polluti...

Автор: parcadei
3,392

ddttom-allaboutv2-claude-skills-block-collection-and-party

The Block Collection and Block Party are repositories for existing AEM blocks, build tools, code snippets, integration p...

Автор: mattnigh
20

nodnarbnitram-claude-code-extensions-claude-skills-esphome-confi

This skill should be used when the user asks to "create an esphome config", "set up an esp32 device", "configure esphome...

Автор: mattnigh
20