Как скачать файлы

Файл скачивают по ссылке из ответа метода или методом, который сразу возвращает файл. Если метод вернул ссылку для скачивания, выполните отдельный GET-запрос к этой ссылке: вызов REST-метода только получает ссылку, сам файл в JSON-ответ не встраивается.

REST API не возвращает содержимое файлового поля в Base64: Base64 используется для загрузки файла в Битрикс24, а для скачивания приходит URL или файловый ответ.

Типы файловых полейТипы файловых полей

Чтобы скачать файл, сначала определите, где он хранится.

• Файл. Поле не связано с Диском. В поле хранится ID файла, а метод чтения объекта возвращает ссылку для открытия или скачивания. Такой ID нельзя передать в disk.file.get

• Файл (диск). Поле связано с Диском. В поле хранится ID объекта Диска или идентификатор привязки файла к объекту. Ссылку возвращают методы Диска или методы объекта, которому файл прикреплен

Как выбрать способ получения файлаКак выбрать способ получения файла

Виды ссылок в ответахВиды ссылок в ответах

В ответах методов встречаются ссылки для пользователя и ссылки для приложения.

Ссылки могут быть абсолютными или относительными. Например, относительными могут быть archiveLink задачи или urlMachine товара каталога. Если ссылка начинается с /, добавьте к ней адрес Битрикс24:

https://your-domain.bitrix24.com/bitrix/tools/disk/uf.php?attachedId=10&action=download&ncc=1

Ссылка может быть одноразовой или ограниченной по времени. Если HTTP-ответ указывает на истекшую ссылку или отказ доступа, повторно получите ссылку методом чтения объекта и скачайте файл по новой ссылке.

Права и ограниченияПрава и ограничения

• Для скачивания нужны права на объект, из которого получена ссылка, и scope метода, которым получаете ссылку или файл. Например, для файла в поле CRM нужны права на чтение элемента CRM и scope crm, для файла Диска — права на файл или папку и scope disk, для файла чата — доступ к чату и scope im или imbot. Точный scope указан на странице каждого метода и в статье Права доступа приложений

• Ссылка для приложения не заменяет постоянный идентификатор файла. Храните ID файла, идентификатор привязки или ID объекта, а ссылку получайте перед скачиванием

Скачать файл из поля CRMСкачать файл из поля CRM

Для файловых полей CRM используйте универсальные методы crm.item.get и crm.item.list. Они работают с лидами, сделками, контактами, компаниями, счетами и смарт-процессами.

В ответе файловое поле содержит id, url и urlMachine. Для скачивания приложением используйте urlMachine.

{
    "result": {
        "item": {
            "id": 1,
            "ufCrm_123456": [
                {
                    "id": 10,
                    "url": "https://your-domain.bitrix24.com/bitrix/services/main/ajax.php?action=crm.controller.item.getFile&SITE_ID=s1&entityTypeId=2&id=1&fieldName=UF_CRM_123456&fileId=10",
                    "urlMachine": "https://your-domain.bitrix24.com/rest/crm.controller.item.getFile.json?auth=***&token=***"
                }
            ]
        }
    }
}

id в таком поле — это идентификатор файла CRM, а не ID объекта на Диске. Методы Диска не вернут данные по этому числу.

Скачать файл из комментария таймлайна CRMСкачать файл из комментария таймлайна CRM

Файлы комментариев таймлайна возвращают методы crm.timeline.comment.get и crm.timeline.comment.list. В поле FILES ключ объекта совпадает с id файла.

{
    "result": {
        "ID": "1",
        "ENTITY_ID": "2",
        "ENTITY_TYPE": "deal",
        "COMMENT": "New comment was added",
        "FILES": {
            "10": {
                "id": 10,
                "type": "file",
                "name": "1.txt",
                "size": 13,
                "urlPreview": null,
                "urlShow": "https://your-domain.bitrix24.com/disk/downloadFile/10/?&ncc=1&filename=1.txt",
                "urlDownload": "https://your-domain.bitrix24.com/disk/downloadFile/10/?&ncc=1&filename=1.txt"
            }
        }
    }
}

Ссылка urlDownload открывает файл в авторизованном контексте Битрикс24. Она не содержит REST-токен, поэтому для серверного скачивания через вебхук не подходит: HTTP-клиент без браузерной авторизации получит HTML-страницу, а не содержимое файла.

Чтобы скачать файл серверным приложением:

1. Возьмите id файла из объекта FILES
2. Вызовите disk.file.get с этим id
3. Скачайте файл по DOWNLOAD_URL из ответа disk.file.get

Скачать файл ДискаСкачать файл Диска

Если в поле хранится файл Диска, получите ID файла и вызовите disk.file.get. Метод вернет DOWNLOAD_URL.

{
    "result": {
        "ID": "10",
        "NAME": "report.docx",
        "TYPE": "file",
        "SIZE": "21668",
        "DOWNLOAD_URL": "https://your-domain.bitrix24.com/rest/download.json?auth=***&token=***",
        "DETAIL_URL": "https://your-domain.bitrix24.com/company/personal/user/1/disk/file/report.docx"
    }
}

В некоторых полях хранится не ID файла, а идентификатор привязки. Например, файлы задач и часть файловых полей списков связаны с объектом через привязку. Сначала вызовите disk.attachedObject.get, возьмите OBJECT_ID и получите DOWNLOAD_URL методом disk.file.get.

Скачать файл из спискаСкачать файл из списка

Чтобы получить URL файла из свойства элемента списка, вызовите lists.element.get.file.url.

Для свойства типа «Файл (Диск)» метод вернет ссылку на скачивание через привязку:

{
    "result": [
        "/bitrix/tools/disk/uf.php?attachedId=10&action=download&ncc=1"
    ]
}

Для свойства типа «Файл» метод вернет ссылку на файл списка:

{
    "result": [
        "/company/lists/1/file/0/10/PROPERTY_123/20/?ncc=y&download=y"
    ]
}

Скачать файл из задачи или поста лентыСкачать файл из задачи или поста ленты

Файлы задач и постов ленты хранятся на Диске и привязаны к объекту через идентификатор привязки.

Метод tasks.task.get возвращает файлы задачи в поле UF_TASK_WEBDAV_FILES. Значение может приходить с префиксом n, например n491. Для метода disk.attachedObject.get передавайте число без префикса.

{
    "result": {
        "task": {
            "id": 1,
            "ufTaskWebdavFiles": [
                "n10"
            ]
        }
    }
}

Метод log.blogpost.get возвращает идентификаторы привязок в поле FILES.

{
    "result": [
        {
            "ID": 1,
            "FILES": [
                10
            ]
        }
    ]
}

Чтобы скачать отдельный файл задачи или поста:

1. Вызовите disk.attachedObject.get по идентификатору привязки
2. Возьмите OBJECT_ID из ответа
3. Вызовите disk.file.get и скачайте файл по DOWNLOAD_URL

Для задачи можно скачать все файлы архивом. Метод tasks.task.get REST v3 возвращает ссылку archiveLink.

{
    "result": {
        "item": {
            "id": 1,
            "archiveLink": "/bitrix/tools/disk/uf.php?entityId=1&entity=TASKS_TASK&fieldName=UF_TASK_WEBDAV_FILES&action=downloadArchiveByEntity&ncc=1"
        }
    }
}

Комментарий ленты возвращает метод log.blogcomment.user.get. В поле FILES приходит объект с данными файлов и ссылкой urlDownload.

{
    "result": [
        {
            "ID": "1",
            "FILES": {
                "10": {
                    "id": 10,
                    "type": "file",
                    "name": "file.txt",
                    "urlDownload": "https://your-domain.bitrix24.com/disk/downloadFile/10"
                }
            }
        }
    ]
}

Если серверному приложению нужна подписанная REST-ссылка, передайте id файла из FILES в disk.file.get и используйте DOWNLOAD_URL.

Скачать файл товара каталогаСкачать файл товара каталога

Методы catalog.product.get и catalog.product.list возвращают файлы товара в полях изображений и пользовательских свойствах типа «файл». В значении файла есть id, url и urlMachine.

{
    "result": {
        "products": [
            {
                "id": 1,
                "property123": {
                    "value": {
                        "id": "10",
                        "url": "/rest/catalog.product.download?fields%5BfieldName%5D=property123&fields%5BfileId%5D=10&fields%5BproductId%5D=1",
                        "urlMachine": "/rest/catalog.product.download?fields%5BfieldName%5D=property123&fields%5BfileId%5D=10&fields%5BproductId%5D=1"
                    },
                    "valueId": "20"
                }
            }
        ]
    }
}

Для скачивания используйте urlMachine или вызовите catalog.product.download. Метод catalog.product.download сразу возвращает тело файла.

Скачать шаблон или документ генератора документовСкачать шаблон или документ генератора документов

Методы documentgenerator.template.get, documentgenerator.template.list, crm.documentgenerator.template.get и crm.documentgenerator.template.list возвращают поле downloadMachine.

Методы documentgenerator.document.add, documentgenerator.document.list, crm.documentgenerator.document.add и crm.documentgenerator.document.list возвращают поле downloadUrlMachine.

{
    "template": {
        "id": 1,
        "downloadMachine": "https://your-domain.bitrix24.com/rest/documentgenerator.api.template.download.json?auth=***&token=***"
    },
    "document": {
        "id": 2,
        "downloadUrlMachine": "https://your-domain.bitrix24.com/rest/documentgenerator.api.document.getfile.json?auth=***&token=***"
    }
}

Для шаблона используйте downloadMachine, для готового документа — downloadUrlMachine.

Скачать файл чатаСкачать файл чата

Файл чата скачивают отдельным методом в зависимости от контекста:

• im.v2.File.download — для файла от имени пользователя
• imbot.v2.File.download — для файла от имени бота

Оба метода возвращают downloadUrl.

{
    "result": {
        "downloadUrl": "https://your-domain.bitrix24.com/rest/download.json?auth=***&token=***"
    }
}

Ссылка downloadUrl одноразовая. Получайте новую ссылку перед каждым скачиванием.

Скачать запись звонка телефонииСкачать запись звонка телефонии

Метод voximplant.statistic.get возвращает запись звонка в поле CALL_RECORD_URL, если запись прикреплена к звонку и доступна текущему пользователю.

{
    "result": [
        {
            "ID": "1",
            "CALL_ID": "externalCall.example",
            "PORTAL_USER_ID": "1",
            "CALL_RECORD_URL": "https://your-domain.bitrix24.com/rest/download.json?auth=***&token=***"
        }
    ]
}

Если CALL_RECORD_URL пустой, у звонка нет доступной записи. Сначала прикрепите запись методом telephony.externalCall.attachRecord, затем снова получите статистику звонка.

Получить метаданные файла Базы знанийПолучить метаданные файла Базы знаний

Метод note.file.get возвращает объект файла, который привязан к документу Базы знаний. В ответе есть метаданные и assetMarkdown — готовый блок для вставки файла в Markdown документа.

{
    "result": {
        "item": {
            "id": 10,
            "documentId": 1,
            "name": "file.txt",
            "mimeType": "text/plain",
            "assetMarkdown": "[[file fileId=10]]"
        }
    }
}

Метод не возвращает ссылку для скачивания или тело файла. Чтобы файл появился на странице Базы знаний, вставьте assetMarkdown в содержимое документа методом note.document.update.

Скачать подписанный документСкачать подписанный документ

Метод sign.b2e.hcmlink.document.get возвращает ссылку на файл подписанного документа в поле fileUrl, методы sign.b2e.mysafe.tail и sign.b2e.personal.tail — в поле file_url.

{
    "result": {
        "fileUrl": "https://your-domain.bitrix24.com/rest/download.json?auth=***&token=***"
    }
}

Как выполнить скачиваниеКак выполнить скачивание

Ниже приведен пример скачивания файла по ссылке из ответа метода.

curl -L \
  -H "User-Agent: MyIntegration/1.0" \
  -H "Accept: */*" \
  -H "Accept-Language: ru-RU,ru;q=0.9,en;q=0.8" \
  -H "Referer: https://your-domain.bitrix24.com/" \
  -o report.pdf \
  "https://your-domain.bitrix24.com/rest/download.json?auth=***&token=***"

Передавайте заголовки User-Agent, Accept, Accept-Language и Referer по правилам из статьи Как выполняется запрос. Если HTTP-клиент не передает эти заголовки или подставляет технический User-Agent, файл может не скачаться, даже если ссылка подписана корректно.

Если метод сам возвращает файл, например catalog.product.download, сохраните тело ответа REST-метода как файл. В таком ответе не будет JSON с result.

Проверяйте HTTP-статус и тип ответа. Если вместо файла пришел JSON с ошибкой, обработайте код ошибки: проверьте права, срок действия ссылки и повторно получите ссылку перед скачиванием.

Если вместо файла пришла HTML-страница авторизации, ссылка не подходит для серверного скачивания. Получите urlMachine, DOWNLOAD_URL, downloadMachine, downloadUrlMachine или другое поле скачивания из таблицы.

Что дальшеЧто дальше

• Как загрузить файлы — форматы передачи файла и загрузка нескольких файлов во множественное поле

• Как обновить и удалить файлы — замена файла, удаление и сохранение остальных файлов множественного поля

• Как работать с файлами — обзор раздела: типы полей, связь файлов с объектами Битрикс24 и основные методы Диска