WooCommerce ERP对接
WooCommerce 与店小秘、芒果店长这类 ERP 系统对接，核心就是通过 REST API 同步商品、订单和库存。
调试时最容易卡住的往往不是“功能不会开”，而是密钥权限不足、回调地址填错、固定链接设置导致接口一直 404。
本文按零基础视角梳理从准备到验证的完整流程，并给出可直接复用的排查命令，帮你把同步链路一步一步跑通。
对接前先把这三项理清楚
开始配置前，建议先检查站点环境，否则后面报错会很难分辨原因。
- WooCommerce 版本不要太旧，在后台“插件”页面能看到当前版本，如果高于 3.5 就基本支持标准 REST API。
- 站点固定链接不能是纯数字样式，比如
`?p=123，这种结构会让/wp-json` 路由无法正常解析。 - 服务器上如果装了缓存插件或安全防火墙，先确认它们不会拦截 ERP 服务器的请求，尤其是境外 IP 经常被误杀。
WooCommerce 的 API 密钥生成路径是：`WooCommerce > 设置 > 高级 > REST API`，点击“添加密钥”。
描述随意填写，权限建议先选择“读/写”，用户选择一个有管理员权限的账号。
生成后的“消费者密钥”和“消费者密钥值”要完整复制，分别填到店小秘或芒果店长的授权设置里。
需要特别注意：ERP 里的店铺地址只填域名主体，例如 `https://你的域名.com，不要把 /wp-json` 或末尾斜杠也带进去。
常见报错：401、404、超时分别怎么查
401 Unauthorized 表示密钥或权限不对。
先检查密钥是否复制完整，尤其是结尾有没有漏字符；
再去 WooCommerce 后台看密钥状态，不是“已吊销”；
最后确认 ERP 系统里填的用户名是否真实存在。
404 Not Found 通常不是密钥问题，而是接口路径没有生效。
先直接访问 `https://你的域名.com/wp-json/wc/v3，如果浏览器能显示一段 JSON 说明基础路由正常；
如果 404，请到“设置 > 固定链接”里重新保存一次，再检查 Nginx 伪静态规则是否把 /wp-json` 重写掉了。
请求超时或连接失败，常见原因是服务器防火墙、安全组或 CDN 拦截。
测试外部连通性可以这么做：登录服务器，执行 `curl -I https://你的域名.com/wp-json/wc/v3，看到 HTTP/1.1 200` 就说明接口能被公网访问。
如果超时，重点查宝塔面板的系统防火墙、云服务商的安全组出口规则，以及 CDN 是否只允许国内访问。
用系统日志代替盲猜
ERP 后台有时只显示“同步失败”或“网络错误”，细节需要到服务端日志里看。
先开启 WooCommerce 自身日志：`WooCommerce > 状态 > 日志`，如果这里内容空白，直接看 Web 服务器日志。
用宝塔的话，可以实时追踪错误日志：
tail -f /www/wwwlogs/你的域名.error.log想单独测 WooCommerce API 是否正确，可以在服务器上用命令行模拟 ERP 的请求：
curl -u "消费者密钥:消费者密钥值" https://你的域名.com/wp-json/wc/v3/orders命令能正常返回订单 JSON，说明你的 WooCommerce API 本身没有问题，后续就要去检查 ERP 侧填写的字段、映射规则或同步接口版本。
避坑清单和同步效果验证
这里集中列出容易让新手绕远路的几个坑：
- SKU 不匹配：WooCommerce 商品编码和 ERP 里的 SKU 如果不一致，库存同步会失败，优先检查 ERP 的“商品映射”页面。
- 订单状态映射错位：WooCommerce 的“处理中”“完成”“退款”对应 ERP 里的状态码可能不同，需要到 ERP 的“订单状态映射”里手动对应。
- 时区导致日期错乱：服务器默认 UTC，ERP 使用东八区，订单时间会差 8 小时，建议在两边统一设置时区。
- 共用店铺互相覆盖：同一个 WooCommerce 同时对接多个平台或 ERP 时，注意订单来源字段和库存同步方向，防止互相覆盖。
配置完成后不要直接跑全量同步，建议先验证小数据量场景。
第一步，在 ERP 里手动拉取一个测试订单，核对金额、地址、商品明细是否与 WooCommerce 后台一致。
第二步，修改某个商品库存数量，等待 2 到 5 分钟，看店小秘或芒果店长是否刷新。
如果刷新延迟，检查 ERP 设置的定时同步间隔。
第三步，创建一个退款单，观察 WooCommerce 原订单状态能否同步更新。
这个环节最容易暴露映射错误，需要重点检查。
如果最后还是失败，请在 ERP 后台导出完整日志，同时把 WooCommerce API 返回的响应体保存下来，发给 ERP 技术客服。
调试思路就是：先确认 API 能通，再核对数据字段，最后检查业务映射规则。
按这个顺序走，大部分问题都能在十几分钟内定位。
如果你正在处理 WooCommerce ERP 对接，店小秘或芒果店长 API 接口调试踩坑，建议按“接口通没通 → 权限对不对 → 字段映射准不准”的顺序排查。
实际环境有差异时，优先看两边系统记录的原始返回，而不是猜配置项是否写错。
