Загрузить вложение

POST /v1/feedback/attachments

Загружает изображение или документ и возвращает его идентификатор для последующей привязки к обращению или комментарию. Загрузка двухэтапная: сначала файл отправляется сюда, затем полученный id передаётся в поле attachmentIds при создании обращения или добавлении комментария.

Файл передаётся как multipart/form-data в поле file, тип определяется по расширению в имени файла. Изображения PNG, JPEG, WebP и GIF перекодируются на стороне сервера: PNG, JPEG и WebP приводятся к WebP, GIF пересобирается как GIF с сохранением анимации. Документы TXT, MD, CSV, HTML, XLSX и ZIP сохраняются без изменений. Ограничения: до 10 МБ на файл, до 24 миллионов пикселей на изображение, до 5 вложений на одно сообщение и до 25 на обращение.

Поля запроса (multipart/form-data)

Примеры

curl — личный ключ

curl -X POST https://vibecode.bitrix24.tech/v1/feedback/attachments \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "file=@screenshot.png"

curl — OAuth-приложение

curl -X POST https://vibecode.bitrix24.tech/v1/feedback/attachments \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -F "file=@screenshot.png"

JavaScript — личный ключ

const form = new FormData()
form.append('file', fileInput.files[0])

const res = await fetch('https://vibecode.bitrix24.tech/v1/feedback/attachments', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  body: form,
})
const { data } = await res.json()
// data.id передайте в attachmentIds при создании обращения или комментария

JavaScript — OAuth-приложение

const form = new FormData()
form.append('file', fileInput.files[0])

const res = await fetch('https://vibecode.bitrix24.tech/v1/feedback/attachments', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
  body: form,
})
const { data } = await res.json()

Поля ответа

Пример ответа

Загружено изображение screenshot.png:

{
  "success": true,
  "data": {
    "id": "15ae6203-e67c-4378-912c-9b0465360c79",
    "kind": "IMAGE",
    "mime": "image/webp",
    "sizeBytes": 560,
    "width": 640,
    "height": 360,
    "thumbnailUrl": "/v1/feedback/_orphan/15ae6203-e67c-4378-912c-9b0465360c79/thumb",
    "originalName": "screenshot.png",
    "expiresAt": "2026-10-09T09:27:47.506Z"
  }
}

Загружен документ note.txt — без превью и без размеров:

{
  "success": true,
  "data": {
    "id": "f4ec1f18-431b-49ec-85bb-bedcfce6da7d",
    "kind": "DOCUMENT",
    "mime": "text/plain",
    "sizeBytes": 16,
    "width": 0,
    "height": 0,
    "thumbnailUrl": null,
    "originalName": "note.txt",
    "expiresAt": "2026-10-09T09:25:40.292Z"
  }
}

Пример ответа при ошибке

413 — файл больше 10 МБ:

{
  "success": false,
  "error": {
    "code": "IMAGE_TOO_LARGE",
    "message": "File too large: a feedback attachment is capped at 10 MB (10485760 bytes)",
    "hint": "Shrink the image below 10 MB (lower the resolution or re-encode as JPEG or WebP) and upload it again. The cap applies to each file and is not raised by retrying."
  }
}

Ошибки

Полный список общих ошибок API — Ошибки.

Известные особенности

Вложение живёт час до привязки. Загруженное вложение сначала не связано ни с одним обращением и удаляется после expiresAt (через час), если его id не передан в attachmentIds при создании обращения или комментария. После привязки вложение хранится вместе с обращением.

Формат после обработки. PNG, JPEG и WebP приводятся к WebP, поэтому их mime в ответе — image/webp. GIF пересобирается как GIF (image/gif) с сохранением анимации, до 30 кадров, сверх этого — 400 TOO_MANY_FRAMES. Поля sizeBytes, width и height относятся к обработанному файлу. Документ хранится байт в байт, его mime определяется расширением, а не содержимым. Архив не распаковывается, у .zip и .xlsx проверяется только сигнатура ZIP.

Класс вложения выбирается по расширению имени, а не по Content-Type. Изображение обрабатывается по фактическому содержимому, поэтому JPEG, сохранённый как image.png, принимается, а mime в ответе — результат перекодирования. Файл без расширения — например, blob, который FormData.append даёт объекту Blob, — принимается только как изображение и только когда его Content-Type — image/png, image/jpeg, image/webp или image/gif.

Операции с привязанным вложением

После привязки к обращению вложение доступно на скачивание и удаление по его id (поле data.attachments[].id в Получить обращение). Эти операции работают с бинарными данными, поэтому у них нет JSON-тела и стандартного набора из 4 примеров.

Скачать вложение

GET /v1/feedback/:id/attachments/:attId/file

Возвращает файл вложения. Доступно ключу, у которого есть доступ к обращению. Изображение приходит со своим типом — image/webp или image/gif — и поддерживает ETag и If-None-Match: условный запрос отвечает 304 Not Modified. Документ всегда приходит как application/octet-stream с заголовком Content-Disposition: attachment и исходным именем файла, без ETag.

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.tech/v1/feedback/a1b2c3d4-1111-2222-3333-444455556666/attachments/1209c405-1f99-4240-95e5-d5cc0cd43560/file" \
  -o attachment.webp

Если вложение не существует, недоступно ключу или не относится к указанному обращению — 404 NOT_FOUND. При замороженном балансе — 402 ACCOUNT_FROZEN.

Превью вложения

GET /v1/feedback/:id/attachments/:attId/thumb

Возвращает уменьшенное превью изображения. Content-Type — всегда image/jpeg. Параметры и правила доступа — как у скачивания файла. У документа превью нет — запрос отвечает 404 NOT_FOUND.

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.tech/v1/feedback/a1b2c3d4-1111-2222-3333-444455556666/attachments/1209c405-1f99-4240-95e5-d5cc0cd43560/thumb" \
  -o thumb.jpg

Удалить вложение

DELETE /v1/feedback/:id/attachments/:attId

Удаляет вложение. Доступно тому, кто его загрузил. При успехе возвращается 204 No Content с пустым телом. Удалить нельзя, если другая сторона уже ответила после загрузки вложения.

curl -X DELETE -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.tech/v1/feedback/a1b2c3d4-1111-2222-3333-444455556666/attachments/1209c405-1f99-4240-95e5-d5cc0cd43560"

Смотрите также

• Отправить обращение
• Добавить комментарий
• Обратная связь
• Ошибки