使用Xero API按发票号查询无结果但创建时提示重复的问题

可能原因与排查步骤 #

• 状态过滤遗漏：默认的GET /Invoices请求仅返回特定状态的发票（如已授权状态），但重复的发票号可能存在于草稿、已删除或作废状态中。查询时必须指定覆盖所有状态的参数：

  GET /Invoices?InvoiceNumber=INV-123&Statuses=AUTHORISED,DRAFT,DELETED,VOIDED
  

• 组织权限范围：确认API令牌是否覆盖所有关联的Xero组织，重复发票可能存在于当前查询未涉及的组织内。
• 系统同步延迟：极少数情况下Xero数据库存在同步延迟，导致查询请求无法实时获取最新记录。可在创建前增加1-2秒的重试查询，或使用If-Match头进行并发控制。
• 格式匹配问题：检查查询的发票号是否严格匹配大小写、特殊符号（如连字符、空格），Xero的发票号匹配为大小写敏感。

临时处理流程 #

若上述排查无效，可调整业务逻辑：

1. 先发起创建发票的PUT请求，捕获Invoice # must be unique.错误
2. 触发该错误时，立即执行全状态查询获取对应发票，再进行更新操作
3. 若查询仍无结果，直接记录异常并手动在Xero后台搜索该发票号，排查系统级异常记录

额外注意 #

• 确保使用最新版Xero API（v2），旧版本存在查询逻辑缺陷的概率更高
• 直接登录Xero后台手动搜索发票号，确认是否存在隐藏状态的记录

内容的提问来源于stack exchange，提问作者JasonArd