mxDadata

mxDadata — дополнение для интеграции DaData с MiniShop3 на MODX Revolution 3: подсказки адреса и организаций на чекауте, нормализация и проверка данных через Clean и Party API, кэш и журнал запросов в панели управления.

Минимальный путь к подсказкам на витрине

1. Установить пакет и убедиться, что стоит MiniShop3.
2. В профиле DaData взять Token (и Secret для валидации заказа).
3. Extras → mxDadata → API — вставить ключи, Сохранить, при необходимости Тест соединения.
4. В чанк формы заказа (например tpl.msOrder) некэшированно вывести [[!mxDadataAddressSuggest]] с верным input под поле адреса.
5. Настройки → Очистить кэш и открыть страницу оформления с товаром в корзине.

Детали: Быстрый старт, поля формы: Подключение на сайте.

Безопасность ключей

• Token DaData используется для Suggest и запросов с витрины через connector-web.php (запросы ограничены по действиям и rate limit). В HTML/шаблон не подставляйте Secret вручную.
• Secret храните только в системных настройках MODX: он нужен для Clean и Party на сервере (плагин заказа, менеджер).
• Сетевой доступ к DaData с сервера — по HTTPS. Ключи в БД MODX защищайте политиками доступа к настройкам.

Тарифы, баланс и лимиты DaData

• Условия и стоимость — в кабинете DaData. Баланс и статистика запросов удобно смотреть в Extras → mxDadata → Dashboard (как и Логи).
• Сайт расходует квоту на каждую подсказку и валидацию. RateLimiter в компоненте (mxdadata_throttle_rpm) снижает риск всплесков и 429. При исчерпанном балансе ответы API дают отказ — см. FAQ → 429 и Логи.

Возможности

• Suggest на витрине — сниппеты mxDadataAddressSuggest, mxDadataPartySuggest, универсальная форма mxDadataForm (JSON-конфиг полей) через публичный коннектор assets/components/mxdadata/connector-web.php
• Плагин MiniShop3 — на msOnBeforeCreateOrder и msOnSubmitOrder: валидация телефона и email (Clean), нормализация адреса, обязательный FIAS/индекс, блокировка заказа при ошибках. Дополнительно OnWebPageInit подставляет плейсхолдеры веб-контекста в шаблоны
• Админ-панель (Vue) — Extras → mxDadata: дашборд (статус API, баланс), настройки API, вкладка MiniShop3, кэш, логи, тест Party по ИНН (нужен VueTools)
• Кэш — таблица mxdadata_cache, настраиваемый TTL, очистка из админки
• Логи — таблица mxdadata_log, фильтры, просмотр request/response, ротация по расписанию (опционально пакет Scheduler)

Системные требования

Требование	Версия
MODX Revolution	3.x
PHP	8.2+
MiniShop3	3.x
MySQL / MariaDB	как в требованиях MODX 3

Зависимости

• MiniShop3 — адрес заказа, события оформления
• VueTools — раздел Extras → mxDadata в менеджере. Для подсказок на странице заказа VueTools не обязателен: достаточно токена DaData в системных настройках и сниппетов в чанке

Опционально

• Scheduler — фоновая ротация логов по расписанию (см. установку пакета)

Установка

1. Установите пакет через Extras → Installer (транспорт с ModStore или локальная сборка php _build/build.php из исходников)
2. Убедитесь, что установлены MiniShop3 и при необходимости VueTools
3. Зарегистрируйтесь на dadata.ru, в профиле скопируйте API Token и Secret
4. Extras → mxDadata (вкладка API) — вставьте ключи, Тест соединения, Сохранить
5. Настройки → Очистить кэш

С чего начать: Быстрый старт.

Термины

Термин	Описание
Token / Secret	Ключи DaData: Token — в основном Suggest, Secret — Clean и Party
connector-web.php	Публичный коннектор для AJAX-подсказок с витрины (ограничение частоты, кэш)
connector.php	Коннектор для менеджерских процессоров (MODX)
Party	API организаций по ИНН (реквизиты, адрес)

Документация по разделам

• Быстрый старт — ключи, плагин, сниппеты в чанке заказа
• Админка в MODX — вкладки, дашборд, логи, Party
• Системные настройки — API, кэш, throttling, MiniShop3
• Сниппеты — адрес, ИНН, универсальная форма
• Подключение на сайте — порядок вывода с msRussianPost, событие mxdadata:order-address-updated
• Интеграция и сценарии — события плагина, валидация, кэш, схемы потоков
• Для разработчиков — плейсхолдеры, API DaData
• FAQ — частые проблемы, 429

Расширенные JSON-примеры для mxDadataForm — Интеграция и сниппет. Руководство по админке — Админка в MODX.