QBXML（QuickBooks Desktop API）批量添加多个Time Activities的正确结构

我的Web应用通过QuickBooks Web Connector与QuickBooks Desktop通信，单个时间条目添加可成功执行，QBXML结构如下：

<?xml version="1.0" encoding="utf-8"?>
<?qbxml version="6.0"?>
<QBXML>
    <QBXMLMsgsRq onError="stopOnError">
        <TimeTrackingAddRq requestID="100">
            <TimeTrackingAdd>
                <TxnDate>2022-10-22</TxnDate>
                
                <EntityRef>
                    <ListID>8000000F-1661995835</ListID>
                </EntityRef>
                
                <CustomerRef>
                    <ListID>80000007-1654551468</ListID>
                </CustomerRef>
                
                <ItemServiceRef>
                    <ListID>80000008-1654552326</ListID>
                </ItemServiceRef>
                
                <Duration>PT1H0M</Duration>
                
                <PayrollItemWageRef>
                    <ListID>80000009-1654190217</ListID>
                </PayrollItemWageRef>
                
                <Notes>Test Note</Notes>

                <BillableStatus>Billable</BillableStatus>
            </TimeTrackingAdd>
        </TimeTrackingAddRq>
    </QBXMLMsgsRq>
</QBXML>

该结构符合Intuit的TimeTrackingAdd请求规范，但尝试批量添加时（直接重复<TimeTrackingAdd>节点），收到错误：QuickBooks found an error when parsing the provided XML text stream.，失败的批量请求QBXML如下：

<?xml version="1.0" encoding="utf-8"?>
<?qbxml version="6.0"?>
<QBXML>
    <QBXMLMsgsRq onError="stopOnError">
        <TimeTrackingAddRq requestID="100">
            <TimeTrackingAdd>
                <TxnDate>2022-10-22</TxnDate>
                
                <EntityRef>
                    <ListID>8000000F-1661995835</ListID>
                </EntityRef>
                
                <CustomerRef>
                    <ListID>80000007-1654551468</ListID>
                </CustomerRef>
                
                <ItemServiceRef>
                    <ListID>80000008-1654552326</ListID>
                </ItemServiceRef>
                
                <Duration>PT1H0M</Duration>
                
                <PayrollItemWageRef>
                    <ListID>80000009-1654190217</ListID>
                </PayrollItemWageRef>
                
                <Notes>Test Note</Notes>

                <BillableStatus>Billable</BillableStatus>
            </TimeTrackingAdd>
            <TimeTrackingAdd>
                <TxnDate>2022-10-23</TxnDate>
                
                <EntityRef>
                    <ListID>8000000F-1661995835</ListID>
                </EntityRef>
                
                <CustomerRef>
                    <ListID>80000007-1654551468</ListID>
                </CustomerRef>
                
                <ItemServiceRef>
                    <ListID>80000008-1654552326</ListID>
                </ItemServiceRef>
                
                <Duration>PT2H0M</Duration>
                
                <PayrollItemWageRef>
                    <ListID>80000009-1654190217</ListID>
                </PayrollItemWageRef>
                
                <Notes>Test Note</Notes>

                <BillableStatus>Billable</BillableStatus>
            </TimeTrackingAdd>
        </TimeTrackingAddRq>
    </QBXMLMsgsRq>
</QBXML>

使用QB XML Validator（QuickBooks SDK v15.0）验证时，还会报错：Error during validation: D, Conversion from string "Line: 31 LinePos: 21 Src Text:" to type 'Double' is not valid.。原以为此方法和发票ADD请求一样支持批量，但找不到批量TimeTrackingAdd请求的示例，现寻求正确QBXML或解决方法，需实现高效处理工时表并保证原子性（单个工时表的所有时间条目要么全部成功，要么全部失败）。

解决方法与正确QBXML示例 #

错误原因 #

TimeTrackingAddRq节点下仅允许包含一个<TimeTrackingAdd>子节点，无法通过直接重复该节点实现批量。正确的批量方式是为每个时间条目创建独立的TimeTrackingAddRq节点，同时利用QBXMLMsgsRq的onError="stopOnError"属性保证原子性。

正确的批量QBXML示例 #

<?xml version="1.0" encoding="utf-8"?>
<?qbxml version="6.0"?>
<QBXML>
    <QBXMLMsgsRq onError="stopOnError">
        <!-- 第一个时间条目请求 -->
        <TimeTrackingAddRq requestID="100">
            <TimeTrackingAdd>
                <TxnDate>2022-10-22</TxnDate>
                <EntityRef>
                    <ListID>8000000F-1661995835</ListID>
                </EntityRef>
                <CustomerRef>
                    <ListID>80000007-1654551468</ListID>
                </CustomerRef>
                <ItemServiceRef>
                    <ListID>80000008-1654552326</ListID>
                </ItemServiceRef>
                <Duration>PT1H0M</Duration>
                <PayrollItemWageRef>
                    <ListID>80000009-1654190217</ListID>
                </PayrollItemWageRef>
                <Notes>Test Note</Notes>
                <BillableStatus>Billable</BillableStatus>
            </TimeTrackingAdd>
        </TimeTrackingAddRq>
        <!-- 第二个时间条目请求 -->
        <TimeTrackingAddRq requestID="101">
            <TimeTrackingAdd>
                <TxnDate>2022-10-23</TxnDate>
                <EntityRef>
                    <ListID>8000000F-1661995835</ListID>
                </EntityRef>
                <CustomerRef>
                    <ListID>80000007-1654551468</ListID>
                </CustomerRef>
                <ItemServiceRef>
                    <ListID>80000008-1654552326</ListID>
                </ItemServiceRef>
                <Duration>PT2H0M</Duration>
                <PayrollItemWageRef>
                    <ListID>80000009-1654190217</ListID>
                </PayrollItemWageRef>
                <Notes>Test Note</Notes>
                <BillableStatus>Billable</BillableStatus>
            </TimeTrackingAdd>
        </TimeTrackingAddRq>
    </QBXMLMsgsRq>
</QBXML>

关键要点 #

• 每个时间条目必须封装在独立的<TimeTrackingAddRq>节点中，且每个节点的requestID需唯一
• 保持<QBXMLMsgsRq onError="stopOnError">配置：一旦某条请求失败，后续请求会终止，已执行的请求会自动回滚，确保原子性
• 注意QBXML版本需与你的QuickBooks Desktop版本兼容

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