Bitrix24 API：如何更新CRM商机文件类型自定义字段

嘿，刚好对这个场景熟得很！Bitrix24里的文件类自定义字段更新逻辑有点特殊——不能直接传文件内容，得先把文件传到Bitrix的文件存储里拿到ID，再把这个ID赋值给字段。下面一步步给你讲清楚：

第一步：先把文件上传到Bitrix24的存储系统 #

你得先调用disk.file.upload接口（或者用CRM专属的crm.document.upload，前者更通用）完成上传。这里要注意几个点：

• 确保你的API令牌有disk或者crm相关的权限，不然会被拒
• 可以选择上传到临时目录（用PARENT_ID: -1），或者指定你有权限的文件夹

给你个PHP的示例代码，其他语言逻辑一样：

// 替换成你的Bitrix24域名和API令牌
$bitrixApiEndpoint = 'https://your-bitrix-domain.bitrix24.ru/rest/123/your-api-token-here/';
$targetFilePath = '/local/path/to/your/document.pdf';

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $bitrixApiEndpoint . 'disk.file.upload',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'data' => json_encode([
            'NAME' => 'my-uploaded-file.pdf',
            'PARENT_ID' => -1, // 上传到临时存储，不用管后续清理
        ]),
        'file' => new CURLFile($targetFilePath)
    ]
]);

$uploadResult = json_decode(curl_exec($curl), true);
curl_close($curl);

// 提取上传后的文件ID，这是关键！
$uploadedFileId = $uploadResult['result']['ID'];

第二步：用文件ID更新商机的自定义字段 #

拿到文件ID后，调用crm.deal.update接口就行。这里要特别注意：文件字段的值必须是数组格式，哪怕你只传一个文件也要用数组包起来。

假设你的自定义字段代码是UF_CRM_1689012345（这个可以在CRM设置→自定义字段→商机里查到），示例代码：

$dealIdToUpdate = 456; // 你要更新的商机ID
$updateFields = [
    'UF_CRM_1689012345' => [$uploadedFileId] // 数组格式！
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $bitrixApiEndpoint . 'crm.deal.update',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'id' => $dealIdToUpdate,
        'fields' => json_encode($updateFields)
    ]
]);

$updateResult = json_decode(curl_exec($curl), true);
curl_close($curl);

// 检查更新是否成功
if ($updateResult['result']) {
    echo "商机的文件字段更新成功啦！";
} else {
    echo "更新失败：" . $updateResult['error_description'];
}

几个要踩的坑提前提醒你 #

• 如果是要上传多个文件，就把多个文件ID放到数组里，比如[$fileId1, $fileId2, $fileId3]
• 一定要确认你的自定义字段类型是文件，不是其他类型，不然传了也白传
• 要是上传到指定文件夹，得确保你的API用户有那个文件夹的写入权限，不然会报错
• 临时目录的文件Bitrix会自动清理，要是想长期保存，就上传到固定文件夹

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