API DomXML

Машиночитаемая схема: /api/v1/openapi.json (OpenAPI 3.1), интерактивный справочник — /api-reference.

REST API для управления шахматкой: жилые комплексы, квартиры, статусы, фиды. База: https://domxml.ru/api/v1. Для нейросетей есть MCP-сервер с теми же возможностями. Обзор возможностей и сценарии — на странице «API и MCP».

Быстрый старт

1. Создайте ключ: аватарка → API и MCP → «Создать ключ», уровень editor. Скопируйте секрет — он показывается один раз.
2. Найдите ID ЖК:

   curl https://domxml.ru/api/v1/complexes \
     -H "Authorization: Bearer dxk_ВАШ_КЛЮЧ"
   # [{"id": 1234567, "name": "Приречный", "kind": "residential", …}]

3. Получите объекты ЖК — например, свободные двухкомнатные:

   curl "https://domxml.ru/api/v1/complexes/1234567/apartments?rooms=2&status=available" \
     -H "Authorization: Bearer dxk_ВАШ_КЛЮЧ"
   # [{"id": 345, "number": "32", "floor": 5, "price": 7810000, "status": "available", …}]

4. Поменяйте цену:

   curl -X PUT https://domxml.ru/api/v1/complexes/1234567/apartments/345 \
     -H "Authorization: Bearer dxk_ВАШ_КЛЮЧ" \
     -H "Content-Type: application/json" \
     -d '{"price": 7950000}'

Правка сразу видна в панели и на витрине и попадает в журнал ЖК со способом key. Фиды пересобираются сами раз в 3 часа, если в ЖК были изменения; POST …/feeds/{feed}/generate — чтобы пересобрать сейчас.

Аутентификация

Создайте ключ в панели: аватарка → API и MCP → «Создать ключ». Секрет показывается один раз. Передавайте его в заголовке:

curl https://domxml.ru/api/v1/complexes \
  -H "Authorization: Bearer dxk_ВАШ_КЛЮЧ"

При создании ключа выбираются:

• Уровень доступа: readonly — только GET; editor — чтение и изменение; full — плюс удаление.
• ЖК: все или выбранные. Ключ с ограничением работает с путями /complexes/{id}/… своих ЖК, справочниками, фото (/apartment-images/…) и импортом-экспортом Excel — ЖК там сверяется по телу запроса и по строкам файла. Создавать новые ЖК такой ключ не может; импорт файла, где есть чужой или новый ЖК, не выполняется целиком.
• Срок: пресеты 1–30 дней или бессрочно. Отзыв в панели действует мгновенно.

Ключом закрыто всегда — только в панели, ответ 403: профиль и вход (/auth), выпуск ключей (/apikeys) и подключений нейросетей (/oauth), обращения в поддержку (/support), уведомления (/notifications), партнёрская программа (/partner), управление доступами к ЖК (любой путь с /access), подключение Битрикс24 (/b24). Каналы публикации — только с отдельным разрешением ключа, а удаляются только в панели (ниже).

Основные эндпоинты

Проекты (ЖК, посёлки, паркинги…), застройщик, корпуса

Квартиры

Фото и планировки

Уже загруженные файлы можно привязать и при создании квартиры: поля imageIds и floorPlanIds.

Любую загруженную картинку сервер пережимает сам: не больше 1920 пикселей по большей стороне, JPEG с качеством 85, поворот по EXIF, прозрачный фон — белым, метаданные (в том числе координаты съёмки) удаляются. Исходник — JPEG, PNG или WebP до 40 МБ; повреждённый файл отклоняется с ошибкой 400.

Планировка квартиры — поле floorplanUrl, а если оно пустое, первая привязанная планировка (imageType: "floorplan"). Так её читают снимок (floorPlan), фиды и проверка фида, поэтому заполнять floorplanUrl после bulk-add не нужно.

Ссылка на страницу квартиры для фидов VK Рекламы и Яндекс Директа — поле pageUrl: полный адрес http(s)://… на вашем сайте, до 500 символов. Его берут фиды, где включён «Ваш сайт» (adLinks ЖК), а где его нет — шаблон; пусто (null или "") — снять. В Excel — колонка «Ссылка на страницу» (BF), пустая ячейка ссылку не снимает.

Фиды и импорт

Яндекс, Циан и Авито получают квартиры как новостройку от застройщика. Квартиры без цены или общей площади в эти три фида не попадают.

Фиды для рекламы. vk — каталог недвижимости VK Рекламы (Центр коммерции, собственный формат VK), direct — фид недвижимости Яндекс Директа для товарных объявлений ЕПК и товарных кампаний. В них попадают свободные квартиры со ссылкой на свою страницу (для VK — ещё и с планировкой или фото), а ЖК — отдельной позицией или каталогом. Ссылка берётся из шаблона objectUrlTemplate у ЖК (например, https://site.ru/flats/{number}; подстановки {number}, {id}, {building}), а если он пуст — со страницы квартиры на опубликованной витрине. Без ссылок, города (и для VK — региона и адреса), а для Директа — без названия застройщика фид не собирается: ответ 400 со списком.

Виды проектов

Проект — это ЖК, коттеджный посёлок, паркинг, бизнес-центр, отдельный дом или вторичка агентства. Вид задаёт поле kind проекта: от него зависят объекты, которые в нём заводятся, назначения зданий и площадки фидов.

• При создании вид передаётся в POST /complexes: код или подпись из GET /dictionaries (complex.kind). Без поля — residential. В ответах GET /complexes и GET /complexes/{id} — kind и feedPlatforms.
• Смена вида — PUT /complexes/{id} с kind. Отказ — 422 с loc: ["body", "kind"] и перечнем причин: в проекте есть объекты другого вида, объектов больше, чем допускает вид (у дома — один), есть здания с неподходящим назначением, каталог проектов домов не у посёлка или включены фиды площадок, недоступных новому виду (выключите или удалите их).
• Отдельный дом — один объект. Второй объект в проекте house не создаётся — ни в REST (в том числе …/apartments/bulk), ни в MCP, ни из Excel: 422 «В проекте «Отдельный дом» — один дом…». Каждый дом — своим проектом со своим адресом; несколько домов в одном месте ведите коттеджным посёлком.
• Вид объекта по проекту. Объект вида, которого в проекте не бывает (гараж в ЖК, квартира в паркинге), — 422 с перечнем допустимых видов. Если kind объекта не прислан, у паркинга создаётся машиноместо, у коммерческой недвижимости — помещение, у дома — дом.
• Площадки. Паркинг и коммерция вне ЖК уходят только в VK Рекламу и Яндекс Директ: Домклик, Яндекс Недвижимость, Циан и Авито принимают их только в составе ЖК из своего каталога новостроек. Посёлок и дом — без Домклика, дом — ещё и без VK (VK нужно от трёх объектов в каталоге). Фид недоступной площадки не создать: 422 с loc: ["body", "platform"] и ctx.allowed — при создании, предпросмотре и правке фида, в …/feeds/{type}/toggle и во флагах domclickEnabled, cianEnabled, yandexEnabled проекта.
• Нежилое по умолчанию. У паркинга и коммерции оно и есть товар: при создании проекта включено для VK и Директа (premisesFeeds), а новый фид без premises получает всё, что площадка принимает из видов проекта.
• Сводка правил — GET /dictionaries, ключ complex.kindRules: по каждому виду label, objectKinds, maxObjects, buildingPurposes, feedPlatforms, premisesFeeds.

Паркинг и коммерция внутри ЖК остаются в ЖК — зданиями с назначением parking или commercial — и уходят на все площадки, кроме Домклика.

Новый проект: застройщик, готовность, шаблон Excel

Те же ручки, что у мастера «Добавить» в панели: проект с застройщиком — одним запросом, затем объекты из Excel по шаблону проекта и чек-лист готовности.

curl -X POST https://domxml.ru/api/v1/complexes \
  -H "Authorization: Bearer dxk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"name": "Паркинг на Ленина", "kind": "parking", "city": "Казань",
       "developer": {"name": "ООО «СЗ Восток»"}}'
# 201 {"id": 1234590, "kind": "parking", "feedPlatforms": ["vk", "direct"], …}

• developer в POST /complexes: {"name": "…"} — новый застройщик с этим названием (ИНН и реквизиты — потом, PUT …/developer); {"fromComplexId": N} — застройщик синхронизирован с застройщиком проекта N, как …/developer/sync-from: правка реквизитов расходится по всем проектам с ним. Проект N должен быть доступен вам на правку. Без поля — заглушка «Застройщик {название}», как раньше. Иное значение — 422. Ключ, ограниченный списком ЖК, проекты не создаёт.
• GET /developers — застройщики проектов, которые вы можете править, без повторов (по ИНН, без ИНН — по названию) и без заглушек:

  {"developers": [{"complexId": 12, "complexName": "Заречье", "name": "ООО «СЗ Восток»",
                   "inn": "1655123456", "projects": 3, "complexIds": [12, 40, 41]}]}

  complexId — проект-источник: его передают как developer.fromComplexId. Ключу, ограниченному списком ЖК, — 403.
• GET /complexes/{id}/readiness — «Что сделать для работы»: {complexId, kind, done, total, ready, items}, у каждого пункта key, title, done, hint и section — раздел панели. Пункты: developer — название застройщика не заглушка и ИНН из 10 или 12 цифр; contacts — город и телефон отдела продаж (или застройщика) из 10 цифр; photos — фото проекта; objects — объекты в продаже; feed — последний выпуск хотя бы одного включённого фида успешен и не пуст; showcase — опубликованная витрина с этим проектом. Названия и подсказки — по виду проекта.
• GET /import-export/template?complex_id=N — шаблон Excel под проект: без листов «Застройщик» и «ЖК» (данные проекта правятся в панели, файл их не перезапишет), лист «Корпуса» — по виду (у отдельного дома его нет), на листе «Квартиры» — примеры объектов этого вида с ID проекта. Заполненный файл загружается обычным импортом (/import-export/import/preview).

Виды объектов, гаражи и посёлки

Квартиры, коммерция, машиноместа, кладовые, гаражи, участки и дома — объекты одного списка /complexes/{id}/apartments. Вид задаёт поле kind, по умолчанию flat. Какие виды можно завести, зависит от вида проекта (kind у самого проекта):

Вид, который не подходит проекту, отклоняется с 422. Отобрать объекты одного вида — GET …/apartments?kind=parking. Справочные поля принимают код или подпись из GET /dictionaries.

• Нежилое (commercial, parking, storage): commercialUse (office, free, retail, catering, warehouse), entranceType (street, yard), separateEntrance, vat (included, not_included, none), parkingType (underground, multilevel, covered, open), secured.
• Гараж (garage, только в проекте parking): garageType — brick (кирпичный), concrete (железобетонный), metal (металлический), box (бокс в ГСК или паркинге); secured — охрана. Площадь, цена и этаж — общие поля; этаж у гаража необязателен: пусто — отдельно стоящий, −1, −2 — подземные уровни. В Excel — колонка BG «Тип гаража» листа «Квартиры». В VK Рекламу и Яндекс Директ гараж уходит как машиноместо.
• Участки, дома, таунхаусы: landArea — площадь участка в м², cadastralNumber, landCategory (settlements, agricultural, other), landUse (izhs, lph, gardening, dnp, farm), utilities — коммуникации {"gas", "electricityKw", "water", "sewerage"}, saleMode (plot_only, with_contract, both — без подряда, только с подрядом, с подрядом или без), wallMaterial, houseStage (ready, construction, to_order), builtYear, street, houseProjectId — проект дома из каталога посёлка, planShape — контур на генплане. Площадь дома — areaTotal, этажность — totalFloors.
• Вторичка (проект resale): адрес у каждого объекта — region, city, district, street, houseNumber (полный address соберётся сам) или address целиком; latitude, longitude; flatNumber — номер квартиры: уходит только в фиды (площадки проверяют его при модерации), в снимок и на витрину — нет; metro — до 5 станций [{"name", "minutes", "by": "foot" | "transport"}]; дом — houseType (brick, panel, monolith, monolith-brick, block, wood, stalin), passengerLifts, cargoLifts, garbageChute, builtYear; renovation (none, cosmetic, euro, design, needs_repair), saleKind (free, alternative), haggle, ownersCount, ownershipYears; комната — rooms (всего в квартире), roomsOffered (в продаже), flatArea (площадь квартиры; areaTotal — площадь комнаты); roomLayout (isolated, adjoining, mixed), commercialParking (none, street, building); internalId — внешний ID (ID объявления в вашей CRM, по нему импорт фида обновляет объект). Номер объекта — номер лота A-0001: у нового объекта его можно не передавать. Список фильтруется по ?city= и ?agent=. Договор, комиссия, цена «на руки» и собственники объекта по API-ключу недоступны (пути …/listing и …/owners — только из панели); назначают агента и собственников тоже в панели. Имя и рабочий телефон ответственного агента публикуются с объектом — в фидах и в снимке.
• Посёлок — поля ЖК: highway и distanceKm — шоссе и расстояние от города, settlement — описание и значения по умолчанию для участков: {"landCategory", "landUse", "utilities", "security", "roads", "feeMonthly"}; ID в справочниках площадок — yandexVillageId, cianKpId. Очереди посёлка — корпуса с назначением phase.

Что уходит в фиды. Квартиры попадают во все фиды. Участки, дома и таунхаусы — во все, кроме Домклика. Нежилое — только туда, где оно отмечено у фида (premises в POST/PATCH …/feeds) и где площадка его принимает: Яндекс и Авито — коммерция и машиноместа, Циан — коммерция, машиноместа и кладовые, VK — коммерция, машиноместа, кладовые и гаражи, Директ — машиноместа и гаражи. Какие площадки вообще доступны проекту — по его виду (выше). Прежнее поле ЖК premisesFeeds ({"yandex": ["commercial", "parking"]}) по-прежнему принимается и меняет стандартные фиды площадок; для новых интеграций используйте premises у фида.

В снимке и дельтах у объекта есть kind, у участков, домов и таунхаусов — ещё landArea, street, saleMode, houseStage, planShape (в профиле full — и остальные поля посёлка), а у ЖК-посёлка — блок complex.settlement: генплан, шоссе, значения по умолчанию и каталог проектов домов. У объектов вторички — address, city, district, lat, lon, в профиле full — ещё метро, дом, ремонт, сделка, комнаты и agent (имя и рабочий телефон ответственного, как в объявлениях); номера квартиры в снимке нет.

Поля и типы

Имена полей принимаются и в camelCase (areaTotal), и в snake_case (area_total). Отсутствующее поле не меняется, null очищает значение.

• Типы проверяются. Значение не того типа, слишком длинная строка или число вне диапазона — ответ 422 с именем поля в loc. Число в строковом поле принимается как текст ("entrance": 1), число в строке — как число ("price": "5000000"), пустая строка в числовом поле — как null.
• Корпус задаётся через buildingId и должен принадлежать этому ЖК. Название корпуса подставляется в building само.
• Часовой пояс ЖК (timezone) — смещение от UTC: +5, UTC+5, +05:00, или IANA-имя пояса России (Asia/Yekaterinburg). Хранится как +5. Если не передан, определяется по region или city, иначе +3.
• Срок сдачи задаётся у корпуса (builtYear, readyQuarter 1–4) и у ЖК (completionYear, completionQuarter). У корпуса без срока берётся срок ЖК.
• ID в справочниках площадок нужны, чтобы объявления привязались к ЖК и корпусу: у ЖК — yandexBuildingId, cianJkId, avitoDevelopmentId, у корпуса — yandexHouseId, cianHouseId, avitoDevelopmentId. Справочники: Яндекс (3-й и 7-й столбцы), Циан, Авито (ID корпуса; ID ЖК — только если корпусов нет).
• Справочные поля — finishing, classType, buildingType, buildingState — принимают код, подпись или синоним из GET /dictionaries. Незнакомое значение сохраняется, но площадки его не примут: /feeds/validate об этом предупредит.

Одно поле в разных местах

REST управляет данными, снимок — публичный контракт для сайтов с короткими именами и своей версией (contract), инструменты MCP принимают аргументы в snake_case.

roomsKind — вид планировки одной строкой: studio — студия, euro2, euro3… — евроформат (euroPlan: true, цифра — значение rooms), 1, 2, 3… — классическая, число комнат.

internalId в снимок не попадает: снимок же отдаёт публичный канал витрины, а внутренние номера наружу не уходят. Для сопоставления храните id квартиры DomXML или берите internalId из GET /complexes/{id}/apartments.

В снимке у каждого корпуса (complex.buildings) есть completionYear и completionQuarter — срок сдачи корпуса или ЖК.

Синхронизация шахматки: версия, снимок, изменения

Чтобы держать шахматку на своём сайте в актуальном состоянии, не нужно скачивать её целиком. Сначала спросите версию — это одна строка из базы, — и качайте данные, только если она изменилась.

Версия ЖК растёт при любом изменении, которое видно покупателю: цена, статус, площадь, фотографии, корпуса, акции, данные самого ЖК. Служебные правки её не двигают.

# 1. дёшево узнаём, изменилось ли что-нибудь
curl -H "Authorization: Bearer dxk_КЛЮЧ" \
  https://domxml.ru/api/v1/complexes/1234567/version
# {"rev": 42, "changedAt": "...", "apartments": {"available": 180, "total": 344},
#  "snapshotUrl": "/api/v1/complexes/1234567/snapshot?rev=42"}

# 2. если rev вырос — забираем только изменения
curl -H "Authorization: Bearer dxk_КЛЮЧ" \
  "https://domxml.ru/api/v1/complexes/1234567/changes?since=41"

# 3. или снимок целиком: адрес с rev неизменяем, его можно кэшировать навсегда
curl -H "Authorization: Bearer dxk_КЛЮЧ" \
  "https://domxml.ru/api/v1/complexes/1234567/snapshot?rev=42"

Надёжнее всего сверять rev из /version с сохранённым у себя: совпал — ничего не качать. Адрес snapshotUrl с ревизией неизменяем, его можно кэшировать навсегда. Снимок отдаётся и с заголовком ETag (если ответ пришёл сжатым, nginx помечает его как слабый: W/"…") — его можно вернуть в If-None-Match как есть.

complexChanged: true в ответе /changes значит, что менялись данные самого ЖК — например, описание, корпуса или акции. Их в дельте нет: перечитайте блок complex из снимка. Изменения объектов при этом приходят как обычно, в items и deleted.

Дельта с profile=full отдаёт квартиры в том же виде, что снимок, вместе с images и floorPlan.

Журнал изменений хранится 30 дней и минимум 50 ревизий. Если запрошенная версия уже забыта, ответ придёт с "fullRequired": true — значит, нужно перекачать снимок целиком.

Публичное API виджета и витрины

Этот раздел — для кода, который работает в браузере посетителя: сам виджет, витрина или ваш скрипт на сайте. Авторизации нет, вместо неё — ключ канала dxp_, который создаётся в панели вместе с виджетом или витриной. Ключ виден в исходном коде страницы и секретом не является: доступ ограничивают список разрешённых доменов и лимиты запросов.

fetch('https://domxml.ru/api/public/v1/dxp_КЛЮЧ/version')
  .then(r => r.json())
  .then(v => fetch(`https://domxml.ru/api/public/v1/dxp_КЛЮЧ/apartments?v=${v.version}`))
  .then(r => r.json())
  .then(data => console.log(data.complexes[0].apartments.length));

Ограничения: 240 запросов в минуту с одного адреса и 1200 в минуту на канал, сверх — 429. Если канал выключен или удалён, ответ — 404: по ключу нельзя узнать, что витрина существует, но скрыта.

Домены. Если у канала задан список доменов, запрос должен прийти с одного из них: сервер смотрит заголовок Origin, а без него — Referer. Браузер присылает их сам, а запрос без обоих заголовков — curl или ваш сервер — получит 403 «Этот виджет не разрешён на текущем домене». Для проверки из терминала передайте заголовок явно:

curl https://domxml.ru/api/public/v1/dxp_КЛЮЧ/version \
  -H "Origin: https://ваш-сайт.ru"

Канал с пустым списком доменов отвечает любому сайту и запросам без заголовков. Серверу, который синхронизирует шахматку, удобнее REST API с ключом dxk_ (выше): там проверки домена нет.

Заявка с сайта

Форма на вашей странице может отправлять заявку тем же ключом — она попадёт в CRM как клиент со статусом по умолчанию и источником «Виджет». Обязательны имя и телефон; всё остальное по желанию.

fetch('https://domxml.ru/api/public/v1/dxp_КЛЮЧ/leads', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Пётр',
    phone: '+7 917 000-11-22',
    apartmentId: 96,             // из снимка, необязательно
    comment: 'Перезвоните после 18',
    utm: { utm_source: 'yandex' },
    ft: Date.now() - formOpenedAt, // сколько форма была открыта, мс
    company: ''                  // ловушка для ботов: поле должно остаться пустым
  })
}).then(r => r.json());

Ответ — {"ok": true}. Он одинаков и для новой карточки, и когда человек уже писал с этого телефона: во втором случае заявка ложится записью в его карточку, а не создаёт дубль. По ответу нельзя проверить, есть ли телефон в вашей базе.

Два поля нужны против ботов. company прячут от человека стилями — если оно заполнено, заявка тихо отбрасывается. ft — сколько миллисекунд форма была открыта: меньше полутора секунд считается автоматической отправкой. В обоих случаях ответ тот же {"ok": true}, чтобы по нему нельзя было подобрать обход. Лимиты: 10 заявок в час с одного адреса и 5 в сутки с одного телефона, дальше — 429.

Если в настройках канала включена галочка согласия, передавайте consent: true — иначе придёт 400. Вместе с заявкой сохраняются метки рекламы, адрес страницы и текст согласия, который видел посетитель.

Каналы публикации

Виджеты и витрины создаются в панели, но ими же можно управлять по API — например, завести по виджету на каждый ЖК скриптом. Канал принадлежит проекту CRM: собирается из его ЖК, заявки с него приходят в его CRM.

Узкие ручки безопаснее широкого PATCH: скрипт, который раз в месяц меняет акцентный цвет, не затрёт блоки витрины. Что можно прислать в каждое поле, отвечает /channels/schema.

Ключу нужно отдельное разрешение. Управление каналами не входит в «Чтение и редактирование»: витрина видна всему интернету, и ключ синхронизации цен не должен её трогать. При создании ключа включите «Управление витриной и виджетами», а чтобы ключ мог ещё и включать канал — подопцию «и публиковать». Без них придёт 403 с объяснением, чего не хватает. Удалять каналы ключом нельзя никогда — только в панели.

Сотрудникам застройщика права выдаются в CRM → Настройки → Команда: «Витрина» — собирать и менять каналы, «Публикует» — включать их. Маркетолог собирает, руководитель публикует.

В ответе приходят embedCode — готовая строка для вставки на сайт, previewUrl — адрес предпросмотра, apiUrl — корень публичного API канала, stats — показы и заявки за 30 дней и updatedAt — когда канал последний раз меняли или включали.

Новый канал создаётся выключенным: сначала предпросмотр, потом публикация отдельным вызовом. Так неудачная автоматическая настройка не попадёт в интернет сама.

Квиз — отдельная запись проекта CRM (ниже), витрина на неё ссылается: quizId — кнопка и адрес /quiz, floatingQuizId — плавающий чат на страницах витрины. on: true у витрины без квиза заводит ей квиз со стандартным набором шагов. Кнопка и /quiz работают только у опубликованного квиза того же проекта; иначе адрес /quiz отвечает 404 и пропадает из карты сайта витрины.

Свой домен витрины задаётся тем же полем domains, что и список доменов виджета: витрина открывается по нему, как только домен направлен на сервис (DNS и сертификат подключает поддержка).

Для витрины (kind: "showcase") обязателен slug — адрес вида v.domxml.ru/{slug}. Оформление блоков лежит в blocks: незаполненные поля считаются из карточки ЖК, поэтому пустую строку слать не нужно — она перекроет умолчание.

Опубликовать витрину не получится, пока не заполнены застройщик и ИНН в карточке ЖК, ссылка на проектную декларацию (blocks.legal.declarationUrl) и ссылка на политику обработки персональных данных (settings.policyUrl): по 214-ФЗ и закону о рекламе они обязательны.

Квизы и чат-боты

Квиз — запись проекта CRM, как фид: создаёте, настраиваете, получаете постоянную ссылку https://v.domxml.ru/q/{code} и код вставки на сайт. Режим steps показывает сценарий по шагам, chat — диалогом чат-бота; заявки, статистика и вставка у них общие. До 20 квизов на проект CRM. Права и разрешения ключа — как у каналов: «Управление витриной и виджетами», публикация — подопцией «и публиковать»; удаление — только в панели. Обзор для маркетолога — страницы квиза и чат-бота.

Поля

Ссылки на картинки и политику — https:// или свой путь /uploads/…. Неизвестное поле, блок или шаг, который не подходит виду проекта, — 400 с объяснением, а не молчаливый пропуск.

curl -X POST "https://domxml.ru/api/v1/quizzes?crm=CRM_ID" \
  -H "Authorization: Bearer dxk_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{
    "title": "Подбор квартиры — реклама VK",
    "complexIds": [1234567],
    "mode": "steps",
    "preset": "short",
    "closing": { "type": "bonus_form", "bonus": "Скидка 2% при бронировании" },
    "content": { "advantages": [{ "icon": "key", "text": "Ключи в 2027 году" }] },
    "design": { "theme": "auto", "color": "#2E5BFF", "layout": "cover-left" },
    "settings": { "policyUrl": "https://ваш-сайт.ru/privacy" }
  }'

Закрытия

Тексты закрытий готовые, title меняет заголовок. Контакты — всегда последний шаг, в steps и blocks их не перечисляют.

Вставка на сайт

<!-- плавающая кнопка -->
<script src="https://v.domxml.ru/s/quiz-embed.js" data-quiz="CODE" async></script>

<!-- блоком в странице -->
<div id="dx-quiz-CODE"></div>
<script src="https://v.domxml.ru/s/quiz-embed.js" data-quiz="CODE" data-target="#dx-quiz-CODE" async></script>

Квиз открывается в рамке с v.domxml.ru, поэтому стили сайта его не задевают. Загрузчик передаёт в квиз адрес страницы и utm-метки, а цели — в Метрику сайта: атрибут data-metrika или metrikaId квиза. Цели: quiz_view, quiz_start, quiz_step_N, quiz_contact, quiz_lead.

Публичные ручки квиза

Их вызывают страница квиза и загрузчик. Авторизации нет — вместо неё код квиза и список domains (сверяются Origin, Referer и заголовок окна вставки). Выключенный и удалённый квиз отвечает 404.

Антиспам и лимиты заявок — как у формы канала: ловушка company, время заполнения ft, 10 заявок в час с адреса и 5 в сутки с телефона. Ответов — до 20, ответ — до 300 знаков, меток — до 10 по 200 знаков.

Статистика

GET /api/v1/quizzes/42/stats?days=30

{
  "days": 30, "views": 1240, "starts": 612, "contacts": 288, "leads": 97,
  "startRate": 49.4, "contactRate": 47.1, "conversion": 7.8,
  "byDay": [{ "day": "2026-10-01", "views": 51, "starts": 24, "contacts": 11, "leads": 4 }]
}

startRate — начали из открывших, contactRate — дошли до контактов из начавших, conversion — заявки из показов, в процентах; без базы — null.

Заявка из квиза создаёт клиента CRM с источником «Квиз» (режим chat — «Чат-бот»), в ленту пишутся ответы и обещанный бонус, в Битрикс24 уходят пары «вопрос: ответ», в вебхук lead.created — quizId, quizCode, quiz и bonus. MCP: инструменты quiz_* (документация).

Вебхуки

Вместо опроса API можно получать события запросом на свой адрес. Подписка создаётся в панели (API и MCP → Вебхуки) или по API.

События: lead.created, client.created, client.status_changed, apartment.booked, apartment.released, apartment.sold, deal.created, deal.lost (только по сделкам: отказ от интереса и снятая бронь сюда не попадают), complex.changed, channel.published; агентская программа — fixation.created, fixation.activated, fixation.extended, fixation.closed, fixation.confirmed (клиент ответил, работает ли с агентом), showing.requested, showing.confirmed, showing.done, showing.cancelled, booking.requested, booking.decided, commission.created, commission.updated (застройщику — по его ЖК, агенту и руководителю агентства — по их закреплениям).

Что приходит

POST https://ваш-сервер.ru/domxml-hook
Content-Type: application/json
X-DomXML-Event: lead.created
X-DomXML-Delivery: 8241
X-DomXML-Timestamp: 1789902000
X-DomXML-Signature: sha256=2f1c…

{
  "event": "lead.created",
  "createdAt": "2026-09-20T11:00:00Z",
  "data": {
    "clientNumber": 42,
    "isNewClient": true,
    "name": "Пётр",
    "phone": "+7 917 000-11-22",
    "source": "Витрина",
    "channelKey": "dxp_…",
    "complexId": 1234567,
    "apartmentId": 96,
    "quizId": null,
    "quizCode": null,
    "quiz": [],
    "bonus": null,
    "utm": { "utm_source": "yandex", "utm_campaign": "zarechye" }
  }
}

channelKey — ключ канала (виджета или витрины), с которого пришла заявка; utm — метки рекламы, которые прислала форма (не было — пустой объект). isNewClient: false — человек уже был в CRM, заявка легла в его карточку.

Заявка из квиза или чат-бота приходит с source «Квиз» или «Чат-бот», channelKey: null, номером и кодом квиза, ответами и обещанным бонусом:

"source": "Квиз",
"channelKey": null,
"quizId": 42,
"quizCode": "k7m2x9q4p1az",
"quiz": [
  { "key": "rooms", "question": "Сколько комнат нужно?", "answer": "2-комнатная" },
  { "key": "budget", "question": "Какой бюджет комфортен?", "answer": "7,5–9,5 млн ₽" },
  { "key": "pay", "question": "Как планируете оплату?", "answer": "Ипотека" }
],
"bonus": "Скидка 2% при бронировании"

Событие complex.changed несёт новую и прежнюю ревизию — по ним можно сразу запросить /changes?since=, не вызывая /version:

{
  "event": "complex.changed",
  "createdAt": "2026-09-23T09:00:00Z",
  "data": {
    "complexId": 1234567,
    "name": "ЖК «Приречный»",
    "rev": 43,
    "previousRev": 42
  }
}

Проверка подписи

Секрет выдаётся один раз при создании подписки. Подпись считается от строки «метка времени, точка, тело запроса» — метка внутри подписи не даёт переиграть старый запрос:

signature = "sha256=" + hmac_sha256(secret, timestamp + "." + raw_body)

Сравнивайте подписи функцией с постоянным временем сравнения и отклоняйте запросы старше пяти минут по X-DomXML-Timestamp.

Повторы

Ответ 2xx считается доставкой. При любом другом ответе или ошибке сети запрос повторяется через 1, 5, 30, 120 и 360 минут, после чего доставка помечается неудачной и остаётся в журнале. После 20 неудач подряд подписка выключается сама, а владелец получает уведомление — так отвалившийся навсегда адрес не копит очередь.

Отвечайте быстро: приёмнику даётся 10 секунд. Тяжёлую работу ставьте в свою очередь, а нам отвечайте сразу. Переходы по редиректам не выполняются, адрес должен быть публичным и на https.

CRM для застройщика

CRM — это проект: отдел продаж со своими ЖК, командой, клиентами, настройками, витринами и виджетами. У аккаунта может быть несколько проектов и приглашения в чужие. Доступ к ЖК и доступ к CRM независимы: менеджеру продаж шахматка не нужна, а редактор шахматки не видит клиентов.

Ключ без ограничения по ЖК работает с CRM так же, как пользователь в панели, в пределах прав владельца ключа в проекте («только свои», правка чужих, удаление, смена ответственного, задачи другим, администратор). Ключ с ограничением по ЖК к /crm не допускается — используйте MCP. {owner} в путях — публичный ID проекта (publicId из GET /crm/workspaces; у CRM, созданных до проектов, он совпадает с публичным ID владельца, поэтому старые интеграции работают). Клиент адресуется номером {number} в рамках проекта.

Смена статуса квартиры через PUT /complexes/{id}/apartments/{aid} при активной брони клиента отвечает 409 с полем crmBooking; повторите запрос с "force": true, чтобы снять бронь. Номер и имя клиента в crmBooking приходят только участнику его проекта CRM, остальным — null, а в crmName и holder — название проекта.

Агентская программа

Застройщик запускает программу по своему ЖК: условия (вознаграждение, шкала, правила закрепления клиента, что разрешено), участники — агенты и агентства (агентство — проект CRM вида agency). Агент закрепляет клиента по телефону, записывает на показ, просит бронь; застройщик решает в своей CRM. API подходит агентствам со своей CRM (amoCRM, Битрикс24 через Make или n8n): закрепление и статусы — ключом, события — вебхуками fixation.*, showing.*, booking.*, commission.*. Ключ с ограничением по ЖК работает только с условиями программ своих ЖК (/complexes/{id}/agent-program); закрепления, показы, бронь и начисления ему недоступны.

Агенту (свои закрепления; руководитель и администраторы агентства — все закрепления агентства):

Застройщику ({owner} — проект CRM отдела продаж; право «Агенты: видит», решения — «Агенты: управляет»; показы подтверждает и «видит»):

Клиенты агентов в CRM застройщика помечены полем agent и отбираются фильтром GET /crm/{owner}/clients?agent=1. Отметка «куплена» по клиенту агента с действующим закреплением создаёт начисление вознаграждения автоматически.

Примеры

Изменить цену квартиры

curl -X PUT https://domxml.ru/api/v1/complexes/12/apartments/345 \
  -H "Authorization: Bearer dxk_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"price": 5200000}'

Пересобрать фид Домклик

curl -X POST https://domxml.ru/api/v1/complexes/12/feeds/domclick/generate \
  -H "Authorization: Bearer dxk_ВАШ_КЛЮЧ"

Вызывать generate после каждой правки не нужно: фиды пересобираются сами раз в 3 часа, если в ЖК что-то поменялось. generate — чтобы площадка получила изменения сейчас.

Готовый фид всегда доступен по постоянной ссылке https://feed.domxml.ru/{type}/complex_{id}.xml. Прежний адрес https://domxml.ru/feeds/{type}/complex_{id}.xml отдаёт тот же файл — ссылки, уже переданные площадкам, продолжают работать.

Пагинация

Большинство списков отдаётся целиком. Постранично — там, где записей может быть много: параметры limit и offset.

• GET /crm/{owner}/clients — limit по умолчанию 50, до 500; ответ {"items", "total", "limit", "offset"}.
• GET /crm/{owner}/tasks — limit по умолчанию 100, до 500.
• GET /complexes/{id}/changelog — limit по умолчанию 100, до 500; ответ — массив без общего числа: пришло меньше limit — записи кончились.

Объекты ЖК (GET /complexes/{id}/apartments) приходят все сразу. Чтобы не качать их каждый раз, берите только изменения: /apartments/delta или /changes (синхронизация).

CORS

REST API (/api/v1) — для вашего сервера, а не для браузера. Запросы со страниц чужих сайтов браузер не пропустит: CORS открыт только панели DomXML. Да и не нужно: ключ dxk_ в коде страницы увидел бы любой посетитель. Для браузера есть публичное API с ключом канала dxp_ — оно отвечает Access-Control-Allow-Origin: * и отдаёт ETag наружу.

Коды ошибок

Всегда JSON вида {"detail": "текст"}.

У 422 в detail — массив ошибок по полям:

{"detail": [{"type": "string_too_long", "loc": ["body", "salesPhone"],
             "msg": "Не длиннее 20 символов", "input": "…"}]}

При массовом создании в loc есть номер квартиры в массиве: ["body", "apartments", 3, "price"].

Фид площадки, недоступной виду проекта:

{"detail": [{"type": "value_error", "loc": ["body", "platform"], "input": "cian",
             "msg": "Циан принимает паркинги и коммерцию только в составе ЖК из своего каталога новостроек — у отдельного паркинга и гаражей доступны VK Реклама и Яндекс Директ",
             "ctx": {"allowed": ["vk", "direct"]}}]}

Общего лимита числа запросов по ключу dxk_ нет; массовые операции — до 500 объектов за запрос.

Безопасность

• Секрет ключа показывается один раз, в базе хранится только его хэш. Ключ отзывается в разделе «API и MCP» — сразу.
• У каждого ключа — уровень, список ЖК и срок. Ключ не выпускает другие ключи и не выдаёт доступы.
• Правки ЖК и объектов по ключу пишутся в журнал ЖК со способом key, через MCP — mcp; изменения каналов — в журнал канала (/channels/{id}/log).
• Доступ поддержки. Поддержка не заходит в ваш аккаунт сама. Если в обращении нужна правка, вы выдаёте временный ключ — галочкой при обращении или кнопкой «Разрешить» в ответе поддержки. Он действует 5 дней, виден в «API и MCP», отзывается в любой момент и сам — при закрытии обращения. Такой ключ работает только по REST и только с вашими ЖК (чужие, к которым вам открыли доступ, он не видит), ничего не удаляет; CRM и витрины — только если вы их отметили, публиковать витрины не может. Его правки помечены в журнале ЖК как support — «через поддержку».