cclee-shipping 物流插件使用指南
cclee-shipping 是 WooCommerce 多承运商物流插件，支持 FedEx、顺丰国际 等承运商实时运费报价。客户结算时自动显示真实运费，无需手动维护运费表。
快速入门
前提条件
- WordPress 6.4+
- WooCommerce 8.0+
- 已有 FedEx 或顺丰国际账户
第一步：安装插件
- 进入 WordPress 后台 → 插件 → 安装插件 → 上传插件
- 选择
cclee-shipping.zip文件 → 点击现在安装 - 安装完成后点击启用
安装成功
插件启用后会自动注册 FedEx 和顺丰两种配送方式，无需额外激活。
第二步：创建配送区域
WooCommerce 通过配送区域来匹配客户地址和运费规则。
- 进入 WooCommerce → 设置 → 配送 → 配送区域
- 点击添加配送区域
- 填写区域名称（如「国际配送」）
- 在区域范围中选择配送目的地（如「所有国家」或指定国家）
- 点击添加配送方式
第三步：添加承运商
在配送区域中添加 FedEx 或顺丰：
- 在选择配送方式下拉框中选择 FedEx (CCLEE Shipping) 或 顺丰国际 (CCLEE Shipping)
- 点击添加配送方式
- 点击该方式右侧的管理按钮，进入设置页面
第四步：配置 FedEx 凭证
| 设置项 | 填写内容 | 获取位置 |
|---|---|---|
| API Key | FedEx API Key | FedEx Developer Portal |
| Secret Key | FedEx Secret Key | 同上 |
| Account Number | FedEx 账号 | FedEx 账户后台 |
| Environment | production | 沙箱测试选 sandbox |
FedEx 凭证获取
- 访问 FedEx Developer Portal
- 注册开发者账号并创建项目
- 在项目详情页获取 API Key 和 Secret Key
- Account Number 在 FedEx 官网账户设置中查看
第五步：测试运费
- 前台添加商品到购物车
- 进入结算页
- 填写收货地址
- 查看运费选项是否显示 FedEx 报价
承运商配置详解
FedEx 设置项
| 设置项 | 说明 | 推荐值 |
|---|---|---|
| API Key | FedEx 开发者 API Key | — |
| Secret Key | FedEx 开发者密钥 | — |
| Account Number | FedEx 账号 | — |
| Environment | 环境 | 生产环境选 production |
| Enabled Services | 启用的服务类型 | 国际件建议选 INTERNATIONAL_PRIORITY + INTERNATIONAL_ECONOMY |
| Rate Modifier Type | 运费加成方式 | 固定金额或百分比 |
| Rate Modifier Value | 加成数值 | 0 表示原价，可设置利润加成 |
| Package Type | 默认包装类型 | Your Packaging（自备包装） |
| Shipping Payment Type | 运费支付方 | SENDER（商家预付） |
| Duties Payment Type | 关税支付方 | SENDER 或 RECIPIENT（到付） |
| Debug Mode | 调试模式 | 正常运营关闭，排查问题时开启 |
顺丰国际设置项
| 设置项 | 说明 | 获取位置 |
|---|---|---|
| Customer Code | 顾客编码 | 顺丰开放平台 |
| Check Word | 校验码 | 顺丰开放平台 |
| Environment | 环境 | 生产环境选 production |
| Enabled Services | 启用的服务 | 国际件建议选 36/37/38/44 |
顺丰凭证获取
顺丰国际 API 需要联系顺丰客户经理开通，在 顺丰开放平台 获取顾客编码和校验码。
顺丰国际服务类型
| 代码 | 名称 | 适用场景 |
|---|---|---|
| 36 | 跨境速配 | 快速跨境配送 |
| 37 | 国际特惠 | 经济型国际件 |
| 38 | 国际标快 | 标准国际件 |
| 44 | 国际电商专递 | 跨境电商专用 |
FedEx 沙盒测试工具
cclee-shipping 内置 Label Test 管理工具，用于在 FedEx 沙盒环境测试 Ship API 下单，验证 API 凭证和账号配置是否正确。
适用场景
刚完成 FedEx API 注册，需要对接沙盒环境验证 Ship API 是否可用。注册流程参见 FedEx 注册教程。
打开 Label Test
- 进入 WordPress 后台 → WooCommerce → Label Test
- 页面顶部显示 FedEx 连接状态：
- Credentials：是否已配置（需先在配送区域添加 FedEx 方式并填写凭证）
- Environment：当前环境（Sandbox 或 Production）
- Account Number：当前使用的 FedEx 账号
前置条件
Label Test 使用配送区域中 FedEx 方式的凭证。如显示「Not configured」，请先按 快速入门 完成 FedEx 配置。
生成测试面单
- 确认连接状态显示 Configured，Environment 为 Sandbox
- 点击 Generate Test Label 按钮
- 等待 FedEx Ship API 返回（超时上限 30 秒）
生成成功后会显示：
- Tracking Number：测试运单号
- Preview：查看 ZPL 原始文本内容
- Download：下载
.zpl面单文件（用于热敏打印机） - Print：ZPL 格式需要热敏打印机，暂不可用
测试通过
成功返回 Tracking Number，说明 FedEx Ship API 对接正常，可申请生产环境权限。切换方法参见下方常见问题「如何切换到生产环境？」。
测试失败排查
| 错误信息 | 原因 | 解决方法 |
|---|---|---|
| FedEx shipping method not configured | 未在配送区域添加 FedEx | 先添加 FedEx 配送方式并填写凭证 |
| FedEx OAuth authentication failed | API Key 或 Secret 错误 | 检查 Developer Portal 中的 Client ID 和 Secret |
| FedEx API error (4xx/5xx) | FedEx 拒绝请求 | 查看具体错误消息，检查 API 权限是否已开通 |
| Label data not found | 响应中无面单数据 | 查看 WooCommerce → 状态 → 日志（source: cclee-shipping-label-test） |
运费支付方式说明
运费支付方（Shipping Payment）
| 选项 | 含义 | 结账显示 |
|---|---|---|
| SENDER（商家预付） | 运费从商家 FedEx 账户扣除 | 客户支付商品 + 运费 |
| RECIPIENT（收件人到付） | 运费由收件人支付 | 运费显示 $0，收件人签收时付费 |
如何选择？
- 跨境 B2C 电商：选 SENDER，客户结账时一次性付清
- 样品寄送/大客户：可选 RECIPIENT，让对方承担运费
关税支付方（Duties & Taxes Payment）
仅国际件有效，决定谁来支付海关关税和税费。
| 选项 | 含义 |
|---|---|
| SENDER | 商家预付关税，客户无需额外付费 |
| RECIPIENT | 收件人支付关税，包裹到达时收取 |
关税到付风险
选择 RECIPIENT 时，客户可能在收货时被要求支付关税，可能导致拒收。建议商家预付或提前告知客户。
运费加成设置
cclee-shipping 支持在承运商原价基础上加成，用于覆盖包装成本或增加利润。
固定金额加成
每个包裹加收固定金额（如 $5）。
示例：FedEx 报价 $20 → 显示 $25
百分比加成
按承运商报价的百分比加成（如 10%）。
示例：FedEx 报价 $20 → 显示 $22
常见问题 FAQ
运费不显示怎么办？
排查步骤
- 检查凭证：确认 API Key、Secret Key、Account Number 填写正确
- 检查环境：生产环境请选择 production
- 开启调试：在设置中启用 Debug Mode，查看 WooCommerce → 状态 → 日志
- 检查地址：确保配送区域覆盖客户收货地址
- 检查商品重量：商品必须设置重量，否则无法计算运费
如何设置包邮门槛？
cclee-shipping 只负责运费计算，包邮设置请使用 WooCommerce 免费配送方式：
- 在同一配送区域添加免费配送方式
- 设置最低订单金额（如 $100）
- 客户满足条件时自动显示免运费选项
支持国内配送吗？
- FedEx：支持美国境内 FedEx Ground
- 顺丰：目前仅支持国际件（服务类型 36-38, 44）
国内顺丰配送请联系顺丰商务开通国内件 API。
运费与实际收费不一致？
运费报价基于以下因素：
- 商品重量和尺寸（请在商品设置中填写）
- 包装类型（默认 Your Packaging）
- 起运地和目的地地址
如果报价与实际差异较大，请检查商品重量设置是否准确。
如何切换到生产环境？
- 在 FedEx Developer Portal 申请 Production Key
- 将 API Key、Secret Key、Account Number 更换为生产环境凭证
- 在插件设置中将 Environment 改为 production
- 保存设置
技术支持
- GitHub：cclee-hub/cclee-shipping
- 问题反馈：GitHub Issues
访问 GitHub 仓库