Perfex CRM API创建线索报错：必填字段缺失问题排查求助

问题代码 #

$api_key = "mytoken";
$url = "https://mysite/api/leads";

$data = array(
    "first_name" => "John",
    "last_name" => "Doe",
    "email" => "john.doe@example.com",
    "phone" => "1234567890",
    "company" => "Example Inc.",
    "source" => "New Site",
    "status" => "New"
);
$data_json = json_encode($data);

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_json);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "Authtoken: ".$api_key
));
$response = curl_exec($curl);
$status_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($status_code == 201) {
    echo "New lead created successfully.";
} else {
    echo "Error creating new lead. Status code: ".$status_code;
}

错误响应 #

{
"status":   false,
"error":
    {   "name":"The Lead Name field is required.",
        "source":"The Source field is required.",
        "status":"The Status field is required."
    },
"message": "The Lead Name field is required. The Source field is required. The Status field is required."
} 

排查方向及解决方案 #

1. 修正name字段格式 #

错误提示明确要求name字段必填，但代码中拆分了first_name和last_name。Perfex CRM的创建线索API通常需要合并的name字段，而非分开的名和姓。将代码中的first_name和last_name替换为name字段：

"data" => array(
    "name" => "John Doe", // 合并姓名
    // 其他字段保留
)

2. 替换source和status为对应ID #

API提示这两个字段必填，但传入的是文本名称（如"New Site"、"New"）。Perfex CRM的这类字段通常要求传入后台配置的数字ID，而非显示名称：

• 登录Perfex CRM后台，查看线索来源（Leads > Sources）和线索状态（Leads > Statuses）的对应ID
• 将代码中的source和status值替换为对应的数字ID，例如：

"source" => 1, // 替换为实际来源ID
"status" => 1 // 替换为实际状态ID

3. 验证认证请求头 #

部分Perfex CRM版本的API使用X-API-KEY而非Authtoken作为认证头，尝试修改请求头：

curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "X-API-KEY: ".$api_key
));

4. 添加调试输出 #

在代码中打印完整响应内容，便于获取更详细的错误细节：

// 执行请求后添加
var_dump($response);

修改后示例代码 #

$api_key = "mytoken";
$url = "https://mysite/api/leads";

$data = array(
    "name" => "John Doe",
    "email" => "john.doe@example.com",
    "phone" => "1234567890",
    "company" => "Example Inc.",
    "source" => 1, // 替换为后台实际来源ID
    "status" => 1 // 替换为后台实际状态ID
);
$data_json = json_encode($data);

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_json);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "X-API-KEY: ".$api_key
));
$response = curl_exec($curl);
$status_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

// 调试用：打印响应内容
var_dump($response);

if ($status_code == 201) {
    echo "New lead created successfully.";
} else {
    echo "Error creating new lead. Status code: ".$status_code;
}

内容的提问来源于stack exchange，提问作者graf-8269