Скачать файлы вариации товара catalog.product.offer.download

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

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

Scope: catalog

Кто может выполнять метод: пользователь с правом на чтение вариации в инфоблоке и одним из прав: «Просмотр каталога товаров», «Просмотр товаров каталога» или «Изменение цены продажи товара»

Метод catalog.product.offer.download скачивает файл вариации товара из поля изображения или файлового свойства.

Параметры метода

Обязательные параметры отмечены *

Название
тип

Описание

fields*
object

Параметры файла вариации товара (подробное описание)

Параметр fields

Обязательные параметры отмечены *

Название
тип

Описание

fileId*
integer

Идентификатор зарегистрированного файла.

Идентификатор возьмите из поля id объекта файла в ответе метода catalog.product.offer.get или catalog.product.offer.list

productId*
catalog_product_offer.id

Идентификатор вариации товара.

Для получения идентификаторов вариаций товара необходимо использовать catalog.product.offer.list

fieldName*
string

Имя поля, в котором хранится файл. Передавайте имя в camelCase — в том же формате, в котором поле возвращают методы catalog.product.offer.get и catalog.product.offer.list.

Возможные значения:

  • detailPicture — детальная картинка, поле доступно в старой карточке товара
  • previewPicture — картинка для анонса, поле доступно в старой карточке товара
  • propertyN — файловое свойство, где N — идентификатор или символьный код свойства, например property258 или propertyMorePhoto

Получить идентификаторы и символьные коды свойств вариации можно методом catalog.productProperty.list. Для скачивания подходят только свойства файлового типа

Примеры кода

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

Метод возвращает содержимое файла, а не JSON. Выполняйте прямой HTTP-запрос и сохраняйте тело успешного ответа как файл.

curl -X POST \
-H "Content-Type: application/json" \
-d '{"fields":{"fileId":40057,"productId":7695,"fieldName":"previewPicture"}}' \
--output offer-file \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/catalog.product.offer.download
curl -X POST \
-H "Content-Type: application/json" \
-d '{"fields":{"fileId":40057,"productId":7695,"fieldName":"previewPicture"},"auth":"**put_access_token_here**"}' \
--output offer-file \
https://**put_your_bitrix24_address**/rest/catalog.product.offer.download
import { writeFile } from 'node:fs/promises'

const response = await fetch(
  'https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/catalog.product.offer.download',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      fields: {
        fileId: 40057,
        productId: 7695,
        fieldName: 'previewPicture',
      },
    }),
  },
)

if (!response.ok) {
  throw new Error(await response.text())
}

const file = new Uint8Array(await response.arrayBuffer())
await writeFile('offer-file', file)
<script>
  async function downloadOfferFile() {
    const response = await fetch(
      'https://**put_your_bitrix24_address**/rest/catalog.product.offer.download',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          fields: {
            fileId: 40057,
            productId: 7695,
            fieldName: 'previewPicture',
          },
          auth: '**put_access_token_here**',
        }),
      },
    )

    if (!response.ok) {
      throw new Error(await response.text())
    }

    const blob = await response.blob()
    const url = URL.createObjectURL(blob)
    const link = document.createElement('a')
    link.href = url
    link.download = 'offer-file'
    document.body.appendChild(link)
    link.click()
    link.remove()
    URL.revokeObjectURL(url)
  }

  document.addEventListener('DOMContentLoaded', downloadOfferFile)
</script>
import requests

response = requests.post(
    "https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/catalog.product.offer.download",
    json={
        "fields": {
            "fileId": 40057,
            "productId": 7695,
            "fieldName": "previewPicture",
        }
    },
)
response.raise_for_status()

with open("offer-file", "wb") as file:
    file.write(response.content)
$curl = curl_init('https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/catalog.product.offer.download');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'fields' => [
            'fileId' => 40057,
            'productId' => 7695,
            'fieldName' => 'previewPicture',
        ],
    ]),
]);

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($httpCode === 200) {
    file_put_contents('offer-file', $response);
} else {
    echo $response;
}
const auth = BX24.getAuth()
const url = new URL(`https://${auth.domain}/rest/catalog.product.offer.download`)
url.searchParams.set('auth', auth.access_token)
url.searchParams.set('fields[fileId]', 40057)
url.searchParams.set('fields[productId]', 7695)
url.searchParams.set('fields[fieldName]', 'previewPicture')

fetch(url)
  .then(async response => {
    if (!response.ok) {
      throw new Error(await response.text())
    }
    return response.blob()
  })
  .then(blob => {
    const objectUrl = URL.createObjectURL(blob)
    const link = document.createElement('a')
    link.href = objectUrl
    link.download = 'offer-file'
    document.body.appendChild(link)
    link.click()
    link.remove()
    URL.revokeObjectURL(objectUrl)
  })
  .catch(error => console.error(error))
payload, err := json.Marshal(map[string]any{
    "fields": map[string]any{
        "fileId": 40057, "productId": 7695, "fieldName": "previewPicture",
    },
})
if err != nil {
    return err
}

url := "https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/catalog.product.offer.download"
response, err := http.Post(url, "application/json", bytes.NewReader(payload))
if err != nil {
    return err
}
defer response.Body.Close()

body, err := io.ReadAll(response.Body)
if err != nil {
    return err
}
if response.StatusCode != http.StatusOK {
    return fmt.Errorf("download failed: %s", body)
}

return os.WriteFile("offer-file", body, 0o644)

Обработка ответа

HTTP-статус: 200

В теле ответа приходит содержимое файла. Это бинарный ответ, а не JSON: заголовок Content-Type зависит от формата файла, а Content-Disposition: attachment содержит имя файла для скачивания.

Возвращаемые данные

Файл с идентификатором fileId из поля fieldName вариации productId.

Обработка ошибок

HTTP-статус: 400

{
    "error": "0",
    "error_description": "Required fields: fileId"
}

Название
тип

Описание

error
string

Строковый код ошибки. Состоит из цифр, латинских букв и знака подчеркивания. Может прийти пустым — тогда причину показывает только error_description

error_description
string

Текст ошибки для разработчика. Не показывайте его конечному пользователю без обработки

Возможные коды ошибок

Статус

Код

Описание

Значение

400

200040300010

Access Denied

У пользователя нет ни права «Просмотр каталога товаров», ни права «Просмотр товаров каталога», ни права «Изменение цены продажи товара»

400

200040300040

Access Denied

У пользователя нет права на чтение этой вариации в инфоблоке

400

Пустое значение

offer does not exist.

Вариация с указанным productId не найдена

400

100

Could not find value for parameter

Не передан параметр fields

400

0

Required fields: fieldName, fileId, productId

Не передан один или несколько параметров в fields. В тексте перечислены отсутствующие параметры

400

0

Name file field is not available

Поле fieldName недоступно для скачивания: имя указано неверно, например в верхнем регистре, свойство не существует или не относится к файловому типу

400

0

Product file wrong

Файл fileId не относится к полю fieldName этой вариации

400

0

Product is empty

Файл с указанным fileId не найден в файловом хранилище

Статусы и коды системных ошибок

HTTP-статус: 4xx, 5xx

Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.

Статус

Код
Текст ошибки

Описание

500

INTERNAL_SERVER_ERROR
Internal server error

Возникла внутренняя ошибка сервера. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

Сервер вернул неожиданный ответ. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24

503

QUERY_LIMIT_EXCEEDED
Too many requests

Превышен лимит на интенсивность запросов

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит

401

NO_AUTH_FOUND
Wrong authorization data

В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука

401

INVALID_REQUEST
Https required

Методы вызываются только по протоколу HTTPS

401

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24

401

ACCESS_DENIED
REST is available only on commercial plans

REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — REST is available only by subscription

401

INVALID_CREDENTIALS
Invalid request credentials

Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом

404

ERROR_METHOD_NOT_FOUND
Method not found!

Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа

401

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на provided by the access token

401

expired_token
The access token provided has expired

Срок действия access-токена истек

401

user_access_error
The user does not have access to the application

Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям

403

PORTAL_DELETED
Portal was deleted

Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

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