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

Фото по фильтру

POST
/api/v2/salons/{salon_id}/photos/search
curl --request POST \
--url https://app.photo-otchet.ru/api/v2/salons/1/photos/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "filter": { "combinator": "and", "not": false, "rules": [ { "combinator": "and", "not": false, "rules": [] } ] }, "master_id": 1, "binding": "portfolio", "removed": "withheld", "limit": 50, "offset": 0 }'

Страница такая же, как у списка, только с деревом условий И/ИЛИ/НЕ по тегам и дате добавления.

Относительные периоды («эта неделя») считаются в момент запроса и в поясе студии, поэтому один и тот же сохранённый фильтр на следующей неделе покажет другое.

total считается не больше потолка: если подошло больше, приходит total_capped: true, листать дальше при этом можно.

salon_id
required
Salon Id

Салон

integer
>= 1

Салон

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

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

Поиск фото по фильтру. Дерево условий — то же, что хранится в именованных фильтрах.

binding и master_id работают так же, как у GET /photos, и умолчание общее: не задан — всё, на что есть право. Лента работ передаёт binding=portfolio явно.

object
filter
required
FilterGroup

Дерево условий; «без фильтра» — это GET /photos

object
combinator
Combinator
string
default: and
Allowed values: and or
not
Not

Отменяет всю группу

boolean
rules
required
Rules
Array
>= 1 items
One of:
FilterGroup

Дерево условий

object
combinator
Combinator
string
default: and
Allowed values: and or
not
Not

Отменяет всю группу

boolean
rules
required
Array recursive
master_id
Any of:
integer
binding
Any of:
Binding

Где лежит фото. Значения взаимно исключающие: либо портфолио, либо визит, либо нигде.

string
Allowed values: portfolio slot unbound
removed
Any of:
RemovedFilter

Что из снятого просит список: вкладку изъятого — или наоборот, ничего из снятого.

Не то же, что RemovalKind: вид — свойство строки, а это вопрос запроса, и значений у него на одно больше. none появился потому, что «без параметра» и «только в обращении» — разные вещи: без параметра приходит и своё изъятое на модерацию, иначе владелец не нашёл бы снятый кадр там, где он лежит. Пока владелец кадра и тот, кто его разбирает, — разные люди, одно поведение обслуживало оба экрана; у салона, где это один человек, общая лента работ стала показывать ему то, что он сам же снял с публикации (запрос фронтенда 06.11.2026).

Умолчание не меняется: none просят явно.

string
Allowed values: withheld trashed none
limit
Limit
integer
default: 50 >= 1 <= 200
offset
Offset
integer
0

Страница работ, подошедших под фильтр

Media type application/json
PhotosPage

Страница фото. Форма одна у списка и у поиска, чтобы клиент не разбирался, откуда пришёл ответ.

total_capped значит «больше, чем total»: точное число не считали, потому что с фильтром это заставило бы базу просмотреть все подошедшие строки.

object
items
required
Items
Array<object>
PhotoView

Фото в выдаче: карточка со ссылками, чей это мастер и оба вида тегов.

master_id и master_name берутся от владельца (photos.owner_id), а не от привязки к портфолио: владелец есть у любого фото, а привязки может не быть вовсе.

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

Поля изъятия (removed_at, removal_reason, removal_note, purge_after) лежат в основе карточки — ResponseDownloadUrl, — а не здесь: плашка нужна во всех выдачах, включая экран дня и портфолио.

object
id
required
Id
integer
created_at
required
Created At
string format: date-time
can_delete
required
Can Delete
boolean
status
required
PhotoStatus

Что с файлом работы: ссылка выдана, файл загружен, обрабатывается, готов или не получился.

string
Allowed values: pending loaded processing ready failed
urls
required
Any of:
PhotoDownloadLink

Ссылки на файл работы: сам кадр и превью.

Ссылки подписанные и временные — живут около суток (точный срок настраивается на сервере). Хранить их у себя нельзя: по истёкшей хранилище откажет. Нужна снова — запросите карточку работы, ссылка придёт новая.

object
full
required
Full

Полный кадр

string format: uri
>= 1 characters <= 2083 characters
thumb
required
Thumb

Превью: им заполняют сетки и списки

string format: uri
>= 1 characters <= 2083 characters
removed_at
Any of:
string format: date-time
removal_reason
Any of:
string
removal_note
Any of:
string
removal_marks
Any of:
RemovalMarks

Разметка вердикта целиком: версия формата и список фигур.

Пустой список принимается и означает «разметки нет»: клиенту проще прислать пустое, чем решать, опускать ли поле, а нам — записать null вместо него (см. is_empty).

object
v
required
V

Версия формата разметки; сейчас 1

integer
Allowed value: 1
shapes
required
Shapes

Фигуры на кадре, не больше 20

Array
<= 20 items
One of: discriminator: type
BoxShape

Фигура по двум точкам: прямоугольник, эллипс, стрелка, отрезок.

У всех четырёх points — это [x1, y1, x2, y2]. У прямоугольника и эллипса порядок неважен (это углы описывающего прямоугольника), у стрелки значащий: от хвоста к острию.

object
color
MarkColor

Цвет из закрытой палитры

string
default: red
Allowed values: red white black yellow cyan
w
MarkWidth

Толщина линии

string
default: mid
Allowed values: thin mid bold
type
required
Type
string
Allowed values: rect ellipse arrow line
points
required
Points

[x1, y1, x2, y2] в долях кадра; у стрелки — от хвоста к острию

Array<number>
>= 4 items <= 4 items
purge_after
Any of:
string format: date-time
master_id
required
Master Id
integer
master_name
required
Master Name
string
added_at
Any of:
string format: date-time
binding
Any of:
Binding

Где лежит фото. Значения взаимно исключающие: либо портфолио, либо визит, либо нигде.

string
Allowed values: portfolio slot unbound
slot
Any of:
SlotRef

Визит, в котором лежит фото: ровно столько, сколько нужно, чтобы его узнать и привязать замену туда же.

object
id
required
Id
integer
datetime_start
required
Datetime Start
string format: date-time
replacement_ids
Replacement Ids

Фото, загруженные мастером вместо этого — приходят только на вкладках изъятия. Метка справочная: вердикт она не снимает, изъятое возвращает только works:release

Array<integer>
tags
Tags

Теги мастера, по порядку показа

Array<object>
TagResponse

Тег справочника.

object
id
required
Id
integer
name
required
Name
string
sort
required
Sort
integer
archived_at
required
Any of:
string format: date-time
photos
Any of:
integer
group
Any of:
TagGroupRef

Группа тега внутри самого тега: столько, сколько нужно, чтобы его показать и понять, можно ли назначить.

Порядка и числа тегов здесь нет — за ними идут в справочник групп. archived_at есть: тег архивной группы назначать нельзя, и правило читается на клиенте одинаково для обоих случаев — архив у тега или у его группы.

object
id
required
Id
integer
name
required
Name
string
archived_at
required
Any of:
string format: date-time
service_tags
Service Tags

Служебные метки; мастеру пусто

Array<object>
TagResponse

Тег справочника.

object
id
required
Id
integer
name
required
Name
string
sort
required
Sort
integer
archived_at
required
Any of:
string format: date-time
photos
Any of:
integer
group
Any of:
TagGroupRef

Группа тега внутри самого тега: столько, сколько нужно, чтобы его показать и понять, можно ли назначить.

Порядка и числа тегов здесь нет — за ними идут в справочник групп. archived_at есть: тег архивной группы назначать нельзя, и правило читается на клиенте одинаково для обоих случаев — архив у тега или у его группы.

object
id
required
Id
integer
name
required
Name
string
archived_at
required
Any of:
string format: date-time
total
required
Total
integer
limit
required
Limit
integer
offset
required
Offset
integer
total_capped
Total Capped
boolean

Пример

{
"items": [
{
"status": "pending",
"removal_marks": {
"v": 1,
"shapes": [
{
"color": "red",
"w": "thin",
"type": "rect"
}
]
},
"binding": "portfolio"
}
],
"total_capped": false
}

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

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

Пример

{
"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": "В условии «tags» теги, которых нет в справочнике: [7]"
}

Салон заблокирован оператором: 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"
}