如何通过PHP Webhook将Bitrix24指定线索迁移至目标阶段？

先解决crm.lead.list拿不到阶段ID的问题 #

默认调用crm.lead.list不会返回阶段相关字段，必须在select参数里明确指定STATUS_ID（阶段ID）和DATE_MODIFY（最后修改时间），才能获取到这些关键数据。

完整实现步骤 #

1. 获取目标阶段ID #

两种方式可以拿到目标阶段的ID：

• 后台直接查看：进入CRM设置 → 线索 → 状态，鼠标悬停在目标阶段上，浏览器地址栏中ID=后面的数字就是阶段ID。
• API调用获取：使用crm.status.list接口，过滤条件设为ENTITY_ID=LEAD，就能返回所有线索阶段的ID和名称。请求参数示例：

$statusParams = [
    'filter' => ['ENTITY_ID' => 'LEAD'],
    'select' => ['ID', 'NAME']
];

2. 筛选并迁移线索 #

以下是完整的PHP Webhook实现代码，包含分页处理和错误日志记录：

// 配置你的Bitrix24 Webhook信息
$webhookUrl = 'https://你的Bitrix24域名/rest/用户ID/你的Webhook密钥/';
$targetStatusId = '替换成你的目标阶段ID'; // 比如默认阶段"NEW"或自定义数字ID

// 计算10天前的UTC时间（Bitrix24 API统一使用UTC时间）
$tenDaysAgo = gmdate('c', strtotime('-10 days'));

// 初始化分页起始位置
$leadFilter = [
    'filter' => ['<DATE_MODIFY' => $tenDaysAgo],
    'select' => ['ID', 'STATUS_ID'],
    'start' => 0
];

do {
    // 获取符合条件的线索列表
    $response = file_get_contents($webhookUrl . 'crm.lead.list?' . http_build_query($leadFilter));
    $result = json_decode($response, true);
    
    if (empty($result['result'])) break;
    
    // 遍历线索，迁移到目标阶段
    foreach ($result['result'] as $lead) {
        // 跳过已在目标阶段的线索，避免重复操作
        if ($lead['STATUS_ID'] === $targetStatusId) continue;
        
        $updateData = [
            'id' => $lead['ID'],
            'fields' => ['STATUS_ID' => $targetStatusId]
        ];
        
        // 调用更新接口
        $updateResponse = file_get_contents($webhookUrl . 'crm.lead.update?' . http_build_query($updateData));
        $updateResult = json_decode($updateResponse, true);
        
        // 可选：记录更新失败的日志
        if (isset($updateResult['error'])) {
            error_log("线索ID {$lead['ID']} 更新失败：{$updateResult['error_description']}");
        }
    }
    
    // 更新分页起始位置，处理下一页数据
    $leadFilter['start'] = $result['next'];
} while ($result['next'] > 0);

关键注意事项 #

• 时区问题：必须使用UTC时间计算tenDaysAgo，代码中用gmdate确保时间格式符合Bitrix24 API要求，否则筛选结果会出错。
• 分页处理：Bitrix24 API默认每页返回50条数据，通过do-while循环可以处理所有符合条件的线索。
• Webhook权限：创建Webhook时必须勾选crm.lead.read和crm.lead.write权限，否则会返回权限不足的错误。

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