API 同步常见问题排查
1. 「连接测试失败」
可能原因：
- API Key 复制时多了空格 → 重新生成一个 Key，仔细粘贴
- API Key 权限不够 → 检查是否勾选了对应的写权限
- AIAccount 公司编号填错 → 在 AIAccount 设置首页查看公司 ID
- 对方系统访问 AIAccount 的网络被防火墙拦截 → 联系我们提供白名单 IP
2. 「同步成功，但 AIAccount 看不到记录」
检查清单：
- 查看是否被推送到了错误公司（如果你有多家公司账号）
- 检查会计期间是否已锁定 — 锁定期间内的新记录会被拒绝
- 看「集成日志」（设置 → 集成 → 日志），找最近的失败记录
3. 「科目映射错误，记到了错误的账户」
登入对方系统的会计集成设置，重新配置映射关系。已经推送过的记录不会自动调整，需要在 AIAccount 端手动重分类。
4. 「重复入账」
每个 API 推送都带有幂等键，重复推送同一个键的请求会被拒绝。如果真的看到重复，可能是：
- 对方系统更新了订单 ID 但没更新幂等键
- 同时配置了 API 同步和 Excel 导入 — 关掉一个
5. 「金额对不上」（差 1 仙）
多半是舍入差异。AIAccount 默认按「按行项目舍入再加总」，对方系统可能按「先加总再舍入」。在集成设置选择和对方系统一致的舍入方式即可。
6. 「e-Invoice 提交失败」
常见原因：
- 客户 TIN 编号格式错 → 检查格式是否符合 LHDN 规范
- 商品分类码缺失 → 在 AIAccount 设置默认的分类码
- 金额超过 RM 10,000 但客户信息不完整 → 补全买方资料
7. 「库存数量不对」
NetShop 退货后库存应该回补但没回补？
- 检查 NetShop 退货状态是否为「已退款 + 已收回商品」— 只退款未收回不回补库存
- SKU 在两边是否完全一致（大小写、空格、特殊符号）
8. 「同步延迟超过 10 分钟」
正常情况下应在 10 秒内。延迟超过 10 分钟通常是：
- 对方系统的待重试队列堵塞 — 联系对方客服
- AIAccount 公司账户超额（如试用版超过 100 笔/月）
9. 「想暂停同步」
在 AIAccount → 设置 → 集成 → API Keys，把对应 Key 的状态切换为「暂停」。暂停期间对方系统的推送会被拒绝但缓存，恢复后自动重新发送。
10. 「想换一个 API Key」
- 新建一个新 Key
- 在对方系统更新 Key
- 测试连接成功后，把旧 Key 设为「禁用」（不要立刻删除，保留 7 天审计）
找不到答案？
WhatsApp 我们：+60 11 1880 3744，附上集成日志截图，技术团队 24 小时内回复。