xero-node调用createContacts创建联系人无法写入brandingTheme等字段

API 探路者

2026-9-3

问题原因

xero-node SDK的Contact类型定义没有区分字段的操作权限，把「只读返回字段」「创建可写字段」「更新可写字段」做了合并，你传入的brandingTheme、salesDefaultLineAmountType两个字段不属于createContacts接口的入参白名单，Xero API对不在白名单的入参字段默认做静默丢弃处理，不会抛错，所以最终只保存了创建接口支持的name和accountNumber。
额外注意：brandingTheme关联本身要求品牌主题ID必须归属于当前传入的租户ID，如果ID无效、跨租户或者已被删除，哪怕走更新接口传入也会被静默忽略。

处理方案

拆分创建和配置两步操作，创建联系人时只传createContacts接口支持的基础字段，拿到创建成功后返回的contactID，示例代码：

const create_contact: Contact = {
  accountNumber: '******',
  name: '*******',
};
const createRes = await xero.accountingApi.createContacts('myTenantId', {
  contacts: [create_contact]
});
const savedContact = createRes.body.contacts?.[0];
if (!savedContact?.contactID) {
  throw new Error('联系人创建失败，未返回有效contactID');
}

提前校验品牌主题ID有效性，调用xero.accountingApi.getBrandingThemes('myTenantId')拉取当前租户下的所有有效品牌主题，确认你要绑定的brandingThemeID在返回列表中。
调用单联系人更新接口，传入contactID和需要补充的两个配置字段完成设置，示例代码：

const update_contact: Contact = {
  contactID: savedContact.contactID,
  brandingTheme: {
    brandingThemeID: '********-****-****-****-************',
  },
  salesDefaultLineAmountType: SalesDefaultLineAmountTypeEnum.EXCLUSIVE
};
await xero.accountingApi.updateContact(
  'myTenantId',
  savedContact.contactID,
  update_contact
);