[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-recipes\u002Fcrm-files":3,"docs-tabs-recipes\u002Fcrm-files":6},{"content":4,"lastmod":5},"# Работа с файлами в полях CRM\n\n**Сложность:** medium | **Скоупы:** crm | **Стек:** cURL \u002F Node.js \u002F PHP\n\n## Что делаем\n\nЧитаем, скачиваем и записываем файлы в пользовательских полях типа «Файл» у сущностей CRM, которые работают через `crm.item.*`.\n\n## Два типа файловых полей\n\nВ Битрикс24 есть два разных типа файловых полей, и работают они по-разному.\n\n- **«Файл»** — поле не связано с Диском. Содержимое хранится в самом поле. Эта страница про него.\n- **«Файл (диск)»** — поле ссылается на объект Диска. С такими файлами работают через эндпоинты `\u002Fv1\u002Ffiles\u002F*`, см. [Работа с файлами Диска](.\u002Fdisk-files.md).\n\nТип поля виден в ответе `GET \u002Fv1\u002F{entity}\u002Ffields`.\n\n## Где применимо\n\nМеханика одинакова для всех сущностей CRM на `crm.item.*`.\n\n- [Сделки](..\u002Fentities\u002Fdeals.md) — `GET \u002F PATCH \u002Fv1\u002Fdeals\u002F:id`\n- [Лиды](..\u002Fentities\u002Fleads.md) — `GET \u002F PATCH \u002Fv1\u002Fleads\u002F:id`\n- [Контакты](..\u002Fentities\u002Fcontacts.md) — `GET \u002F PATCH \u002Fv1\u002Fcontacts\u002F:id`\n- [Компании](..\u002Fentities\u002Fcompanies.md) — `GET \u002F PATCH \u002Fv1\u002Fcompanies\u002F:id`\n- [Предложения](..\u002Fentities\u002Fquotes.md) — `GET \u002F PATCH \u002Fv1\u002Fquotes\u002F:id`\n- [Счета](..\u002Fentities\u002Finvoices.md) — `GET \u002F PATCH \u002Fv1\u002Finvoices\u002F:id`\n- [Смарт-процессы](..\u002Fentities\u002Fitems.md) — `GET \u002F PATCH \u002Fv1\u002Fitems\u002F:entityTypeId\u002F:id`\n\n## Имя поля\n\nИмя файлового поля имеет вид `ufCrm_\u003Cкод>`. Точное имя и признак множественности возвращает `GET \u002Fv1\u002F{entity}\u002Ffields`.\n\n## Как поле выглядит в ответе\n\n`GET \u002Fv1\u002Fdeals\u002F:id` возвращает файловое поле массивом объектов.\n\n```json\n{\n  \"ufCrm_1a2b3c\": [\n    {\n      \"id\": 35845,\n      \"url\": \"https:\u002F\u002Fportal.bitrix24.ru\u002Fbitrix\u002Fservices\u002Fmain\u002Fajax.php?action=crm.controller.item.getFile&entityTypeId=2&id=100&fieldName=UF_CRM_1A2B3C&fileId=35845\",\n      \"urlMachine\": \"https:\u002F\u002Fportal.bitrix24.ru\u002Frest\u002F1\u002FWEBHOOK\u002Fcrm.controller.item.getFile\u002F?token=...\"\n    }\n  ]\n}\n```\n\nВ каждом объекте два адреса для разных задач.\n\n- **`url`** — для открытия в браузере. Требует активной сессии пользователя.\n- **`urlMachine`** — для программного скачивания. Авторизация включена в сам адрес.\n\n## Скачать файл\n\nВозьмите `urlMachine` из ответа и выполните по нему `GET`. В ответе придёт бинарное содержимое файла.\n\n```bash\ncurl -s -o result.pdf \"URL_MACHINE_FROM_RESPONSE\"\n```\n\n```javascript\nimport { writeFile } from 'node:fs\u002Fpromises'\n\nconst res = await fetch(urlMachine)\nawait writeFile('result.pdf', Buffer.from(await res.arrayBuffer()))\n```\n\n```php\n\u003C?php\nfile_put_contents('result.pdf', file_get_contents($urlMachine));\n```\n\nДля ключа-вебхука авторизация вшита в адрес и работает сразу. Для ключа OAuth-приложения адрес действует ограниченное время. Скачивайте файл сразу после чтения записи, а если прошло время, перечитайте запись и возьмите свежий `urlMachine`.\n\n## Записать файл\n\nФайл передаётся парой из имени и содержимого в формате base64.\n\nОдиночное поле принимает одну пару.\n\n```json\n{ \"ufCrm_1a2b3c\": [\"contract.pdf\", \"BASE64_CONTENT\"] }\n```\n\nМножественное поле принимает массив пар.\n\n```json\n{ \"ufCrm_1a2b3c\": [[\"contract.pdf\", \"BASE64_CONTENT\"], [\"act.pdf\", \"BASE64_CONTENT\"]] }\n```\n\nПризнак множественности возвращает `GET \u002Fv1\u002F{entity}\u002Ffields`. Примеры ниже показывают множественное поле. Для одиночного поля передайте одну пару без внешнего массива.\n\n```bash\ncurl -s -X PATCH -H \"X-Api-Key: YOUR_API_KEY\" -H \"Content-Type: application\u002Fjson\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\u002F100\" \\\n  -d '{\"ufCrm_1a2b3c\": [[\"contract.pdf\", \"BASE64_CONTENT\"]]}'\n```\n\n```javascript\nawait fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\u002F100', {\n  method: 'PATCH',\n  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application\u002Fjson' },\n  body: JSON.stringify({ ufCrm_1a2b3c: [['contract.pdf', base64Content]] }),\n})\n```\n\n```php\n\u003C?php\n$ch = curl_init('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\u002F100');\ncurl_setopt_array($ch, [\n  CURLOPT_CUSTOMREQUEST => 'PATCH',\n  CURLOPT_HTTPHEADER => ['X-Api-Key: YOUR_API_KEY', 'Content-Type: application\u002Fjson'],\n  CURLOPT_POSTFIELDS => json_encode([\n    'ufCrm_1a2b3c' => [['contract.pdf', $base64Content]],\n  ]),\n  CURLOPT_RETURNTRANSFER => true,\n]);\n$response = curl_exec($ch);\ncurl_close($ch);\n```\n\nТело запроса ограничено 1 МБ, а base64 увеличивает размер примерно на треть, поэтому практический предел одного файла — около 750 КБ. Для больших файлов используйте поле «Файл (диск)» и загрузку на Диск.\n\nЧтобы сохранить уже прикреплённые файлы и добавить новый, передайте идентификаторы существующих файлов вместе с новой парой.\n\n```json\n{ \"ufCrm_1a2b3c\": [{ \"id\": 35845 }, [\"new.pdf\", \"BASE64_CONTENT\"]] }\n```\n\n## Удалить файл\n\nПередайте в поле только те файлы, которые нужно оставить. Пустой массив очищает поле полностью.\n\n```json\n{ \"ufCrm_1a2b3c\": [] }\n```\n\n## Смотрите также\n\n- [Работа с файлами Диска](.\u002Fdisk-files.md)\n- [Синтаксис фильтрации](..\u002Ffiltering.md)\n- [Entity API](..\u002Fentity-api.md)\n","2026-07-03",{}]