无法通过Xero API创建银行交易：账户代码验证错误排查

问题详情 #

我们尝试通过Xero API创建银行交易，调用的curl请求如下：

curl --location --request POST 'https://api.xero.com/api.xro/2.0/BankTransactions' \
--header 'Authorization: Bearer ' \
--header 'Xero-Tenant-Id: ' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Cookie: ' \
--data-raw '{
   "bankTransactions":[ 
      {
         "type":"RECEIVE",
         "contact":{ 
            "contactID":"1db8660c-387a-45e9-943e-269a0fa9f6b39"
         },
         "lineItems":[ 
            {
               "description":"Foobar",
               "TaxType":"NONE",
               "quantity":1.0,
               "unitAmount":20.0,
               "accountCode":"4567"
            }
         ],
         "bankAccount":{ 
            "code":"4567"
         }
      }
   ]
}'

通过Get Account API获取到目标账户信息：

{
    "AccountID": "5aef5a57-f9f7-401f9-a627-30708840fb2",
    "Code": "4567",
    "Name": "Xero Integration",
    "Status": "ACTIVE",
    "Type": "BANK",
    "TaxType": "NONE",
    "Class": "ASSET",
    "EnablePaymentsToAccount": false,
    "ShowInExpenseClaims": false,
    "BankAccountNumber": "456789",
    "BankAccountType": "BANK",
    "CurrencyCode": "USD",
    "ReportingCode": "ASS.CUR.CAS.CAS",
    "ReportingCodeName": "Cash on hand",
    "HasAttachments": false,
    "UpdatedDateUTC": "/Date(1670594412700+0000)/",
    "AddToWatchlist": false
}

但收到验证错误：

"Account code '4567' is not a valid code for this document."

我们已多次核对账户代码，未发现问题，恳请告知错误原因及解决办法。

错误原因及解决办法 #

核心原因 #

1. lineItems账户类型错误：你在交易明细lineItems中使用了银行账户代码（4567），但lineItems的accountCode需要关联收入/费用类业务账户，而非银行账户。银行账户仅需在bankAccount字段中指定，用于记录资金最终流入的账户，交易明细需要对应业务相关的会计科目（比如销售收入账户）。
2. 银行账户接收权限未开启：目标银行账户的EnablePaymentsToAccount字段为false，该设置会阻止此账户接收付款类交易（RECEIVE类型），需要先在Xero后台开启权限。

具体解决步骤 #

步骤1：修正lineItems的账户代码

将lineItems中的accountCode替换为有效的收入类账户代码（可通过Get Account API获取所有ACTIVE状态的收入类账户）。

步骤2：开启银行账户的付款接收权限

1. 登录Xero后台，进入会计 > 账户页面
2. 找到代码为4567的银行账户，点击「编辑」
3. 勾选「允许付款至该账户」选项，保存设置

修正后的curl请求示例

curl --location --request POST 'https://api.xero.com/api.xro/2.0/BankTransactions' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Xero-Tenant-Id: YOUR_TENANT_ID' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
   "bankTransactions":[ 
      {
         "type":"RECEIVE",
         "contact":{ 
            "contactID":"1db8660c-387a-45e9-943e-269a0fa9f6b39"
         },
         "lineItems":[ 
            {
               "description":"Foobar",
               "TaxType":"NONE",
               "quantity":1.0,
               "unitAmount":20.0,
               "accountCode":"200" // 替换为你的收入类账户代码
            }
         ],
         "bankAccount":{ 
            "code":"4567"
         }
      }
   ]
}'

额外检查项 #

• 确认lineItems使用的账户类型为收入/费用/其他业务相关类型，而非银行账户
• 验证账户状态为ACTIVE，确保账户未被禁用
• 检查交易类型RECEIVE与账户货币（USD）匹配，避免跨币种交易冲突

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