API шахматки: версия, дельты и вебхуки
Интеграция для тех, кому нужна не готовая вставка, а свои страницы. Данные отдаются так, чтобы их не приходилось выкачивать целиком: короткая версия, снимок с ETag, дельты и события на ваш адрес.
Ключ создаётся в панели за минуту, авторизация для чтения не нужна
Как это работает
Как встроить за один вечер
Создайте канал
Раздел «Публикация» → канал с типом «виджет»: он даёт публичный ключ и список разрешённых доменов.
Спросите версию
GET /version — хэш шахматки и счётчики по каждому ЖК. Дёшево настолько, что можно звать часто.
Заберите снимок
GET /apartments с профилем short или full. Ответ кэшируется и проверяется по ETag.
Подпишитесь на события
Вебхук с подписью HMAC приходит при изменении цен, статусов и состава квартир.
Преимущества
Что сделано ради вашего трафика
Версия вместо каталога
Проверка изменений — несколько сотен байт. Не нужно качать тысячу квартир, чтобы понять, что не поменялось ничего.
ETag и 304
Снимок неизменяемый: ревизия в имени, кэш на стороне клиента и CDN. Повторный запрос стоит вам одного заголовка.
Дельты по ревизии
?since=1234567:11 вернёт только изменившиеся и удалённые квартиры. Журнал изменений ведут триггеры базы, а не приложение.
Вебхуки с подписью
HMAC-SHA256 по строке «метка времени.тело», повторы 1/5/30/120/360 минут, автоотключение после 20 неудач подряд.
CORS без фокусов
Публичные ручки отвечают Allow-Origin: * и отдают ETag наружу, поэтому запрос можно делать прямо из браузера.
Контракт версии 1
Поля публичного ответа отделены от внутренних: переименование колонки в панели не ломает ваш код.
Чем это отличается от выгрузки XML
XML-фид — формат для площадок: он собирается по расписанию, содержит объявления целиком и не умеет отвечать на вопрос «что изменилось с прошлого раза». Для сайта это неудобно: чтобы показать актуальные цены, приходится либо скачивать фид целиком, либо мириться с задержкой.
Публичное API устроено под инкрементальное обновление. Версия шахматки меняется, только когда действительно поменялись данные ЖК: за этим следят триггеры в базе, а не ручные вызовы из кода. Поэтому клиент может спрашивать версию хоть каждую минуту и почти всегда получать «ничего не изменилось» за сотни байт.
Каналами можно управлять не только руками: те же настройки доступны по API и через MCP — нейросеть создаёт канал, меняет оформление и показывает предпросмотр. Публикация при этом остаётся отдельным разрешением, которое выдаётся ключу осознанно.
Что отдаёт API
- Версию шахматки и счётчики по статусам
- Снимок квартир: профиль short или full
- Дельты изменений от известной ревизии
- Карточку ЖК: адрес, класс, сроки, инфраструктуру
- Планировки, фото и виды из окна
- Скидки и акции по квартирам
- Приём заявок с вашей формы в CRM
- События на ваш адрес: цены, статусы, заявки
Примеры
Три запроса, которые всё решают
Сначала спрашиваем версию — это несколько сотен байт. Если хэш не изменился, дальше идти некуда:
curl https://domxml.ru/api/public/v1/$KEY/version
# {"contract":"1","version":"0da94d56a6ca","complexes":[
# {"complexId":5627431,"rev":12,"apartments":{"total":50,"available":37}}]}Изменилось — забираем снимок. Он отдаётся с ETag, поэтому повторный запрос с тем же заголовком вернёт 304 и пустое тело:
curl -H 'If-None-Match: "0da94d56a6ca"' \
"https://domxml.ru/api/public/v1/$KEY/apartments?profile=short"Если у вас уже есть прошлый снимок, весь каталог качать незачем — спрашиваем дельту от известной ревизии:
curl "https://domxml.ru/api/public/v1/$KEY/changes?since=5627431:11"
# {"updated":[{"id":...,"price":8990000,"status":"reserved"}],"removed":[]}А чтобы не опрашивать вовсе — подпишитесь на события. Вебхук приходит с подписью, её проверяют так:
const signed = `${req.headers['x-domxml-timestamp']}.${rawBody}`;
const mine = crypto.createHmac('sha256', secret).update(signed).digest('hex');
if (mine !== req.headers['x-domxml-signature']) return res.sendStatus(401);FAQ
Частые вопросы
Как часто можно опрашивать API?
Ограничение — 240 запросов в минуту с одного адреса и 1200 на канал. Этого хватает с запасом: правильный цикл спрашивает версию раз в минуту и идёт за данными, только когда хэш изменился.
Зачем дельты, если есть снимок?
Снимок ЖК на тысячу квартир — это сотни килобайт, а типичное изменение за день — несколько лотов. Дельта возвращает только их, поэтому обновление стоит трафика меньше, чем одна фотография.
Как проверить подпись вебхука?
Считайте HMAC-SHA256 от строки «метка времени, точка, тело запроса» на своём секрете и сравните с заголовком X-DomXML-Signature. Секрет показывается один раз при создании подписки.
Нужен ли ключ и что он открывает?
Для чтения — только публичный ключ канала: он открывает ровно те ЖК, которые вы в этот канал добавили. Для управления каналами нужен API-ключ с отдельным разрешением «Управление витриной и виджетами».
Что будет, если я удалю канал?
Ключ перестанет отвечать: и вставка на сайте, и ваши запросы получат 404. По ключу нельзя отличить «канала не было» от «канал выключен» — это сделано специально.
Заберите данные к себе на сайт
Создайте канал, скопируйте ключ и сделайте первый запрос — API бесплатное
Начать бесплатно