Мosковская МДЦ 2.0: для разработчиков

Практическое руководство по подключению к платформе Мosковская МДЦ 2.0 для автоматизации сервисов и интеграции через API. Примерное время выполнения—от 60 до 180 минут в зависимости от глубины интеграции.

Что вы изучите

• Как получить доступ к МДЦ 2.0 и пройти регистрацию разработчика с подписями и загрузкой документов (2025–2026 процесс).
• Как аутентифицировать приложение через OAuth2 и получать токен для API v2.0 (релиз 2025-11-01).
• Примеры вызовов API: получение метаданных, создание интеграционных задач, загрузка файлов.
• Запуск локального агента в Docker (образ mdc-agent:2.0, размер ~48 МБ) и настройка webhook.
• Типичные ошибки, их диагностика и исправления, требования к ресурсам и ограничения по rate-limit.

Требования

• ОС: Ubuntu 22.04 LTS или Debian 12 (рекомендовано) или macOS 13+ для разработки локально.
• Docker 24.0 (релиз 2025) и Docker Compose 2.15, свободный диск 1 ГБ, RAM минимум 1 ГБ для агента; рекомендуется 2 ГБ для тестовых сборок.
• curl 8.2 (2025), jq 1.7 для парсинга JSON, openssl 3.1 для проверки сертификатов.
• CPU: минимум 1 vCPU для CI-агента; в продакшен-интеграции 2 vCPU и 4 ГБ RAM рекомендуются.
• Порты: HTTP API 443 (TLS), локальный агент использует порт 8088 по умолчанию.

Что это и кому надо

Московская МДЦ 2.0 — платформа для интеграции муниципальных цифровых сервисов и обмена данными между государственными и частными системами через стандартизированный API v2.0 (релиз 2025-11-01). Разработчикам полезно, если нужно автоматизировать подачу документов, получать события от муниципальных систем или реализовать сервисы с подтверждением электронной подписи и документооборотом.

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

Регистрация

Регистрация состоит из три этапов: создание учётной записи, регистрация приложения и подтверждение полномочий организации. Для разработки используйте sandbox-аккаунт (sandbox.md.mdc.gov.ru) с ограниченными квотами: 1000 запросов/сутки, payload до 5 МБ.

После заполнения формы вы получите Client ID и Client Secret для OAuth2. Для организаций требуется загрузить сканы устава и доверенности с электронной подписью. При загрузке документов система проверяет формат и контрольную сумму SHA256.

Шаг 1: подписание документов

Команда: подпишите PDF-файлы и загрузите их через API. Предположим, у вас есть файл power_of_attorney.pdf и сертификат в формате PKCS#12 signer.p12 с паролем.

# Генерация подписи PKCS7 (CMS) и создание payload
openssl pkcs12 -in signer.p12 -nodes -passin pass:секрет -out signer.pem  # 2-3s
openssl cms -sign -in power_of_attorney.pdf -signer signer.pem -outform DER -nodetach -out signed.bin  # 200-800ms
curl -X POST "https://sandbox.md.mdc.gov.ru/api/v2/documents" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @signed.bin

Пояснение: первая команда извлекает сертификат; вторая создаёт detached CMS-подпись в формате DER. Время выполнения зависит от размера PDF: для 0.5–2 МБ обычно 0.2–0.8 секунды. Образ подписывающего агента локально — ~48 МБ.

Ожидаемый вывод:

{
  "id": "doc_6f4a2b",
  "status": "verified",
  "sha256": "a3b1...",
  "uploaded_at": "2026-03-12T10:23:45Z"
}

Типичная ошибка и фикс:

# Ошибка: 400 Bad Request, неверный формат подписи
{
  "error": "invalid_signature_format",
  "message": "signature must be CMS/PKCS7 detached"
}
# Фикс:
# 1) Проверьте, что вы используете опцию -nodetach если API ожидает встроенную подпись, или уберите её если требуется detached.
# 2) Убедитесь, что сертификат действителен (openssl verify) и не просрочен.

Шаг 2: API

Команда: запрос токена OAuth2 клиентом (grant_type=client_credentials). Используйте endpoint авторизации https://auth.md.mdc.gov.ru/oauth2/token. Время ответа 150–400 ms при нормальной нагрузке.

# Получение access token (пример curl)
curl -X POST "https://auth.md.mdc.gov.ru/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=mdc.api"

Ожидаемый вывод:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "mdc.api"
}

Пояснение: токен — JWT, подписанный RSA-2048, срок жизни по умолчанию 3600 секунд. В response есть expires_in, переставайте полагаться на wall clock и обновляйте за 60 секунд до истечения.

Типичная ошибка и фикс:

# Ошибка: 401 Unauthorized
{ "error": "invalid_client", "error_description": "Client authentication failed" }
# Фикс:
# 1) Проверьте правильность client_id/client_secret и кодировку (URL-encoding).
# 2) Убедитесь, что аккаунт активирован через портал и у клиента есть scope mdc.api.
# 3) При использовании CI: секреты могут быть обрезаны окружением; проверьте длину строки секрета в переменной окружения.

Дальше — пример запроса к методу получения статусов заявления (API v2.0):

# Получение статусов
curl -X GET "https://api.md.mdc.gov.ru/v2/applications/12345/status" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json"

Ожидаемый вывод:

{
  "application_id": "12345",
  "status": "processed",
  "history": [
    {"ts":"2026-02-01T09:12:34Z","status":"submitted\