Перейти к содержимому

Заказать ZIP-архив выбранных фото

POST
/api/v2/salons/{salon_id}/photos/archive
curl --request POST \
--url https://app.photo-otchet.ru/api/v2/salons/1/photos/archive \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "photo_ids": [ 1 ], "format": "webp", "max_size": 1280 }'

Проверяет состав и заводит заказ. Архив «как есть» (format: webp без max_size) готов сразу — 200 и state: ready. Любой другой формат или размер означает пережатие: ответ 202, state: queued, и дальше спрашивайте GET /photos/archive/{id} раз в две секунды. Повторный заказ того же состава в том же виде отдаёт тот же заказ, а не второй архив. Фото, которые ещё обрабатываются или удалены, в архив не попадают — их число в поле skipped.

salon_id
required
Salon Id

Салон

integer
>= 1

Салон

Тело запросаобязательно

Заголовок раздела « Request Bodyrequired »
Media type application/json
ArchiveRequest

Что положить в архив и в каком виде.

format: webp без max_size — архив «как есть»: фото ложатся такими, какими лежат у нас, и такой архив готов сразу, без сборки. Любой другой набор означает пережатие, а значит фоновую задачу.

Сколько фото можно — photos.download.max_photos; число приходит клиенту в «я в салоне» (limits.archive_max_photos) и в теле отказа 422 archive_too_many.

object
photo_ids
required
Photo Ids

Какие фото положить в архив

Array<integer>
>= 1 items
format
ImageFormat

Формат файлов внутри архива

string
default: webp
Allowed values: webp jpeg
max_size
Any of:
DownloadSize

Длинные стороны, в которые можно попросить вписать кадр при выдаче. Пусто — «как лежит у нас».

Перечислением, а не настройкой: значения попадают в схему OpenAPI и в кодоген клиента, и ему не приходится зашивать у себя два магических числа (просьба фронтенда 04.11.2026).

Перечисление чисел, а не Literal: размер приходит и в теле (числом), и в строке запроса (строкой), а Literal[1280, 2048] строку «1280» не принимает — запрос отбивался бы схемой.

Здесь, а не в схемах ручки: формат и размер — две половины одного ответа «в каком виде отдаём картинку», и жить они должны вместе. Отсюда их берут и схема заказа, и ручка «я в салоне», где клиент узнаёт пределы до запроса.

integer
Allowed values: 1280 2048

Заказ архива: с ним идти за состоянием и за файлом

Media type application/json
ArchiveView

Заказ архива глазами клиента.

Одна и та же форма во всех ответах — и на заказ, и на вопрос о состоянии, и в списке своих: клиент рисует её одним кодом, а расхождение «что в ответе» и «что в записи» было бы враньём о состоянии.

Две разные потери: skipped — отброшенные на входе (ещё обрабатываются или удалены), а total - done при ready — не прочитавшиеся во время сборки. Из-за одного битого кадра архив на пятьсот фото не теряется.

object
id
required
Id

Заказ: с ним идти за состоянием и за файлом

string
state
required
ArchiveState

queued, building, ready или failed

string
Allowed values: queued building ready failed
format
required
ImageFormat

Формат файлов внутри архива

string
Allowed values: webp jpeg
max_size
Any of:
integer
total
required
Total

Сколько фото попадёт в архив

integer
done
required
Done

Сколько уже уложено; при ready — сколько уложилось

integer
skipped
required
Skipped

Сколько выбранных отброшено на входе

integer
bytes
Any of:
integer
created_at
required
Created At

Когда заказан

string format: date-time
expires_at
required
Expires At

Когда исчезнет

string format: date-time
reason
Any of:
string

Пример

{
"state": "queued",
"format": "webp"
}

Заказ принят, архив собирается

Media type application/json
ArchiveView

Заказ архива глазами клиента.

Одна и та же форма во всех ответах — и на заказ, и на вопрос о состоянии, и в списке своих: клиент рисует её одним кодом, а расхождение «что в ответе» и «что в записи» было бы враньём о состоянии.

Две разные потери: skipped — отброшенные на входе (ещё обрабатываются или удалены), а total - done при ready — не прочитавшиеся во время сборки. Из-за одного битого кадра архив на пятьсот фото не теряется.

object
id
required
Id

Заказ: с ним идти за состоянием и за файлом

string
state
required
ArchiveState

queued, building, ready или failed

string
Allowed values: queued building ready failed
format
required
ImageFormat

Формат файлов внутри архива

string
Allowed values: webp jpeg
max_size
Any of:
integer
total
required
Total

Сколько фото попадёт в архив

integer
done
required
Done

Сколько уже уложено; при ready — сколько уложилось

integer
skipped
required
Skipped

Сколько выбранных отброшено на входе

integer
bytes
Any of:
integer
created_at
required
Created At

Когда заказан

string format: date-time
expires_at
required
Expires At

Когда исчезнет

string format: date-time
reason
Any of:
string

Пример

{
"state": "queued",
"format": "webp"
}

Нечего архивировать

Media type application/json
ErrorResponse

Отказ приложения: текст человеку и причина программе.

Ветвиться нужно по reason — текст detail переписывают, и ломаться об это клиент не должен. Поля причины приходят рядом и зависят от неё; перечень причин с таблицей «когда и где» — в docs/api/1.0.md, раздел «Формат ошибки».

object
detail
required
Detail

Текст для человека — показывается как есть

string
reason
required
Reason

Причина отказа: по ней ветвится клиент

string
Allowed values: unauthenticated policy forbidden not_found conflict bad_request invalid validation too_many_attempts salon_expired salon_blocked acceptance_required archive_not_ready archive_too_many transcode_unavailable
policy
Any of:
string
limit
Any of:
integer
retry_at
Any of:
string format: date-time
state
Any of:
string
paid_until
Any of:
string format: date-time

Пример

{
"detail": "Среди выбранных нет готовых фото"
}

Нет действующего входа: нет куки или токена, сессия истекла, токен отозван

Media type application/json
ErrorResponse

Отказ приложения: текст человеку и причина программе.

Ветвиться нужно по reason — текст detail переписывают, и ломаться об это клиент не должен. Поля причины приходят рядом и зависят от неё; перечень причин с таблицей «когда и где» — в docs/api/1.0.md, раздел «Формат ошибки».

object
detail
required
Detail

Текст для человека — показывается как есть

string
reason
required
Reason

Причина отказа: по ней ветвится клиент

string
Allowed values: unauthenticated policy forbidden not_found conflict bad_request invalid validation too_many_attempts salon_expired salon_blocked acceptance_required archive_not_ready archive_too_many transcode_unavailable
policy
Any of:
string
limit
Any of:
integer
retry_at
Any of:
string format: date-time
state
Any of:
string
paid_until
Any of:
string format: date-time

Пример

{
"reason": "unauthenticated"
}

Срок салона кончился: reason: salon_expired, в теле state и paid_until

Media type application/json
ErrorResponse

Отказ приложения: текст человеку и причина программе.

Ветвиться нужно по reason — текст detail переписывают, и ломаться об это клиент не должен. Поля причины приходят рядом и зависят от неё; перечень причин с таблицей «когда и где» — в docs/api/1.0.md, раздел «Формат ошибки».

object
detail
required
Detail

Текст для человека — показывается как есть

string
reason
required
Reason

Причина отказа: по ней ветвится клиент

string
Allowed values: unauthenticated policy forbidden not_found conflict bad_request invalid validation too_many_attempts salon_expired salon_blocked acceptance_required archive_not_ready archive_too_many transcode_unavailable
policy
Any of:
string
limit
Any of:
integer
retry_at
Any of:
string format: date-time
state
Any of:
string
paid_until
Any of:
string format: date-time

Пример

{
"reason": "unauthenticated"
}

Прав на это действие нет: не хватает политики или запрещён способ входа

Media type application/json
ErrorResponse

Отказ приложения: текст человеку и причина программе.

Ветвиться нужно по reason — текст detail переписывают, и ломаться об это клиент не должен. Поля причины приходят рядом и зависят от неё; перечень причин с таблицей «когда и где» — в docs/api/1.0.md, раздел «Формат ошибки».

object
detail
required
Detail

Текст для человека — показывается как есть

string
reason
required
Reason

Причина отказа: по ней ветвится клиент

string
Allowed values: unauthenticated policy forbidden not_found conflict bad_request invalid validation too_many_attempts salon_expired salon_blocked acceptance_required archive_not_ready archive_too_many transcode_unavailable
policy
Any of:
string
limit
Any of:
integer
retry_at
Any of:
string format: date-time
state
Any of:
string
paid_until
Any of:
string format: date-time

Пример

{
"reason": "unauthenticated"
}

Есть невидимое фото

Media type application/json
ErrorResponse

Отказ приложения: текст человеку и причина программе.

Ветвиться нужно по reason — текст detail переписывают, и ломаться об это клиент не должен. Поля причины приходят рядом и зависят от неё; перечень причин с таблицей «когда и где» — в docs/api/1.0.md, раздел «Формат ошибки».

object
detail
required
Detail

Текст для человека — показывается как есть

string
reason
required
Reason

Причина отказа: по ней ветвится клиент

string
Allowed values: unauthenticated policy forbidden not_found conflict bad_request invalid validation too_many_attempts salon_expired salon_blocked acceptance_required archive_not_ready archive_too_many transcode_unavailable
policy
Any of:
string
limit
Any of:
integer
retry_at
Any of:
string format: date-time
state
Any of:
string
paid_until
Any of:
string format: date-time

Пример

{
"detail": "Одно или несколько фото не найдены"
}

Слишком много фото

Media type application/json
ErrorResponse

Отказ приложения: текст человеку и причина программе.

Ветвиться нужно по reason — текст detail переписывают, и ломаться об это клиент не должен. Поля причины приходят рядом и зависят от неё; перечень причин с таблицей «когда и где» — в docs/api/1.0.md, раздел «Формат ошибки».

object
detail
required
Detail

Текст для человека — показывается как есть

string
reason
required
Reason

Причина отказа: по ней ветвится клиент

string
Allowed values: unauthenticated policy forbidden not_found conflict bad_request invalid validation too_many_attempts salon_expired salon_blocked acceptance_required archive_not_ready archive_too_many transcode_unavailable
policy
Any of:
string
limit
Any of:
integer
retry_at
Any of:
string format: date-time
state
Any of:
string
paid_until
Any of:
string format: date-time

Пример

{
"detail": "В один архив кладётся 500 фото, а выбрано 712"
}

Салон заблокирован оператором: reason: salon_blocked, причина в blocked_reason

Media type application/json
ErrorResponse

Отказ приложения: текст человеку и причина программе.

Ветвиться нужно по reason — текст detail переписывают, и ломаться об это клиент не должен. Поля причины приходят рядом и зависят от неё; перечень причин с таблицей «когда и где» — в docs/api/1.0.md, раздел «Формат ошибки».

object
detail
required
Detail

Текст для человека — показывается как есть

string
reason
required
Reason

Причина отказа: по ней ветвится клиент

string
Allowed values: unauthenticated policy forbidden not_found conflict bad_request invalid validation too_many_attempts salon_expired salon_blocked acceptance_required archive_not_ready archive_too_many transcode_unavailable
policy
Any of:
string
limit
Any of:
integer
retry_at
Any of:
string format: date-time
state
Any of:
string
paid_until
Any of:
string format: date-time

Пример

{
"reason": "unauthenticated"
}

Слишком часто

Media type application/json
ErrorResponse

Отказ приложения: текст человеку и причина программе.

Ветвиться нужно по reason — текст detail переписывают, и ломаться об это клиент не должен. Поля причины приходят рядом и зависят от неё; перечень причин с таблицей «когда и где» — в docs/api/1.0.md, раздел «Формат ошибки».

object
detail
required
Detail

Текст для человека — показывается как есть

string
reason
required
Reason

Причина отказа: по ней ветвится клиент

string
Allowed values: unauthenticated policy forbidden not_found conflict bad_request invalid validation too_many_attempts salon_expired salon_blocked acceptance_required archive_not_ready archive_too_many transcode_unavailable
policy
Any of:
string
limit
Any of:
integer
retry_at
Any of:
string format: date-time
state
Any of:
string
paid_until
Any of:
string format: date-time

Примеры

Салон уже собирает

{
"detail": "Салон уже собирает архивы — дождитесь, пока закончится хотя бы один, и повторите"
}