Xero API：updateOrCreateInvoices接口覆盖联系人详情问题求助

问题背景 #

使用PHP(OAuth2)对接Xero Accounting API，通过updateOrCreateInvoices接口同步交易数据时，每次调用接口都会导致联系人详情中的**"additional persons"字段**被覆盖或清空。

接口行为逻辑 #

Xero的updateOrCreateInvoices接口处理发票关联联系人时，遵循全量覆盖逻辑：

• 若请求中传入完整的联系人对象（包含ContactID外的其他字段），接口会用传入的对象信息覆盖Xero已有的联系人记录，而非增量更新。
• 当你从Xero获取完整联系人对象传入接口时，若该对象未包含"additional persons"字段（比如API返回数据默认不携带、或获取时遗漏），接口会判定为需要清空该字段的值。

解决方案 #

要避免联系人信息被修改，只需在发票的联系人关联中仅传入ContactID，而非完整的联系人对象。这样Xero只会完成发票与已有联系人的关联，不会修改联系人的任何详情字段。

修改前的代码片段 #

public function create_or_update_invoice($xero_tenant_id, $api_instance, $invoice_list = array()){
    $arr_invoices = array();
    foreach ($invoice_list as $invoice) {
        // 获取完整联系人详情
        $contact = $this->get_contact_by_id($xero_tenant_id, $api_instance, $xero_contact_id, $contact_name);
    
        // 组装发票数据
        $new_invoice = new XeroAPI\XeroPHP\Models\Accounting\Invoice;
        $new_invoice->setType(XeroAPI\XeroPHP\Models\Accounting\Invoice::TYPE_ACCREC)
        ->setContact($contact)
        ...
        ...
        ->setStatus(XeroAPI\XeroPHP\Models\Accounting\Invoice::STATUS_AUTHORISED);
    
        $arr_invoices[] = $new_invoice;
    }

    $invoices = new XeroAPI\XeroPHP\Models\Accounting\Invoices;
    $invoices->setInvoices($arr_invoices);

    try{
        $result = $api_instance->updateOrCreateInvoices($xero_tenant_id, $invoices); 
        return $result;
    }catch(Exception $e){
        return $e;
    }
}

修改后的代码片段 #

public function create_or_update_invoice($xero_tenant_id, $api_instance, $invoice_list = array()){
    $arr_invoices = array();
    foreach ($invoice_list as $invoice) {
        // 仅创建包含ContactID的联系人对象
        $contact = new XeroAPI\XeroPHP\Models\Accounting\Contact;
        $contact->setContactID($xero_contact_id);
    
        // 组装发票数据
        $new_invoice = new XeroAPI\XeroPHP\Models\Accounting\Invoice;
        $new_invoice->setType(XeroAPI\XeroPHP\Models\Accounting\Invoice::TYPE_ACCREC)
        ->setContact($contact)
        ...
        ...
        ->setStatus(XeroAPI\XeroPHP\Models\Accounting\Invoice::STATUS_AUTHORISED);
    
        $arr_invoices[] = $new_invoice;
    }

    $invoices = new XeroAPI\XeroPHP\Models\Accounting\Invoices;
    $invoices->setInvoices($arr_invoices);

    try{
        $result = $api_instance->updateOrCreateInvoices($xero_tenant_id, $invoices); 
        return $result;
    }catch(Exception $e){
        return $e;
    }
}

效果说明 #

仅传入ContactID后，接口仅完成发票与联系人的关联操作，不会对联系人的任何字段（包括"additional persons"）进行修改，确保了联系人信息的完整性。

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