PHP调用QuickBooks API无法创建客户问题求助

核心问题定位 #

你已获取有效access token和realmId，但调用创建客户API返回Unexpected error: null且客户未创建，大概率是请求格式、头信息或API细节处理不当导致，以下是针对性排查和修复方案：

1. 检查请求体的JSON结构 #

QuickBooks API要求创建客户的请求体必须包裹在Customer顶层对象内，这是最常见的错误点。正确的请求体格式示例：

{
  "Customer": {
    "DisplayName": "Test Customer 001",
    "PrimaryEmailAddr": {
      "Address": "test_customer@example.com"
    }
  }
}

如果你的请求体直接写字段（比如漏了外层Customer键），API会因解析失败返回模糊错误。

2. 验证HTTP请求头完整性 #

必须确保以下关键请求头存在且正确：

• Authorization: Bearer {你的access_token}：注意Bearer后面有空格，token不能有多余字符
• Content-Type: application/json：强制指定请求体格式为JSON，缺失会导致API无法解析数据
• Accept: application/json：指定接收JSON格式响应
• Intuit-Realm-ID: {你的realmId}：部分沙箱端点需要显式传入该头

3. 确认沙箱API端点正确性 #

沙箱环境的客户创建端点是：

https://sandbox-quickbooks.api.intuit.com/v3/company/{realmId}/customer

不要误使用生产环境的端点（quickbooks.api.intuit.com）。

4. 开启cURL调试获取完整错误信息 #

添加调试选项到你的cURL代码，打印完整的请求日志和原始响应，能暴露隐藏的错误细节：

// 在curl_init后添加以下代码
curl_setopt($ch, CURLOPT_VERBOSE, true);
$verboseLog = fopen('php://temp', 'w+');
curl_setopt($ch, CURLOPT_STDERR, $verboseLog);

// 执行请求后读取调试日志
rewind($verboseLog);
echo "调试日志:\n" . stream_get_contents($verboseLog);
fclose($verboseLog);

通过日志你能看到实际发送的请求头、请求体，以及API返回的完整错误（可能不止Unexpected error: null）。

5. 检查access token的权限范围 #

确认你的OAuth授权scope包含com.intuit.quickbooks.accounting，没有该权限会导致创建客户操作被拒绝。你可以在获取token时检查请求的scope参数，或通过Intuit开发者平台查看token的权限详情。

修复后的完整示例代码 #

<?php
$accessToken = "你的access_token";
$realmId = "你的realmId";

// 沙箱API端点
$apiUrl = "https://sandbox-quickbooks.api.intuit.com/v3/company/{$realmId}/customer";

// 构造符合要求的请求体
$customerData = json_encode([
    "Customer" => [
        "DisplayName" => "Test Customer " . time(),
        "PrimaryPhone" => [
            "FreeFormNumber" => "123-456-7890"
        ],
        "PrimaryEmailAddr" => [
            "Address" => "test_" . time() . "@example.com"
        ]
    ]
]);

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $customerData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// 设置完整请求头
$headers = [
    "Authorization: Bearer {$accessToken}",
    "Content-Type: application/json",
    "Accept: application/json",
    "Intuit-Realm-ID: {$realmId}"
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

// 开启调试（可选，排查时使用）
curl_setopt($ch, CURLOPT_VERBOSE, true);
$verboseLog = fopen('php://temp', 'w+');
curl_setopt($ch, CURLOPT_STDERR, $verboseLog);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// 输出调试信息
echo "HTTP状态码: " . $httpCode . "\n";
echo "API响应: " . $response . "\n";

rewind($verboseLog);
echo "调试日志:\n" . stream_get_contents($verboseLog);
fclose($verboseLog);

curl_close($ch);
?>

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