多次编辑QuickBooks Desktop销售订单遇QBWC 3200编辑序列过期错误

问题背景 #

尝试编辑QuickBooks Desktop中的销售订单，提交QBXML修改请求后触发编辑序列过期错误，且对SyncToken的使用存在疑问。

提交的QBXML修改请求 #

<?xml version="1.0" encoding="ISO-8859-1"?>
<?qbxml version="13.0"?>
<QBXML>
  <QBXMLMsgsRq onError="stopOnError">
    <SalesOrderModRq>
      <SalesOrderMod>
        <TxnID>AE5-xxxxx</TxnID>
        <EditSequence>xxxxxxx</EditSequence>
        <CustomerRef>
          <FullName>R.M.H:Winterstone:Test DRIVE</FullName>
        </CustomerRef>
        <TxnDate>2023-02-20</TxnDate>
        <BillAddress>
          <Addr1>123</Addr1>
          <Addr2></Addr2>
          <City>TAMPA</City>
          <State>Florida</State>
          <PostalCode>33618</PostalCode>
          <Country>United States</Country>
        </BillAddress>
        <PONumber>204392</PONumber>
        <Other>Summerstone</Other>
        <SalesOrderLineMod>
          <TxnLineID>AE7-xxxx</TxnLineID>
          <ItemRef>
            <FullName>Single Family</FullName>
          </ItemRef>
          <Desc>Test Line 1 </Desc>
          <Quantity>1</Quantity>
          <Amount>85.00</Amount>
        </SalesOrderLineMod>
      </SalesOrderMod>
    </SalesOrderModRq>
  </QBXMLMsgsRq>
</QBXML>

触发的错误信息 #

QBWC ERROR: 3200 - The provided edit sequence "xxxxxx" is out-of-date.

查询到的目标销售订单响应数据 #

{"xml_attributes"=>{"requestID"=>"1", "statusCode"=>"0", "statusSeverity"=>"Info", "statusMessage"=>"Status OK"},
 "sales_order_ret"=>
  [{"xml_attributes"=>{},
    "txn_id"=>"6F-xxxxx",
    "time_created"=>"2022-06-28T18:33:04-05:00",
    "time_modified"=>"2022-06-28T18:37:19-05:00",
    "edit_sequence"=>"xxxxx",
    "txn_number"=>13,
    "customer_ref"=>{"xml_attributes"=>{}, "list_id"=>"80000004-xxxx", "full_name"=>"R.M.H:Winterstone:Test DRIVE"},
    "template_ref"=>{"xml_attributes"=>{}, "list_id"=>"80000008-xxxx", "full_name"=>"Custom Sales Order"},
    "txn_date"=>"2022-06-28",
    "ref_number"=>"11",
    "bill_address"=>{"xml_attributes"=>{}, "addr1"=>"123", "city"=>"zz", "state"=>"FL", "postal_code"=>"33z618", "country"=>"zzz"},
    "bill_address_block"=>{"xml_attributes"=>{}, "addr1"=>"123", "addr2"=>"sds, sdsd sdsd", "addr3"=>"Unsditsded Statsdes"},
    "po_number"=>"204391",
    "due_date"=>"xxxx",
    "ship_date"=>"xxxx",
    "subtotal"=>85.0,
    "sales_tax_percentage"=>0.0,
    "sales_tax_total"=>0.0,
    "total_amount"=>85.0,
    "is_manually_closed"=>false,
    "is_fully_invoiced"=>true,
    "is_to_be_printed"=>true,
    "is_to_be_emailed"=>false,
    "other"=>"xxxxx",
    "sales_order_line_ret"=>
     {"xml_attributes"=>{},
      "txn_line_id"=>"xxxxxxx",
      "item_ref"=>{"xml_attributes"=>{}, "list_id"=>"80000004-1650461887", "full_name"=>"Single Family"},
      "desc"=>"Test Line 1",
      "quantity"=>#<BigDecimal:7fb52e8c48b8,'0.1E1',9(18)>,
      "rate"=>85.0,
      "amount"=>85.0,
      "sales_tax_code_ref"=>{"xml_attributes"=>{}, "list_id"=>"80000002-xxxxx", "full_name"=>"Non"},
      "invoiced"=>#<BigDecimal:7fb533636088,'0.1E1',9(18)>,
      "is_manually_closed"=>false}},]

解决方案要点 #

• 区分EditSequence和SyncToken：QuickBooks Desktop使用EditSequence字段做并发控制，而SyncToken是QuickBooks Online的专属字段，你完全不需要找SyncToken，直接用查询返回的edit_sequence值即可。
• 必须使用最新的EditSequence：
  • 每次修改前务必重新查询目标订单，获取当前最新的edit_sequence值，绝对不能使用缓存的旧值——任何对订单的修改（包括手动修改、其他集成修改）都会更新这个值。
  • 确保请求中的EditSequence（驼峰写法）与查询返回的edit_sequence（蛇形写法）值完全一致，注意大小写和字符匹配。
• 检查订单状态限制：从查询结果看，该订单is_fully_invoiced为true（已全额开票），QuickBooks Desktop默认不允许修改已全额开票的销售订单，你需要先取消关联的发票，或者调整QuickBooks的权限设置。
• 核对核心ID字段：确认请求中的TxnID（订单ID）和TxnLineID（行项目ID）与查询返回的txn_id、txn_line_id完全匹配，没有拼写错误或ID混淆。
• 标准重试流程：
  1. 发送SalesOrderQueryRq获取目标订单的最新完整数据；
  2. 立即用最新的edit_sequence、txn_id、txn_line_id构建SalesOrderModRq请求；
  3. 提交修改请求，避免中间有其他操作修改该订单。

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