D-Keys Intercom — интеграция для Home Assistant

Неофициальная интеграция для домофонной системы D-Keys / S-M-D.

Протокол восстановлен методом реверс-инжиниринга с помощью перехвата HTTPS-трафика через BurpSuite.
Версия оригинального приложения: 5.3.13. Открытой документации по API у производителя нет.

⚠️ Это неофициальная интеграция, созданная путём реверс-инжиниринга, и она всё ещё находится в разработке.
Производитель может в любой момент изменить или отключить используемые эндпоинты без предупреждения — тогда интеграция перестанет работать. Используйте её только со своим собственным аккаунтом и ключами, с учётом условий использования сервиса D-Keys/S-M-D. Ответственность за это лежит на пользователе.

Что умеет

• Авторизация по номеру телефона, как в приложении.
• Вместо SMS-кода сейчас используется дозвон на номер телефона: нужно ввести последние 6 цифр номера, с которого был звонок.
• Автоматическое обнаружение всех ключей (домофонов, шлагбаумов, калиток) на аккаунте.
• Сущность lock.* для каждого ключа, который поддерживает удалённое открытие (флаг mqtt в options_exist) — вызов lock.unlock открывает дверь.
• Сущность sensor.* для всех ключей, включая те, что открываются только звонком или по ссылке, чтобы они тоже были видны в Home Assistant, с атрибутами: адрес, номер помещения, доступные опции и т.д.
• Настраиваемый интервал опроса (по умолчанию 300 секунд, через Настроить → Параметры у интеграции).
• Повторная авторизация (reauth), если токен перестал приниматься сервером.

Установка

Вариант 1. Самостоятельно

1. Скопируйте папку custom_components/dkeys в <config>/custom_components/dkeys вашей установки Home Assistant.
2. Перезапустите Home Assistant.
3. Откройте Настройки → Устройства и службы → Добавить интеграцию.
4. Найдите D-Keys Intercom.
5. Введите номер телефона, привязанный к вашему аккаунту D-Keys, в формате 79XXXXXXXXX.
6. Дождитесь звонка и введите последние 6 цифр номера, с которого был совершён звонок.
7. Готово — появятся сущности lock.* для ключей с удалённым открытием и sensor.* для всех ключей.

Вариант 2. Через HACS

1. Откройте HACS → Integrations.
2. Добавьте пользовательский репозиторий ic23/dkeys.
3. После добавления установите интеграцию D-Keys Intercom через HACS.
4. Перезапустите Home Assistant.
5. Откройте Настройки → Устройства и службы → Добавить интеграцию.
6. Найдите D-Keys Intercom и выполните авторизацию:
   • номер телефона в формате 79XXXXXXXXX
   • последние 6 цифр номера, с которого был звонок
7. После успешной авторизации сущности появятся автоматически.

Как устроен протокол

Основной сервер: https://mde.s-m-d.ru:38257/DKeys_app_3/MAIN.php/

Метод запросов: POST
Тип данных: application/x-www-form-urlencoded

В каждом запросе используется общий набор полей: action, os, lang, version, token, mobile, versionOS

Авторизация

1. action=regPhone (с пустым token) — сервер инициирует подтверждение номера.
2. Вместо SMS теперь выполняется звонок на номер телефона, а для подтверждения нужно ввести последние 6 цифр номера, с которого пришёл звонок.
3. action=sendPin&otp=XXXXXX — возвращает постоянный token в DATA.Token.

Список ключей

• action=getKey — возвращает массив ключей с полями:
  • codeKey
  • Nickname
  • Address
  • Icon
  • Color
  • codeMP
  • isMasterKey
  • TypeKey
  • options_exist (например: ["mqtt","openLink","openCall","qr", ...])
  • crc

Открытие двери

Открытие доступно только если в options_exist есть "mqtt":

1. action=getDataOption&option=mqtt&codeKey=<codeKey>
   → DATA.mqtt = {"topicCommand": "smd/<uid>", "openCommand": "cmd1"}

2. POST <cmdc-сервер>/itWork
   JSON с полями авторизации. Проверка связи, как правило, необязательна, но приложение выполняет её перед открытием.

3. POST <cmdc-сервер>/openDoor
   JSON вида:

   {"action":"openDoor","topic":"smd/<uid>","command":"cmd1","uid":"<uid>", ...}

Адрес cmdc-сервера интеграция получает динамически через action=getServers. Там же возвращаются адреса других внутренних сервисов — видео, изображения иконок и т.д. — они в интеграции не используются.

Все JSON-ответы, даже с Content-Type: text/html, имеют вид:

{"error": false, "critical": "10", "message": "", "warning": "", "DATA": {...}}

Логирование

Интеграция логирует свою работу в стандартный лог Home Assistant через логгер custom_components.dkeys:

• INFO — значимые события: успешная авторизация/переавторизация, запуск/выгрузка интеграции, обнаружение нового ключа или пропажа старого, добавление новых сущностей lock/sensor, открытие двери (запрос и результат).
• WARNING — восстановимые ошибки: API вернул error:true, сбой опроса (UpdateFailed), неверный код подтверждения.
• ERROR — сетевые/таймаут-ошибки, ошибка авторизации, неудачная попытка открыть дверь.
• DEBUG — подробности каждого запроса и ответа к серверу D-Keys, с редактированием токена и номера телефона, а также пошаговый лог последовательности открытия двери (getDataOption → itWork → openDoor).

Чтобы включить подробные DEBUG-логи, добавьте в configuration.yaml:

logger:
  default: warning
  logs:
    custom_components.dkeys: debug

О приватности логов: во всех запросах и ответах к API токен сессии и номер телефона автоматически маскируются перед записью в лог (например, c123*****************12f), так что DEBUG-логи можно прикладывать к багрепорту без риска слить токен доступа. При этом сами ответы сервера могут содержать другие данные вашего аккаунта — адрес, номер квартиры, никнейм ключа и т.п. — они не маскируются, поэтому перед публичной отправкой лога стоит один раз просмотреть его глазами.

Ограничения и нюансы

• Состояние lock — оптимистичное: у домофона нет обратной связи о реальном состоянии замка, поэтому сущность считается «заперта» в покое и на несколько секунд переходит в «отперта» сразу после успешной команды открытия, затем сама возвращается в «заперта».
• Ключи без поддержки удалённого открытия (mqtt отсутствует в options_exist) не получают lock-сущность — только sensor для видимости.
• Определение «токен истёк» сделано эвристически, по тексту ошибки от сервера, содержащему «пин» или «токен» — при появлении новых кодов ошибок логику стоит уточнить в api.py.
• Не используйте слишком короткий интервал опроса — это чужой бэкенд, и слишком частые запросы могут привести к ограничениям с их стороны.