Как загрузить файл в задачу

Scope: disk, task

Кто может выполнять методы: чтобы пройти сценарий целиком, нужны права на добавление файла в папку Диска, редактирование задачи и чтение файла

disk.folder.uploadFile — пользователь с правом «Добавление» для папки Диска

tasks.task.files.attach — постановщик задачи или пользователь с правом редактирования задачи и чтения файла

disk.attachedObject.get — пользователь с правом «Чтение» для файла

Выберите инструмент для разработки с AI-агентом:

используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

В Битрикс24 есть два типа файловых полей:

Файл. Поле не связано с Диском, в него файлы загружаются напрямую, через строку формата Base64
Файл (диск). Поле связано с Диском, в поле хранится ID объекта Диска. Формат Base64 в поле не обрабатывается, поэтому сначала файл необходимо загрузить на Диск Битрикс24

Сценарий состоит из трех шагов:

Загрузите файл на Диск методом disk.folder.uploadFile
Передайте ID объекта Диска в tasks.task.files.attach, чтобы прикрепить файл к задаче
Проверьте связь файла с задачей методом disk.attachedObject.get

В результате файл появится в существующей задаче. Проверку выполняйте после прикрепления: attachmentId для третьего шага возвращает метод второго шага.

Перед началом

Для выполнения примера нужны:

входящий вебхук со scope disk и task, созданный пользователем с правом добавления файла в папку Диска, редактирования задачи и чтения файла
идентификатор папки Диска folderId, в которую нужно загрузить файл. Получите его методом disk.storage.getChildren для папки в корне хранилища или disk.folder.getChildren для вложенной папки. В примерах folderId равен 1739
идентификатор существующей задачи taskId. Получите его методом tasks.task.list. В примерах taskId равен 3709
файл, который нужно прикрепить к задаче, в каталоге запуска скрипта. В примерах исходное имя — avatar.jpg, а имя на Диске из data.NAME — ava555.jpg
содержимое файла в виде строки Base64 без префикса data:*/*;base64,. Передайте в fileContent массив из имени файла и этой строки

Вебхук выполняет запросы с правами пользователя, который его создал. Адрес вебхука дает доступ к методам с его scope: храните его в переменных окружения сервера, не добавляйте в браузерный код и репозиторий. Для JS и PHP задайте переменную B24_HOOK с полным URL вебхука. Для Python задайте B24_DOMAIN с доменом Битрикс24 и B24_WEBHOOK_TOKEN со значением вида USER_ID/TOKEN.

Для JS-примера нужны Node.js 22 или новее и пакет @bitrix24/b24jssdk. Код использует ES-модули: сохраните его в файле .mjs или добавьте "type": "module" в package.json. Для Python-примера нужны Python 3.9 или новее и пакет b24pysdk. Для PHP-примера нужны PHP 8.4 или новее и пакет bitrix24/b24phpsdk версии ^3.0.

Инициализируйте SDK до первого вызова метода. Разместите код инициализации и следующие фрагменты выбранного языка в одном скрипте.

Как использовать примеры в документации

PHP

Python

import { readFile } from 'node:fs/promises'
import { B24Hook } from '@bitrix24/b24jssdk'

const $b24 = B24Hook.fromWebhookUrl(process.env.B24_HOOK)

require_once 'vendor/autoload.php';

use Bitrix24\SDK\Services\ServiceBuilderFactory;
use Monolog\Logger;
use Symfony\Component\EventDispatcher\EventDispatcher;

$log = new Logger('b24');
$serviceBuilder = (new ServiceBuilderFactory(new EventDispatcher(), $log))
    ->initFromWebhook(getenv('B24_HOOK'));

import base64
import os
from pathlib import Path

from b24pysdk import BitrixWebhook, Client

token = BitrixWebhook(
    domain=os.environ["B24_DOMAIN"],
    webhook_token=os.environ["B24_WEBHOOK_TOKEN"],
)
client = Client(token)

1. Загружаем файл на диск Битрикс24

Для загрузки файла на Диск используем метод disk.folder.uploadFile с параметрами:

id — укажем значение 1739 — идентификатор папки Диска, в которую загружаем файл
data — укажем имя файла NAME, с этим именем файл сохранится на Диске Битрикс24
fileContent — передаем файл в формате ['имя_файла.расширение', 'файл в виде строки, закодированной в Base64']

Загрузка файла на Диск — необходимый шаг, так как поле UF_TASK_WEBDAV_FILES в задачах принимает только ID файлов Диска.

PHP

Python

const fileName = 'avatar.jpg'
const fileBase64 = (await readFile(fileName)).toString('base64')

const uploadResponse = await $b24.actions.v2.call.make({
    method: 'disk.folder.uploadFile',
    params: {
        id: 1739,
        data: {
            NAME: 'ava555.jpg'
        },
        fileContent: [
            fileName,
            fileBase64
        ]
    },
    requestId: 'disk-uploadfile'
})

if (!uploadResponse.isSuccess) {
    throw new Error(uploadResponse.getErrorMessages().join('; '))
}

const uploadedFile = uploadResponse.getData().result

$fileName = 'avatar.jpg';
$fileBytes = file_get_contents($fileName);
if ($fileBytes === false) {
    throw new RuntimeException('Не удалось прочитать файл');
}
$fileBase64 = base64_encode($fileBytes);

$uploadedFile = $serviceBuilder->getDiskScope()->folder()->uploadFile(
    1739,
    ['NAME' => 'ava555.jpg'],
    [
        $fileName,
        $fileBase64
    ]
)->getFile();

echo '<PRE>';
print_r($uploadedFile);
echo '</PRE>';

file_name = "avatar.jpg"
file_base64 = base64.b64encode(Path(file_name).read_bytes()).decode("ascii")

uploaded_file = client.disk.folder.uploadfile(
    bitrix_id=1739,
    data={
        "NAME": "ava555.jpg",
    },
    file_content=[
        file_name,
        file_base64,
    ],
).response.result

В результате загрузки файла на Диск получили два разных значения ID файла:

FILE_ID: 28073 — внутреннее значение ID файла
ID: 6687 — ID объекта Диска, это значение используем в методах для работы с полями типа «файл (диск)»

Если в запросе для изменения поля «файл (диск)» передать значение FILE_ID, файл либо не прикрепится к задаче, поскольку нет объекта Диска с таким ID, либо прикрепится не тот файл

{
    "result": {
        "ID": 6687,
        "NAME": "ava555.jpg",
        "TYPE": "file",
        "PARENT_ID": "1739",
        "FILE_ID": 28073,
        "SIZE": "405559"
    }
}

2. Прикрепляем файл к задаче

Для прикрепления файла к задаче используем метод tasks.task.files.attach с параметрами:

taskId — ID задачи. Для получения значения ID используйте метод tasks.task.list
fileId — передайте ID объекта Диска из ответа предыдущего метода. В примере ответа это 6687

PHP

Python

const attachResponse = await $b24.actions.v2.call.make({
    method: 'tasks.task.files.attach',
    params: {
        taskId: 3709,
        fileId: Number(uploadedFile.ID)
    },
    requestId: 'task-files-attach'
})

if (!attachResponse.isSuccess) {
    throw new Error(attachResponse.getErrorMessages().join('; '))
}

const attachment = attachResponse.getData().result

// Для этого метода нет типизированной обертки, поэтому вызываем его через ядро SDK
$attachment = $serviceBuilder->core->call(
    'tasks.task.files.attach',
    [
        'taskId' => 3709,
        'fileId' => $uploadedFile['ID']
    ]
)->getResponseData()->getResult();

echo '<PRE>';
print_r($attachment);
echo '</PRE>';

attachment = client.tasks.task.files.attach(
    task_id=3709,
    file_id=int(uploaded_file["ID"]),
).response.result

Мы загрузили файл в задачу и в ответ получили ID связи между файлом Диска и задачей 423. Чтобы проверить прикрепление файла к задаче по ID связи, используем метод disk.attachedObject.get.

{
    "result": {
        "attachmentId": 423
    }
}

Проверим результат

Передайте attachmentId из ответа метода tasks.task.files.attach в параметр id метода disk.attachedObject.get. В примере ответа значение равно 423, в коде используется идентификатор текущего прикрепления.

PHP

Python

const checkResponse = await $b24.actions.v2.call.make({
    method: 'disk.attachedObject.get',
    params: {
        id: Number(attachment.attachmentId)
    },
    requestId: 'disk-attached-object-get'
})

if (!checkResponse.isSuccess) {
    throw new Error(checkResponse.getErrorMessages().join('; '))
}

console.log(checkResponse.getData().result)

// Для этого метода нет типизированной обертки, поэтому вызываем его через ядро SDK
$file = $serviceBuilder->core->call(
    'disk.attachedObject.get',
    [
        'id' => $attachment['attachmentId']
    ]
)->getResponseData()->getResult();

print_r($file);

# Для этого метода нет типизированной обертки, поэтому используем прямой вызов
file = token.call_method(
    "disk.attachedObject.get",
    {
        "id": attachment["attachmentId"],
    },
)["result"]

print(file)

Метод вернет данные прикрепленного файла. Сценарий выполнен успешно, если:

ID совпадает с attachmentId из предыдущего шага
OBJECT_ID содержит идентификатор файла на Диске
ENTITY_TYPE равен tasks_task
ENTITY_ID равен идентификатору задачи
NAME содержит имя прикрепленного файла

Откройте задачу в Битрикс24 и проверьте, что файл ava555.jpg появился среди прикрепленных файлов.

{
    "result": {
        "ID": "423",
        "OBJECT_ID": "6687",
        "MODULE_ID": "tasks",
        "ENTITY_TYPE": "tasks_task",
        "ENTITY_ID": "3709",
        "NAME": "ava555.jpg",
        "SIZE": "405559"
    }
}

Ошибки и диагностика

Если метод вернул ошибку, проверьте данные запроса.

Ошибка	Причина и решение
`ERROR_NOT_FOUND` в disk.folder.uploadFile	Папка с указанным `id` не найдена
`DISK_BASE_SERVICE_22001`	В `data.NAME` не передано имя файла
`ERROR_COULD_NOT_SAVE_FILE`	Файл не удалось сохранить. Проверьте свободное место на Диске и корректность Base64
`ACCESS_DENIED`	Пользователь вебхука не имеет прав на добавление файла в папку или чтение файла
`wrong task id`	В `taskId` передано значение неверного типа
`Could not find value for parameter {fileId}`	Не передан обязательный параметр `fileId`
`Invalid value {value} to match with parameter {fileId}`	В `fileId` передан не `ID` объекта Диска
Пустой результат проверки через disk.attachedObject.get	Передан не `attachmentId` из ответа tasks.task.files.attach

Повторяйте сценарий с того шага, который вернул ошибку. Если файл уже загружен на Диск, не загружайте его повторно: исправьте taskId или fileId и повторите только вызов tasks.task.files.attach.

Что важно учитывать

Если файл уже находится на Диске, пропустите загрузку и передайте его ID в fileId метода tasks.task.files.attach. Для другой задачи замените taskId. В обоих случаях проверьте права пользователя вебхука на файл и задачу.

Продолжите изучение

Была ли статья полезна?

Как создать задачу с прикрепленным файлом

Как перенести файл из поля CRM в задачу

Как загрузить файл в задачу

Перед началомПеред началом

1. Загружаем файл на диск Битрикс241. Загружаем файл на диск Битрикс24

2. Прикрепляем файл к задаче2. Прикрепляем файл к задаче

Проверим результатПроверим результат

Ошибки и диагностикаОшибки и диагностика

Что важно учитыватьЧто важно учитывать

Продолжите изучениеПродолжите изучение

Была ли статья полезна?

Перед началом

1. Загружаем файл на диск Битрикс24

2. Прикрепляем файл к задаче

Проверим результат

Ошибки и диагностика

Что важно учитывать

Продолжите изучение