API для разработчиков

Параметры:

• в ответе contacts — контакты застройщика в том же формате, что у карточки услуги: phones, emails, websites, websites_display (домен без схемы, для показа) и social_links
• в ответе юрблок: legal_form, legal_name, unp (в каталоге услуг то же поле зовётся tax_id), registered_year и legal_checked_at — дата сверки. legal_form приходит кодом из закрытого набора: ooo, odo, oao, zao, ip, self_employed, individual. Юрданные вводятся руками или берутся из открытого реестра, поэтому без даты сверки читать их как факт нельзя. Юрадреса здесь нет
• в ответе is_claimed — карточку забрал представитель застройщика; is_verified — владелец подтвердил доступ к карточке. Ни то, ни другое не означает, что данные сверены нами с реестром
• ответ кэшируется на 60 секунд

Параметры:

• search — по названию, external_id или адресу
• status, object_type, object_type_slug, registration_open, building, city
• building_id — фильтр по дому как сущности (в отличие от building — корпуса из данных застройщика)
• фильтра по жилому комплексу здесь нет: complex_id принимает только сквозной /objects — за объектами комплекса идите туда, /objects?developer_id=ghb&complex_id=UUID
• min_price, max_price, min_area, max_area, rooms
• sort (price_asc | price_desc | area_asc | area_desc | updated_at_desc)
• group=building — свернуть квартиры одного дома в одну запись ленты; форма ответа та же, что у /objects?group=building (см. ниже). Дом сворачивается, только если под фильтр подходит 2+ его объекта
• дома и жилые комплексы, отданные источником отдельной карточкой, из выдачи исключены всегда, в том числе в ленте group=building: у них нет ни комнат, ни площади, ни цены. По прямой ссылке /developers/{id}/objects/{ext_id} такая карточка по-прежнему открывается
• attribution — own (по умолчанию) отдаёт объекты застройщика, participated — чужие объекты, где он указан соавтором или причастным
• page, page_size (макс. 100)
• в ответе currency — валюта price, estimated_price и price_per_sqm; заполнена всегда (умолчание застройщика либо переопределение объекта); сортировка price_asc/price_desc и фильтры min_price/max_price сравнивают не эту валюту, а BYN-эквивалент по последнему известному курсу НБРБ

Параметры:

• limit (1–200, по умолчанию 50)
• before — вернуть события до этой даты (ISO datetime)
• fields — ограничить историю списком полей через запятую

Параметры:

• max_points (2–2000, по умолчанию 2000) — жёсткий потолок: серия прореживается до одной точки в день, при необходимости остаются последние max_points точек
• currency в ответе — валюта объекта (переопределение объекта важнее валюты застройщика); вся серия приведена к ней пересчётом по курсам НБРБ
• rate_adjustments — участки серии, пересчитанные в currency по курсу НБРБ: before — до какого момента действует пересчёт (застройщик вёл цену в другой валюте до этой даты), from_currency — из какой валюты, rate_date/rate — курс НБРБ, использованный для пересчёта (может быть раньше before, если на этот день курс не публиковался)

Параметры:

• ответ — массив { section, image_url, thumb_url }, та же форма, что у /buildings/{building_id}/gallery
• строки наполняет джоба gallery_sync из extra источника; у pzs это рендер и планировка квартиры
• обложка объекта (поле image_url карточки) входит в галерею первым кадром, дублировать её на клиенте не нужно
• пока картинка не перекачана в наше хранилище, адреса ведут на сайт источника
• скрытый или архивированный застройщик даёт 404, как и несуществующий объект

Параметры:

• lang — язык подписи (по умолчанию ru)

Параметры:

• developer_id — ограничить одним застройщиком
• search, status, object_type, object_type_slug, registration_open, building, city
• building_id — фильтр по дому как сущности (в отличие от building — корпуса из данных застройщика)
• complex_id — фильтр по жилому комплексу; независим от building_id, потому что complex_id заполнен и у объектов без дома
• min_price, max_price, min_area, max_area, rooms
• finishing — отделка: none (без отделки), pre_finish (предчистовая), finished (с отделкой); объекты, у которых источник отделку не сообщил, не попадают ни в один срез
• completion — пресет по сроку сдачи: delivered (сдан), this_year (в этом году), next_year (в следующем), later (позже); объекты без срока сдачи не попадают ни в один пресет
• sort (price_asc | price_desc | area_asc | area_desc | updated_at_desc)
• дома и жилые комплексы, отданные источником отдельной карточкой, из плоского списка исключены: у них нет ни комнат, ни площади, ни цены. По прямой ссылке /developers/{id}/objects/{ext_id} такая карточка по-прежнему открывается. В ленте group=building исключение действует не всегда — см. карточку ленты ниже
• group=building — свернуть квартиры одного дома в одну запись ленты (см. ниже)
• page, page_size (макс. 100)
• в ответе currency — валюта price, estimated_price и price_per_sqm; в общем каталоге она разная у разных застройщиков, но сортировка по цене (price_asc/price_desc) и фильтры min_price/max_price сравнивают не эту валюту, а BYN-эквивалент по последнему известному курсу НБРБ; для валюты без известного курса объект уходит в конец сортировки, а не сравнивается сырым числом
• в ответе finishing и construction_stage — отделка и стадия строительства объекта; construction_stage — ось, независимая от status: сданный дом продолжает продаваться, а null означает, что источник о стройке молчит, а не что она не идёт

Параметры:

• since_hours — окно в часах (1–168, по умолчанию 24)
• те же фильтры, что у /objects, кроме object_type_slug и complex_id — этих двух здесь нет. Группировки group=building здесь тоже нет: ответ всегда плоский список
• дома и комплексы, отданные источником отдельной карточкой, исключены всегда — оговорки про ленту, что у /objects, здесь не действуют
• sort — те же варианты, что у /objects, плюс first_seen_at_desc (значение по умолчанию)

Параметры:

• те же фильтры, что у /objects
• total считает записи ленты, а не квартиры
• дом сворачивается, если под фильтр подходит 2+ его объекта — либо если у дома есть собственная карточка-контейнер: тогда он приходит домом даже в одиночку. Всё остальное приходит обычным объектом
• в отличие от плоского списка, карточка дома, отданная источником целиком, в ленту попадает — но только если это дом (не жилой комплекс), он привязан к сущности дома и у него есть цена за м². Как только запрошен любой из rooms, min_price, max_price, min_area, max_area, такие карточки снова исключаются: комнатность, цена квартиры и площадь к ним неприменимы
• registration_open=true — исключение из предыдущего правила: дом с открытой регистрацией приходит и в ленту, и в плоский список, причём без требований к цене и привязке. У застройщика, публикующего дом целиком, регистрация открывается именно на дом (#1957)

Параметры:

• developer_id — слаг застройщика
• city
• page, page_size (макс. 100)
• сортировка одна — по названию комплекса, параметра нет
• в выдачу попадает только ЖК, у которого есть хотя бы одно: видимая единица продажи, видимый дом (см. /buildings) либо живая карточка-контейнер — своя или дома комплекса. Цены карточка не требует: застройщик, публикующий комплекс целиком, мог её не опубликовать вовсе. ЖК вовсе без содержимого из выдачи исключён; снятые с продажи и аренда не в счёт
• в ответе buildings_count и objects_count считают только видимое: снятые с продажи и карточки-контейнеры не в счёт
• в ответе currency — валюта min_price и max_price; комплекс принадлежит одному застройщику, берётся его валюта, переопределения отдельных объектов в агрегаты не попадают
• в ответе container_prices — цена за м² с карточек-контейнеров: как самого комплекса, так и его домов. Список непустой только у комплекса, где нет ни одной видимой единицы продажи. Строки те же, что у /buildings: object_type, min_price_per_sqm, max_price_per_sqm, vat_included, currency, min_area, max_area
• в ответе container_content — содержание карточки самого комплекса: description, site_url, flats_total, area_range, ceiling_height, flats_available, sold_out и construction_stage. В отличие от container_prices карточки домов сюда не сводятся — эти поля описывают предмет карточки, а не набор: описание одного дома не описывает комплекс, и распроданный дом не делает распроданным весь ЖК. Заполняется по тому же правилу, что и цена, — только комплексу без видимых единиц продажи. Набор полей у застройщиков разный, поэтому пустое поле — норма, а не пробел в данных; null у всего объекта означает, что своей карточки нет
• в ответе container_object_id — uuid карточки-контейнера комплекса, на которую ссылается его лента изменений (GET /objects/{object_id}/history). Карточки его домов сюда не попадают — каждая описывает свой дом, а не комплекс целиком. В отличие от container_prices и container_content заполняется у любого комплекса с такой карточкой, а не только у комплекса без единиц продажи
• в ответе container_object_url — страница той же карточки у застройщика. Это не container_content.site_url: тот приходит из таблицы источника и ведёт на отдельный сайт комплекса
• в ответе container_external_id — external_id той же карточки; вместе со слагом застройщика это ключ, по которому комплекс, опубликованный целиком, кладут в «Мои объекты». Карточки домов сюда не попадают, и заполняется поле по правилу container_prices — только у комплекса без видимых единиц продажи

Параметры:

• complex_id — UUID комплекса; 404, если его нет или застройщик скрыт
• в ответе buildings — те же поля, что у /buildings; пустой список законен: часть источников публикует комплекс целиком, без разбивки на дома
• список buildings и счётчик buildings_count подчиняются тому же правилу видимости, что и /buildings: дом без единиц продажи и без цены за метр на своей карточке-контейнере в список домов ЖК не попадает
• в ответе container_prices — как у /complexes: цена за м² с карточек-контейнеров, только когда видимых единиц продажи нет вовсе
• в ответе container_object_id, container_object_url и container_external_id — то же, что у /complexes

Параметры:

• developer_id — слаг застройщика
• ids — список id домов через запятую, до 100 за запрос; пагинация при этом не применяется
• city
• kind — residential | parking | mixed. Без него паркинги в выдачу не попадают: выдача новостроек по умолчанию жилая. Спросите kind=parking явно — получите их. На выборку по ids это ограничение не распространяется: там возвращаются ровно запрошенные дома, паркинги в том числе
• page, page_size (макс. 100)
• в ответе kind — то же значение residential | parking | mixed; mixed у дома, где есть и квартиры, и паркинг
• в ответе completion_date — срок сдачи дома (может быть null)
• в ответе image_url — изображение дома, thumb_url — его уменьшенная копия для списков (может быть null)
• в ответе currency — валюта min_price и max_price; берётся у застройщика дома, переопределения отдельных объектов в агрегаты не попадают
• в ответе type_counts — состав дома под текущим фильтром: тип объекта → сколько его; счётчик в карточке дома подписывается по нему, а не словом «квартир»
• в ответе street, house, quarter — компоненты адреса, разобранные парсером, рядом с полной строкой address. address приходит от источника как есть и может не нести номер дома — house заполняется отдельно, оба поля нужны, чтобы его показать
• в ответе complex_id и complex_name — жилой комплекс дома (см. /complexes); имя стоит рядом с id намеренно, чтобы карточка дома ставила ссылку на комплекс без второго запроса. Оба поля null, если источник не разбивает застройку на комплексы
• total_count и matched_count считают только то, что видит покупатель: снятые с продажи и карточки-контейнеры (сам дом, сам комплекс) в счёт не идут
• в ответе container_prices — цена за м² с собственной карточки дома. Список непустой только у дома, где видимых единиц продажи нет вовсе: есть настоящие квартиры — цену берут по ним, и второе, расходящееся число рядом не показывается. Строка на каждую пару «тип объекта + база НДС»: object_type, min_price_per_sqm, max_price_per_sqm, vat_included (null — источник базу не указал), currency, min_area и max_area той же группы
• в ответе container_external_id — external_id той же карточки-контейнера дома; вместе со слагом застройщика — ключ, по которому дом, опубликованный целиком, можно положить в «Мои объекты». Заполняется по тому же правилу, что и container_prices — только у дома без видимых единиц продажи
• в ответе container_object_id — uuid карточки-контейнера дома, на которую ссылается его лента изменений (GET /objects/{object_id}/history). В отличие от container_external_id и container_prices заполняется у любого дома с такой карточкой, а не только у пустого: события карточки существуют независимо от того, видны ли под домом квартиры
• в ответе container_object_url — страница той же карточки у застройщика: у дома, который публикуется целиком, карточки квартиры не существует, и другого выхода на источник у него нет. Заполняется по тому же правилу, что и container_object_id
• в ответе registration_open, registration_url и registration_start_date — запись с карточки-контейнера дома. В отличие от container_prices считается у любого дома, а не только у пустого: у застройщика, публикующего дом целиком, запись открывается на дом, а не на квартиру (#1957). До открытия флаг ещё false и ссылки нет — остаётся только дата старта (#2001)

Параметры:

• в ответе street, house, quarter — компоненты адреса из парсера рядом с полной строкой address (см. /buildings)
• в ответе complex_id и complex_name — жилой комплекс дома, см. /buildings
• в ответе kind, completion_date и container_prices — те же поля, что у /buildings
• в ответе container_external_id, container_object_id и container_object_url — те же поля, что у /buildings
• в ответе registration_open, registration_url и registration_start_date — те же поля, что у /buildings

Параметры:

• search, status, object_type, object_type_slug, registration_open, city
• min_price, max_price, min_area, max_area, rooms
• sort (по умолчанию price_asc)
• page, page_size (макс. 100)

Параметры:

• ответ — массив таблиц; пустой список, если у дома нет карточек-контейнеров с ценовыми таблицами
• object_type — тип объекта карточки-источника
• kind — list (поимённый список квартир: номер, этаж, площадь, цена за метр) или matrix (цены по этажам и группам площадей; площади строки здесь нет — она спрятана в названии группы)
• headers — заголовки колонок как у источника; notes — подписи под таблицей, которые колонками не являются (условия оплаты и подобное)
• vat_included (null — источник базу не указал) и currency — общие для всей таблицы, currency берётся у застройщика дома. Показываются только рублёвые (BYN) таблицы источника: где те же квартиры продублированы в долларах, долларовая копия отбрасывается — иначе одна квартира считалась бы дважды
• rows[].cells — ячейки строки как есть (форм таблиц у источника одиннадцать, сводить их к общему набору полей значило бы часть данных выбросить); rows[].area, price_per_sqm, total_price — разобранные из cells числа, могут быть null, если соответствующей колонки не было
• rows[].total_is_estimate — true, если total_price не пришёл из своей колонки источника, а посчитан нами как area × price_per_sqm

Параметры:

• ответ — массив { section, image_url, thumb_url }
• section — slug раздела источника: layouts, site_plan, photos, construction_progress или other; подписи разделов остаются на стороне клиента
• снятая с продажи карточка-контейнер своих картинок не отдаёт — тем же правилом, что и container_prices
• пока картинка не перекачана в наше хранилище, image_url и thumb_url ведут на сайт источника; после перекачки — на наш бакет

Параметры:

• limit (1–200, по умолчанию 50) — работает как «не меньше»: страница дотягивается до границы цикла прогона, поэтому строк может прийти больше
• before — вернуть события до этой даты (ISO datetime); для следующей страницы брать next_before из ответа
• kind строки — objects_added, objects_removed, registration_opened, registration_closed, price_up, price_down или field_changed; field заполнен только у field_changed и изменений цены
• scope — building (карточка дома/ЖК, отданная источником отдельно) или units (обычные объекты продажи)
• objects_total — сколько объектов в строке всего, objects — первые десять из них
• values — заполнено только для полей из белого списка (completion_date, price, price_per_sqm), у остальных null и строка остаётся голым счётчиком. form — pair (одно old/new на всю группу) или range (группа разошлась — range_min/range_max, разброс сдвига, а не сырые значения); currency — только у price и price_per_sqm
• truncated: true — выборка упёрлась в потолок в 5000 событий, лента считана по срезу

Параметры:

• тело запроса — { channels } (необязательно): список из tg_miniapp, tg_link, tg_forward, wa, vk, ok, copy_link, copy_text, native, qr; неизвестное значение — 422. Без поля создаются ссылки на все каналы
• ответ — объект { channel: url, ..., text }: ключ — имя канала, значение — https://stroi.homes/r/{token}. Канал пропадает из ответа только если создать редирект не вышло (сбой инфраструктуры), а не потому что его не запросили
• text — готовая подпись: адрес, тип/комнатность/площадь, цена, застройщик и ссылка на основной канал (tg_miniapp, иначе copy_link, иначе первый доступный)
• developer_id — слаг застройщика, external_id — идентификатор объекта у источника; 404, если застройщик скрыт или объект не найден
• токена не требует

Параметры:

• тело запроса — { channels }, тот же формат и та же валидация, что у /objects/{developer_id}/{external_id}/share-urls
• building_id — UUID дома; мусор в пути и отсутствующий дом — 404
• text — адрес дома (город, если адреса нет), год сдачи (если есть), застройщик и ссылка; строка про цену показывается только если у дома она вообще есть — «По запросу» вместо неё не подставляется
• токена не требует

Параметры:

• тело запроса — { channels }, тот же формат, что у /objects/{developer_id}/{external_id}/share-urls
• complex_id — UUID комплекса; мусор в пути и отсутствующий комплекс — 404
• text — то же, что у дома, но иконка 🏢 и адрес — город комплекса
• токена не требует

Параметры:

• тело запроса — { channels }, тот же формат, что у /objects/{developer_id}/{external_id}/share-urls
• service_id — UUID услуги; 404 у снятой с публикации, объединённой с другой карточкой или несуществующей
• text — имя, первая категория (как есть, без перевода в человекочитаемую подпись), рейтинг и число отзывов, город (если есть) и ссылка
• токена не требует

Параметры:

• period — период в днях, 7–365, по умолчанию 30
• ответ — { total_shares, total_opens, by_channel: [{ channel, shares, opens }], period_days }
• opens считается по клик-таблице с ретеншеном 7 дней: при period больше недели shares придут за весь запрошенный период, а opens — только за последние 7 дней
• developer_id — слаг застройщика; 404, если он скрыт. Существование объекта с данным external_id не проверяется — для неизвестного external_id ответ будет нулевым, а не 404
• токена не требует

Параметры:

• period — период в днях, 7–365, по умолчанию 30
• ответ — та же форма, что у /objects/{developer_id}/{external_id}/share-stats, с той же семидневной оговоркой про opens
• service_id — существование не проверяется: для мусора в пути и несуществующей услуги ответ тоже нулевой, а не 404
• токена не требует

Параметры:

• q — строка запроса (обязательна)
• developer_id — ограничить одним застройщиком
• limit (1–20, по умолчанию 8)
• карточки домов и комплексов в подсказки не попадают — как и в каталог

Параметры:

• Тело: { "items": [{ "developer_id": "ghb", "external_id": "OBJ-101" }] }

Параметры:

• page, page_size (макс. 100)

Параметры:

• period — период в днях (7–365, по умолчанию 30)

Параметры:

• has_data — false означает, что блок показывать не стоит: по застройщику ничего не наблюдалось
• observed_since, last_change_at — момент первого и последнего наблюдённого изменения отслеживаемых полей (срок сдачи, цена)
• change_batches_90d — сколько раз за 90 дней мониторинг фиксировал изменения; единица счёта — цикл прогона, а не событие: один прогон меняет сразу много объектов
• completion_shifts_total и completion_shifts — сдвиги срока сдачи; в каждом occurred_at, old_date, new_date, shift_days (положительное — срок отодвинулся, отрицательное — приблизился), objects_total и objects (до 10 объектов группы: external_id, title)
• price_increases_total, price_decreases_total и price_moves — переоценки; в каждом occurred_at, direction (up | down), objects_total и objects — та же форма, до 10 штук
• completion_reached_total и completion_reached_buildings — дома, чей заявленный срок сдачи уже наступил (статуса «сдан» в данных нет, утверждается только наступление срока); элемент — { name, completion_date }
• truncated — true, если выборка событий упёрлась в потолок (20 000) и счётчики посчитаны по срезу
• поля completion_date и price, скрытые в /field-configs (public_value_visibility=hidden), из фактов исключаются; если скрыты оба — 404

Параметры:

• period — период в днях (7–365, по умолчанию 30)

Параметры:

• page (по умолчанию 1), page_size (1–100, по умолчанию 20)
• sort — date | helpful; без параметра выбирается автоматически по числу отзывов сущности: helpful при более чем 10, иначе date — порог не зависит от текущих фильтров
• with_photos — только отзывы с показанным (прошедшим модерацию) фото, по умолчанию false
• critical — только с оценкой ниже 4 (у объекта — по средней аспектов отзыва), по умолчанию false

Параметры:

• 422 "Entity is rated by aspects, not by stars" — прислан rating у объекта; 422 "Aspects required: …" — не хватает аспекта; 422 "Entity has no aspect ratings" / "Rating is required" — у материала и застройщика
• 403 с причиной из can_review_reason выше, если право не выполнено; 409 already_reviewed, если отзыв уже есть; 404 — сущности нет

Параметры:

• entity_type — object | developer (у material ответа не бывает)
• Тело: { "text": "…" | null }

Параметры:

• multipart/form-data, поле file — изображение

Параметры:

• Тело: { "helpful": true | false | null }

Параметры:

• Тело: { "reason": "spam" | "offensive" | "fake" | "personal_data" | "other", "comment"?: "…" }

Параметры:

• q — поиск по названию, описанию и тегам
• category, tag, country, city — фильтры справочников; карточки «по всей стране» попадают в выдачу любого города
• district — район исполнителя (до 100 символов)
• business — слаг бизнеса, витрина одной компании
• verified, has_photo, has_reviews — булевы флаги, по умолчанию false
• price_from, price_to (≥ 0), rating_min (1–5)
• object_type, provider_type, feature — коды из /services/facets
• sort (relevance | rating | reviews | price_asc | price_desc | new)
• page, page_size (1–100, по умолчанию 20)

Параметры:

• Тело: name (обязательно); также, как у карточки: description, categories, custom_categories, tags, features, object_types, provider_type, attributes, locations, price_min, price_max, price_currency, price_unit, price_notes, contacts — все необязательны
• Юрблок в теле: legal_form (код: ooo | odo | oao | zao | ip | self_employed | individual), legal_name, tax_id (УНП), registered_year (1900 — текущий год) и legal_checked_at. Прислать любое из первых четырёх без legal_checked_at нельзя — 422 «Юрданные принимаются только с датой сверки (legal_checked_at)»

Параметры:

• в ответе юрблок: legal_form, legal_name, tax_id (УНП; у застройщика то же поле зовётся unp), registered_year и legal_checked_at — дата сверки. legal_form приходит кодом из того же набора, что у застройщика: ooo, odo, oao, zao, ip, self_employed, individual. Записать юрданные без даты сверки нельзя (см. POST и PATCH ниже), на сайте блок без неё не показывается
• offerings — услуги исполнителя, каждая со своей ценой, категорией и адресом: id, title, slug (считается из title при создании и дальше не меняется), category_slug, description, price_min, price_max, price_currency, price_unit, price_notes, sort_order, status. В публичном ответе только опубликованные (status: published) — черновики сюда не попадают

Параметры:

• Тело: те же поля, что у создания (см. POST /services выше) — все необязательны, меняются только присланные
• Юрблок правится теми же полями и с тем же условием: legal_form, legal_name, tax_id или registered_year в патче требуют legal_checked_at, иначе 422

Параметры:

• Тело: те же поля, что у карточки — name, description, categories, custom_categories, tags, features, object_types, provider_type, attributes, locations, price_min, price_max, price_currency, price_unit, price_notes, contacts и юрблок (legal_form, legal_name, tax_id, registered_year, legal_checked_at) — все необязательны, плюс comment (записка модератору). Условие даты сверки то же, что у PATCH

Параметры:

• Тело: { "reason": "closed" | "duplicate" | "spam" | "other", "comment"?: "…" }

Параметры:

• entity_type — object | building | developer
• entity_id — внутренний UUID сущности (поле id в её схеме), а не external_id объекта. Невалидный UUID — 404; по хорошо сформированному UUID, которому ничего не соответствует, приходит 200 с пустым items — существование сущности эта ручка не проверяет
• отдаются только правки, ожидающие модератора: до 50 штук, новые сверху

Параметры:

• entity_type — object | building | developer; entity_id — внутренний UUID сущности
• Тело: { "field_name": "…", "suggested_value": "…", "current_value"?: "…", "source_note"?: "…" }. suggested_value обязателен и не может быть пустым, current_value — до 512 символов
• Правимые поля объекта: title, address, street, house, quarter, city, district
• Правимые поля дома: name, city, address, street, house, quarter
• Правимые поля застройщика: name, website, description
• Список именно белый: числа, даты и перечисления не правятся (их пришлось бы приводить к типу при применении), контакты застройщика — тоже, потому что подмена телефона это прямой увод лидов. Поле вне списка — 422 «Field is not editable: <имя>»
• Длина suggested_value ограничена самой колонкой; там, где у колонки нет своей длины, потолок 2000 символов. Превышение — 422. Несуществующая сущность — 404
• 201 с телом правки: id, field_name, status (всегда pending), created_at

Параметры:

• entity_type — object | building | developer; entity_id — внутренний UUID сущности
• Тело: { "reason": "duplicate" | "removed" | "wrong_photos" | "other", "comment"?: "…" } — набор причин свой, он не совпадает с набором у /services/{service_id}/reports
• Несуществующая сущность — 404

Параметры:

• Тело (необязательно): { "reasons"?: ["reasonStale"|"reasonDuplicate"|"reasonIncorrect"|"reasonStopped"|"reasonRules", ...], "comment"?: "…" }
• reasons — неизвестные ключи отбрасываются, а не отклоняют запрос; comment обрезается до 500 символов. Оба поля служебные: их видит только админ, наружу карточка их не отдаёт

Параметры:

• page, page_size (1–100, по умолчанию 20)
• is_verified в элементах — отзыв связан с закрытой заявкой к этой же карточке от того же PWA-аккаунта; сам lead_id наружу не отдаётся

Параметры:

• Тело: { "rating": 1..5, "text"?: "…", "lead_id"?: "…" }
• Ответ (201) — та же форма, что у элементов items в GET .../reviews выше, включая is_verified

Параметры:

• Тело: { "reason": "spam" | "offensive" | "fake" | "personal_data" | "other", "comment"?: "…" }

Параметры:

• Тело: { "text": "…" | null }

Параметры:

• payload зависит от game_type: у anagram — { "scrambled": "…" } (перемешанные буквы загаданного слова), у quiz — { "question": "…", "options": ["…", "…", "…", "…"] } (4 варианта, порядок каждый раз перемешан, правильный не помечен)
• attempts_left — стартовое число разрешённых неверных попыток (сейчас 3), а не текущий остаток: он не обновляется в ответах POST .../verify
• expires_at — момент, после которого задание больше не примут (сейчас через 300 секунд после выдачи)
• Идентичность автора для суточной квоты выдачи — та же логика, что у остальных публичных форм: Telegram (X-TG-Init-Data), иначе PWA Bearer, иначе IP

Параметры:

• Тело: { "solution": "…" } — для anagram: разгаданное слово без учёта регистра; для quiz: точный текст выбранного варианта из options, без учёта пробелов по краям
• challenge_id — из ответа POST /challenge
• Успешная проверка не увеличивает суточный лимит записи навсегда, а обнуляет счётчик текущих суток для той же идентичности — новый лимит копится с нуля
• Ответ (200): { "ok": true }

Параметры:

• top_limit (1–20, по умолчанию 6)
• tag_limit (1–50, по умолчанию 15)
• category_limit (1–50, по умолчанию 12)

Параметры:

• category — слаг категории
• categories — несколько категорий через запятую, объединяются с category в один список поиска; если не задан ни category, ни categories — список пустой
• limit (1–10, по умолчанию 3)
• exclude — id карточек через запятую, которые нужно пропустить
• city — не фильтрует выдачу: поднимает карточки с этой локацией в начало списка. Если совпадений нет, список не пустеет — возвращается обычный топ категории
• exclude_provider_types — форматы исполнителя через запятую, которые в подборку не годятся (например, showroom, manufacturer — те, кто продаёт, а не выполняет работы)

Параметры:

• lang — язык подписи, по умолчанию ru; при отсутствии перевода отдаётся русский
• stage — этап пути ремонта: before_deal | design | preparation | rough | finish | furnishing | moving_in. Порядок значений и есть порядок пути. С этим параметром приходят категории запрошенного этапа плюс сквозные (см. is_cross_stage)
• в ответе stage — этап категории или null, если категория вне пути
• в ответе is_cross_stage — категория покрывает несколько этапов сразу («под ключ», генподряд, технадзор) и потому попадает в выборку любого этапа

Параметры:

• q — фильтр по префиксу
• limit (1–50, по умолчанию 20)

Параметры:

• q — фильтр по префиксу
• limit (1–100, по умолчанию 20)

Параметры:

• category — обязателен

Параметры:

• q, category, tag, country, city, business, verified, has_photo, has_reviews

Параметры:

• category — слаг категории, обязателен
• city — слаг города латиницей (minsk), обязателен
• lang — язык подписи категории, по умолчанию ru
• в ответе price — ориентир цены среза: { currency, unit, min, median, max, sample_size } либо null. Считается по карточкам среза с ценой в паре «валюта + единица» — берётся самый представительный по числу карточек сегмент; медиана — по серединам ценовых вилок карточек. null, если в этом сегменте меньше 5 карточек с ценой

Параметры:

• period — период в днях (7–365, по умолчанию 30)

Параметры:

• Тело: { "name": "…", "website": "…", "notes"?: "…" }
• Ограничения длины: name — 256, website — 512, notes — 500 символов

Параметры:

• developer_id, object_id, event_type (OBJECT_APPEARED|OBJECT_REMOVED|OBJECT_UPDATED|REGISTRATION_OPENED|REGISTRATION_CLOSED|COMPLETION_SOON)
• since, until (ISO datetime)
• limit (макс. 500), page
• COMPLETION_SOON — календарное, не diff-событие: дом сдаётся в ближайшие N дней, порог настраивается на направлении. Раз в день его получают дома, чей срок сдачи вошёл в окно; object_id у такого события — синтетический building:{id}, а не id объекта

Параметры:

• developer_id — фильтр по застройщику
• event_types — через запятую (OBJECT_APPEARED, OBJECT_REMOVED, OBJECT_UPDATED, REGISTRATION_OPENED, REGISTRATION_CLOSED, COMPLETION_SOON)
• api_token — токен query-параметром (для EventSource)
• Last-Event-ID — восстановление пропущенных событий