В Mikro V17 закрыт прямой доступ к базе данных: как перевести интеграцию на API (2026)

Кратко: В архитектуре Mikro V17 интеграцию теперь нужно строить на официальном Mikro Desktop API, а не на прямом доступе через SQL. Формулировка, которую можно услышать от интеграторов, — «в V17 закрыли прямой доступ к базе данных, система полностью перешла на API» — хорошо передаёт общую суть, но не совсем точна: официальная документация Mikro прямо указывает, что к полям таблиц, которых нет в JSON API, по-прежнему можно обращаться напрямую по их именам в БД. Поэтому правильно понимать это так: с выходом V17 официальный API стал основным и поддерживаемым каналом интеграции, а для полей, которые API не отдаёт, сохраняется документированное исключение — «доступ по имени в БД». Что делать сейчас? Три шага: (1) проведите инвентаризацию всех текущих точек чтения и записи через SQL, столбец за столбцом, (2) для каждого поля определите, есть ли эндпоинт API или нужен запасной вариант с именем в БД, (3) подайте заявку на API Key через официальный портал для разработчиков, протестируйте новый поток в параллельном режиме, а затем выполните переключение. В этом руководстве мы шаг за шагом разбираем такую миграцию, не выдумывая определённости там, где её нет, и опираясь на официальную документацию Mikro.

Как B2B- и white-label-компания по разработке программного обеспечения из провинции Sakarya (Сакарья), мы ведём такую миграцию для зависимых от Mikro интеграций в электронной коммерции, заказном ПО и бухгалтерии. Ниже мы делимся и логикой этого решения, и конкретным планом действий, который применяем на практике. Все утверждения о датах и портах, выглядящие «точными», мы оставили только там, где смогли опереться на официальный источник, а места, где речь идёт о трактовке интеграторов, явно отметили.

Что именно изменилось?

Компания Mikro опубликовала официальный портал для разработчиков своих десктопных продуктов: apidocs.mikro.com.tr. Слоган портала — «Разрабатывайте, тестируйте, запускайте — руководство по интеграции с Mikro API», а свою аудиторию он определяет прямо: клиенты Mikro Yazılım, партнёры Mikro Yazılım и сторонние разработчики решений. Иными словами, этот API предназначен не только для реселлеров: это официальный канал и для собственных команд клиентов, и для независимых компаний-разработчиков ПО.

Технический характер API тоже понятен: REST/JSON поверх HTTP. На официальном портале есть руководства «Основы JSON и REST API», «Протокол HTTP и коды состояния» и «Использование эндпоинтов», а также доступные для скачивания официальные коллекции Postman для V17 и V16 («Актуальная коллекция Postman (V17)» и «(V16)»). Эти коллекции — официальная отправная точка для этапа тестирования.

Важный нюанс: утверждать, что «V17 убрала весь прямой доступ к базе данных», неверно. Согласно официальному FAQ, «поля таблиц, которых нет в JSON API, также можно использовать напрямую по их именам в БД». Верная формулировка такая: официальный API теперь — обязательный и поддерживаемый основной канал, а обращение по имени в БД — документированное исключение для полей, которые API не отдаёт.

Почему прямой доступ к БД отошёл на второй план? (логика решения)

Блоги интеграторов (например, ozgurguler.net, mikrodestek.net) резюмируют это изменение так: «начиная с V17 компания Mikro закрыла прямой доступ к базе данных и полностью перешла на систему на базе API». Передавать это следует не как официальную формулировку Mikro, а как трактовку интеграторов: именно такой фразы в собственных источниках Mikro мы не нашли, а упомянутое выше исключение с именами в БД смягчает это категоричное утверждение. И всё же техническая логика, по которой разработчик ERP вводит контролируемый слой API вместо прямого SQL, очевидна:

• Стабильность и независимость от схемы: Прямой SQL жёстко привязан к структуре таблиц и столбцов. Когда вендор меняет схему в новой версии, ваши запросы незаметно ломаются. Слой API ставит контракт между внутренней схемой и внешним потребителем: даже если внутренняя структура изменится, контракт эндпоинта можно сохранить.
• Безопасность и поверхность прав доступа: Передать приложению прямые учётные данные базы данных (строку подключения, connection string) — значит открыть максимально широкую поверхность прав. При доступе через API аутентификация делегируется собственному механизму сессий и авторизации Mikro, а доступ можно ограничить на уровне эндпоинтов.
• Поддержка и предсказуемость: При прямом SQL вендор не может знать, что именно вы читаете или записываете, а поскольку бизнес-правила можно обойти, возникает риск для целостности данных. Операции через API определены, версионируются и покрываются поддержкой. Mikro действительно публикует датированный журнал изменений API V17: самая старая запись, которую мы смогли увидеть, — [17.03a] – 14.04.2025, самая новая — [17.07b] – 05.08.2026. Это доказывает, что API активно версионируется и развивается.

Кого это затрагивает?

Эта миграция затрагивает каждую интеграцию, которая подключается к базе данных Mikro напрямую. Три группы, с которыми мы чаще всего сталкиваемся на практике:

• Интеграции электронной коммерции: Магазины, которые синхронизируют остатки, цены, данные контрагентов и заказы между сайтом или маркетплейсом и Mikro через SQL. Самые критичные риски здесь связаны с операциями записи: списанием остатков, созданием счетов и накладных, передачей заказов.
• Заказное ПО и внутренние проекты: Внутренние разработки, для которых Mikro — единый источник достоверных данных: учёт производства, приложения для выездных команд, дилерские B2B-порталы. Для этой группы лицензирование API Key выполняется вручную (см. ниже).
• Интеграции бухгалтерии и отчётности: Сверка взаиморасчётов с контрагентами, шлюзы к e-Fatura (турецкая система электронных счетов-фактур) и e-Arşiv (турецкий электронный архив счетов), BI- и отчётные дашборды, регулярные выгрузки. Большинство из них работает «только на чтение», но именно эта группа глубже всех завязана на прямые запросы к таблицам.

Чем закрыть потоки электронной коммерции и e-Fatura на стороне Mikro — готовым модулем или API-интеграцией на заказ — отдельный вопрос; мы разобрали его в другой статье: Интеграция электронной коммерции, ERP и e-Fatura: готовое решение или API на заказ?

План миграции: от чтения через SQL к эндпоинтам API

Шаги ниже — это редакционная рекомендация, которую мы строим на задокументированных Mikro фактах: такие пункты, как параллельная работа и откат, — не процедура, предписанная Mikro, а стандартная передовая практика интеграции.

1) Инвентаризация полей: сопоставьте каждый столбец SQL

Первый и чаще всего пропускаемый шаг: выпишите все таблицы и все столбцы, с которыми работает ваша текущая интеграция. Затем для каждого поля выберите один из двух путей:

• Если поле есть в JSON API → считывайте его из ответа соответствующего REST-эндпоинта.
• Если поля нет в JSON API → как указано в официальном FAQ, к нему можно обращаться напрямую по имени в БД. Это важный запасной выход, который снимает давление в духе «всё нужно перевести на API за один раз».
• Если его нет ни в эндпоинте, ни среди доступных полей → подайте запрос на новую таблицу или эндпоинт через форму заявки на Program API (Mikro пишет: «Для запросов на новые таблицы: форма заявки на API»).

Миграции без такой инвентаризации заканчиваются ошибками «отсутствует поле» уже в рабочей среде. Сопоставление столбец за столбцом — самый утомительный, но и самый решающий шаг миграции.

2) Аутентификация и заявка

Сначала доступ: интеграторы заполняют форму заявки на Program API. Согласно официальному руководству, пользователям вертикальных решений API Key назначается автоматически, а для собственного ПО компании лицензия выдаётся вручную. (Описанные в некоторых блогах интеграторов этапы — «подробная оценка с вопросами и ответами по электронной почте и передача в отдел паролей» — в официальных материалах так не задокументированы: официальный источник содержит только форму, разграничение лицензирования и контактные адреса.)

Модель аутентификации — не OAuth, скажем об этом прямо. В её основе — API Key + сессия/вход (login). Согласно официальному руководству, в каждом запросе используются следующие данные:

В управлении сессиями есть различие между версиями. Методы V1 сначала открывают сессию через APILogin (адрес на официальной странице установки: POST http://localhost:8094/Api/APIMethods/APILogin, в теле запроса — FirmaKodu, CalismaYili, ApiKey, KullaniciKodu, Sifre). Методы V2/V3, напротив, передают данные пользователя прямо в JSON каждого эндпоинта и автоматически завершают сессию после выполнения операции. Учтите это различие с самого начала, когда проектируете архитектуру (постоянная сессия или сессия по запросу).

3) Установка и настройка портов

API устанавливается через опцию «Server» на странице обновлений версий и регистрирует службу Windows с именем Mikro Desktop API. Служба работает под учётной записью NT SERVICE\MikroDesktopAPIContainer, а параметры порта хранятся в разделе HKLM\SYSTEM\CurrentControlSet\Services\MikroDesktopAPIContainer\Parameters. Чтобы изменить порт, остановите службу, отредактируйте значение в regedit (Decimal Base), а затем откройте порт в брандмауэре Windows.

Порты службы по умолчанию зависят от версии: 8094 для V17 и 8084 для V16. Это значения по умолчанию, их можно изменить через реестр, поэтому вместо «Mikro сменила порт с 8084 на 8094» правильнее говорить: «по умолчанию в V16 используется порт 8084, а в V17 — 8094». Если вы изменили этот порт в своей среде, настройте адреса вызовов соответственно.

4) Тестирование: официальная коллекция Postman

Прежде чем писать код, проверьте вызовы вручную. Скачайте официальный пакет Mikro Postman Collection (V17) и выполните отмеченные в инвентаризации эндпоинты со своими учётными данными. Сравните ожидаемые ответы с текущими результатами SQL и не запускайте решение в эксплуатацию, пока не добьётесь совпадения по каждому полю. На этом этапе официальный канал технической поддержки — [email protected], а для вопросов по API Key и партнёрской части — [email protected].

5) Параллельная работа и откат

Шаг, который сводит риск к минимуму: запустите новый поток на базе API рядом со старым потоком SQL. В течение определённого периода оба пути должны выдавать одни и те же данные (при чтении и записи), а результаты следует сравнивать автоматически (сверка). Если расхождений нет, уверенность растёт. На это время держите наготове план отката: с помощью feature flag вы должны иметь возможность вернуться к старому потоку одним кликом. Такой подход с параллельной работой и откатом — не указание Mikro, а стандартная страховка интеграции, которую рекомендуем мы.

6) Переключение и выбор версии

Когда сравнение не показывает расхождений, выполните переключение: направьте трафик записи в API, переведите путь SQL в режим наблюдения только для чтения, а затем полностью отключите его. Зафиксируйте API на известной версии и заново запускайте регрессионный набор Postman при каждом обновлении Mikro Desktop API: активный журнал изменений показывает, что незаметные изменения возможны.

Одна оговорка: утверждение, что для использования API системе Mikro ERP требуется «V17 или выше», мы не нашли дословно на главной странице и в руководствах официального портала apidocs: оно встречается на странице стороннего интегратора (Ovo Yazılım). Мы не приводим это требование к версии как официальное и рекомендуем проверить его в вашей собственной установке через браузер.

Сроки: какие даты называют для V16?

Для команд, которые хотят привязать миграцию к календарю, в обороте есть две часто упоминаемые даты. Мы не смогли подтвердить их первичным источником Mikro: официальные страницы объявлений были закрыты для автоматизированного доступа. Приведённые ниже даты опираются на блог интегратора, цитирующий объявление Mikro (ozgurguler.net), и на записи жалоб потребителей — то есть перед публикацией их необходимо проверить в браузере на официальной странице объявлений Mikro:

• 15 октября 2025 года — крайняя дата продления (операций продления): Согласно приведённой формулировке, после этой даты все продления будут выполняться только на V17. Это не полное окончание поддержки, а лишь крайний срок продления.
• 15 октября 2026 года — полное окончание поддержки: Согласно объявлению, которое, как указывается, датировано 29 сентября 2025 года, в этот день для V16 полностью прекратятся обновления версий и обновления под изменения законодательства, новые разработки, поддержка клиентов и лицензирование дополнительных пользователей, модулей и вертикальных решений. Это отдельная веха, которая наступает через год после крайней даты продления; не путайте эти две даты.

Практический вывод: какая бы дата ни оказалась окончательной, самый безопасный путь — оформить перевод интеграции на API как проект и завершить его задолго до крайнего срока. Миграции, отложенные на последний день, лишают вас и окна для тестирования, и роскоши отката.

Типичные ошибки

• Пропуск инвентаризации: Расчёт на то, что «API и так всё отдаст». Некоторые поля доступны только по имени в БД, для других приходится подавать запрос на новую таблицу. Неполная инвентаризация = сюрпризы в рабочей среде.
• Аутентификацию принимают за OAuth: Модель — API Key + вход/сессия, а пароль формируется как Дата + Пароль → MD5-хеш. Клиенты, написанные с расчётом на Bearer-токен, упираются в ошибку «Geçersiz api key» и ошибки сессии.
• Предположения о порте: Те, кто переходит с V16, ожидают 8084, но в V17 по умолчанию используется 8094, и это значение могло быть изменено через реестр. Не прописывайте порт жёстко в коде, а делайте его настраиваемым.
• Версия не зафиксирована: API активно развивается. Без фиксации версии каждое обновление несёт риск незаметной регрессии.
• Сторонние инструменты принимают за официальные: Некоторые вспомогательные утилиты для тестирования и установки, которые распространяются в сообществе (например, инструмент, который один блогер называет «бесплатным тестовым приложением, которое я разработал»), не относятся к официальным продуктам Mikro. Официальный тестовый артефакт — коллекция Postman, которую публикует Mikro.
• Переключение без параллельного периода: При прямом переключении без сверки и отката несоответствия в данных выявляются только по жалобам клиентов.

Как Partnerfy может помочь

Как компания по разработке ПО из провинции Sakarya, мы ведём такие ERP-миграции не как «обещание», а как воспроизводимый процесс: сначала инвентаризация существующих зависимостей от SQL на уровне полей, затем создание слоя API-интеграции (заявка, аутентификация, сопоставление эндпоинтов), после этого тестирование с официальной коллекцией Postman, параллельная работа со сверкой и контролируемое переключение. Если ваши связанные с Mikro потоки CRM/ERP относятся к электронной коммерции или веб-приложениям на заказ, мы проектируем и сопровождаем этот слой с единой зоной ответственности.

Честное замечание: ни один интегратор не может гарантировать, что система на API вендора устоит перед любым будущим изменением версии. Поэтому мы строим устойчивую к изменениям архитектуру с зафиксированной версией и наблюдаемостью. Подходят ли вам инвестиции в ERP/CRM, созданную под вашу компанию, можно оценить и с другой стороны: Подходит ли вашей компании индивидуальная ERP/CRM?

Заключение

С выходом V17 официальный Mikro Desktop API стал основным и поддерживаемым каналом для интеграций, а архитектуры, завязанные на прямой SQL, теперь хрупки и остаются без поддержки. Но говорить, что «закрыт весь доступ к БД», было бы неверно: для полей, которые API не отдаёт, остаётся документированное исключение с именем в БД. Правильный подход — провести инвентаризацию на уровне полей, подать заявку на официальный API и протестировать его в Postman, а затем поработать в параллельном режиме и выполнить контролируемое переключение со страховкой в виде отката. Сверьте циркулирующие даты 15 октября 2025 и 2026 годов с официальным объявлением Mikro и не откладывайте миграцию до крайнего срока. Если вы хотите спланировать эту миграцию или передать её нам, свяжитесь с нами: мы выявим ваши зависимости от SQL и предложим план их переноса на API на заказ.

Источники

• Mikro Desktop API — официальный портал для разработчиков (слоган, аудитория, коллекции Postman, адреса поддержки)
• Mikro — установка и настройка портов (служба Windows, NT SERVICE\MikroDesktopAPIContainer, APILogin, порт V17 по умолчанию 8094, regedit)
• Mikro — руководства по API и FAQ (поля аутентификации и MD5, запасной вариант с именем в БД, порты 8094/8084, форма заявки и лицензирование)
• Mikro — журнал изменений API V17 (релизы от 14.04.2025 до 05.08.2026)
• Mikro — форма заявки на Program API (канал для получения API Key и запросов на эндпоинты и таблицы)
• Ovo Yazılım (сторонний интегратор) — требование «V17 или выше» и примечание о порте
• Özgür Güler (интегратор) — крайняя дата продления 15 октября 2025 года и трактовка «на базе API» (цитата из объявления Mikro)
• Özgür Güler (интегратор) — полное окончание поддержки 15 октября 2026 года (цитата из объявления от 29 сентября 2025 года)
• Mikro — официальные объявления (первичный источник для проверки дат в браузере)

Часто задаваемые вопросы