Skip to content

Файлы

Загрузка файлов и получение доступа к ним.

Загрузить файл

Request

Администратор салона загружает CARD с SERVICE_MANAGE, BLOG с SALON_PAGE, AVATAR с STAFF_MANAGE или SALON_PAGE. Владельцем таких файлов сохраняется владелец его салона. Остальные назначения, включая приватные DOCUMENT и бизнес-документы владельца, администратору не разрешены. Мастер салона не получает права загрузки.

Загружает файл. HTTP 200 возвращается после завершения всех обязательных этапов: проверки, crop/стандартизации, шифрования для защищённых назначений и локальной записи основного файла, оригинала и preview, если они предусмотрены для purpose. На момент успешного ответа файл имеет статус UPLOADED; data.file_id можно сразу использовать при создании услуги, сообщения или привязке другого вложения. Отправка в object storage выполняется фоном. GET /api/file/{id} возвращает ссылку на /api/file/download/{id} в обоих состояниях. Этот endpoint перенаправляет обычный файл к текущему месту хранения. Приватные DOCUMENT и SUPPORT всегда выдаются через API. При ошибке подготовки либо локальной записи возвращается HTTP 500 с error_code=file_upload_failed, без успешного file_id.

JSON-part metadata определяет назначение файла и связанные ограничения по типу, размеру и crop.

Ограничения входных данных:

  • файл обязателен и не может быть пустым
  • исходное имя файла должно быть непустым и не длиннее 255 символов
  • размер файла должен быть больше 0
  • количество пикселей изображения ограничено настройкой file.upload.max-image-pixels (по умолчанию 40000000)
  • для файлов с content-type, начинающимся на image/, максимальный размер составляет 20 MB
  • для остальных файлов максимальный размер составляет 100 MB
  • для AVATAR разрешены только image/png, image/jpeg, image/jpg, image/webp
  • для CARD разрешены только image/png, image/jpeg, image/jpg, image/webp
  • для REVIEW разрешены изображения image/png, image/jpeg, image/jpg, image/webp и видео video/mp4, video/quicktime, video/webm, video/3gpp, video/mpeg
  • видео MESSAGE разрешены с MIME video/mp4, video/quicktime, video/webm, video/3gpp, video/mpeg и распознаются как видео, в том числе при определении MP4 как QuickTime и WebM как Matroska
  • для изображений REVIEW ширина и высота должны быть не меньше 900, соотношение сторон не больше 3:1; для видео размеры изображения не проверяются; crop передавать нельзя
  • изображения REVIEW стандартизируются в image/webp с короткой стороной 900, preview — с короткой стороной 200; видео сохраняются без преобразования и без preview
  • для BLOG разрешены только image/png, image/jpeg, image/jpg, image/webp
  • для CATEGORY разрешены только image/png, image/jpeg, image/jpg, image/webp
  • для COMPLAINT разрешены только изображения image/png, image/jpeg, image/jpg, image/webp, image/gif, image/bmp, image/heic, image/heif
  • для AVATAR исходное изображение должно быть не меньше 900x900; crop обязателен, должен быть квадратным и не меньше 900x900
  • для CARD ширина и высота должны быть не меньше 900, а соотношение сторон не больше 3:1; квадратность не требуется, crop передавать нельзя
  • для BLOG ширина и высота должны быть не меньше 900, а соотношение сторон не больше 3:1; квадратность не требуется, crop передавать нельзя
  • для CATEGORY изображение должно быть квадратным и не меньше 300x300; crop передавать нельзя
  • для MESSAGE и VOICE crop передавать нельзя
  • изображения CARD после загрузки стандартизируются в image/webp с короткой стороной 900, без увеличения
  • изображения AVATAR после квадратного crop стандартизируются в image/webp и вписываются в 900x900, без увеличения
  • изображения BLOG после загрузки стандартизируются в image/webp с короткой стороной 900, без увеличения
  • изображения CATEGORY после загрузки стандартизируются в image/webp и вписываются в 300x300
  • изображения COMPLAINT после загрузки стандартизируются в image/webp; preview создаётся в image/webp с максимальной стороной 900
  • preview создаётся только для purpose, где на backend явно задан размер preview
  • сейчас preview создаётся для AVATAR в image/webp, вписанный в 150x150
  • сейчас preview создаётся для CARD в image/webp с короткой стороной 200
  • сейчас preview создаётся для MESSAGE image-файлов в image/webp, вписанный в 900x900
  • сейчас preview создаётся для BLOG в image/webp с короткой стороной 333

CARD используется для карточек мастера, сервиса и салона. REVIEW используется для фотографий и видео отзывов. После успешного ответа upload сразу передайте file_id в media_ids при создании или редактировании отзыва. В сумме допускается до 10 фото и видео. Ранее загруженные изображения CARD также принимаются. BLOG используется для изображений постов. CATEGORY используется для изображений категорий. COMPLAINT используется только как вложение жалобы; прикрепить можно только собственные файлы с этим purpose.

Для первого шага регистрации бизнеса и замены документов отправляйте каждый документ отдельным multipart-запросом: part file — содержимое, part metadata — JSON {"purpose":"DOCUMENT"} с Content-Type application/json. Ответ содержит числовой data.file_id. Успешный ответ возвращается после завершения подготовки и локальной записи. Полученный file_id уже имеет статус UPLOADED. При ошибке upload загрузите файл заново. После этого передайте file_id в files запроса PUT /api/business-registry/registration либо PUT /api/business-registry/registration/documents/reupload. Один upload не изменяет заявку.

Security
bearerAuth or jwtCookie
Bodymultipart/form-datarequired
filestring, (binary)required

Бинарный файл. Имя файла должно быть непустым и не длиннее 255 символов, размер - больше 0 и не более 100 MB.

metadataobject(FileUploadMetadataRequest)required

Метаданные multipart-запроса на загрузку файла.

Правила по crop зависят от purpose:

  • для AVATAR crop обязателен
  • для CARD, REVIEW, BLOG, CATEGORY, MESSAGE и VOICE crop запрещён
curl -i -X POST \
  https://felmee.com/api/file/upload \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@avatar.png;type=application/octet-stream' \
  -F 'metadata="{\"purpose\":\"AVATAR\",\"crop\":{\"height\":900,\"width\":900,\"x\":0,\"y\":0}}";type=application/json'

Responses

Файл подготовлен и доступен с локального диска; перенос в object storage выполняется фоном

Headers
X-Upload-Trace-Idstring, (uuid)

Идентификатор загрузки для сопоставления замеров Nginx и приложения.

Bodyapplication/json
codeErrorstring or nullrequired

Устаревший camelCase-alias поля error_code; при ошибке оба поля содержат одинаковое значение.

successbooleanrequired

Флаг успешного выполнения запроса

messagestringrequired

Человекочитаемое описание результата

error_codestring or null(ERROR_CODE)required

Код ошибки. Для успешных ответов всегда null.

Enum:"INVALID_BODY""INVALID_DATE""invalid_body""unauthorized""not_found""slot_unavailable""conflict""BUSINESS_INACTIVE""INSUFFICIENT_FUNDS""REQUISITES_REQUIRED"
dataobject or null(FileUploadData)required

Полезная нагрузка. Может быть объектом, массивом или null.

Response
{ "success": true, "message": "File upload successfully", "codeError": null, "error_code": null, "data": { "file_id": 123 } }