Laravel中Xero AccountingApi正常但PayrollApi调用401授权失败

问题描述 #

在Laravel环境中调用Xero Payroll UK API创建员工时，收到401未授权错误，错误详情：

[401] Client error: POST https://api.xero.com/payroll.xro/2.0/Employees resulted in a 401 Unauthorized response: {"Type":null,"Title":"Unauthorized","Status":401,"Detail":"AuthorizationUnsuccessful","Instance":"d283e208-b86a-4739-a18 (truncated...)

当前Xero配置可正常支持AccountingApi，示例代码如下：

public function getAllTaxTypes(OauthCredentialManager $xeroCredentials){
    $apiInstance = resolve(\XeroAPI\XeroPHP\Api\AccountingApi::class);
    $taxTypes = $apiInstance->getTaxRates($xeroCredentials->getTenantId());
    dd($taxTypes);
}

该代码能正常输出税率信息，但调用以下创建员工的代码时触发401错误：

public function createEmployee(OauthCredentialManager $xeroCredentials){
    $apiInstance = resolve(\XeroAPI\XeroPHP\Api\PayrollUkApi::class);
    $xeroTenantId = $xeroCredentials->getTenantId();

    $employee = new Employee();
    $employee->setFirstName('jhon');
    $employee->setLastName('doe');

    $response = $apiInstance->createEmployee($xeroTenantId, $employee);
    dd($response);
}

可能的原因及解决方法 #

• Payroll API权限缺失
  Xero的Accounting API与Payroll API为独立授权模块，即使应用拥有Accounting权限，也可能未配置Payroll UK相关权限：

  1. 登录Xero开发者后台，找到对应应用
  2. 检查权限设置，确认已勾选payroll.uk相关权限（如payroll.uk.employees）
  3. 若新增权限，需重新引导用户完成应用授权流程，确认权限同意

• 租户无Payroll服务订阅
  确认当前使用的Xero租户（Tenant）已订阅Payroll UK服务，无订阅租户无法访问Payroll API，可联系租户管理员核实订阅状态。

• API实例初始化验证
  可显式传入凭证初始化PayrollUkApi实例，避免依赖容器自动解析的潜在问题：

  $config = XeroAPI\XeroPHP\Configuration::getDefaultConfiguration()
      ->setAccessToken($xeroCredentials->getToken());
  $apiInstance = new \XeroAPI\XeroPHP\Api\PayrollUkApi(
      new GuzzleHttp\Client(),
      $config
  );
  

• OAuth凭证范围不匹配
  检查OAuth凭证的scope字段，确认包含payroll.uk相关权限。可通过打印$xeroCredentials->getToken()查看scope值，若缺失需重新授权更新权限范围。

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