Инструкция
АПИ
Тарифы
С чего начать
Роуминг
Вопросы и ответы
Контакты
Начать изучение

Руководство по интеграции сервиса ЭПД с 1С

Техническая инструкция для сопровождения интеграции ЭДО/ЭПД. Комплекты 1С 8.2 и 1С 8.3. версия native-компоненты от 1.0.0598

Назначение документа — дать программисту карту архитектуры, точек вызова, методов Native-компоненты, маршрутов API, правил подписания, хранения идентификаторов и диагностики. Описание основано на боевых исходниках обоих комплектов и строках поставляемой компоненты.

Важно. Перед изменением интеграции разделяйте четыре контракта: имена метаданных 1С, имена процедур 1С, имена JSON-полей и строковые команды Native-компоненты. Последние два контракта чувствительны к регистру и не переводятся.

1.Общие принципы и архитектура

1.1. Слои решения
Интеграция состоит из пяти слоев. Каждый слой решает отдельную задачу и не должен подменять соседний:
● Обычная форма «ФормаОбмен» — пользовательские команды, выбор организации, периода, документов и сертификата.
● Модуль объекта внешней обработки — сбор структур JSON, вызов компоненты, обработка ответов, старый контур ЭДО.
● ОбщийМодульМИГ24 — серверные вызовы, прямые GET-запросы ЭПД, генерация XML Т1, чтение и запись регистров.
● Native-компонента КомпонентМИГ24.bin — HTTP-взаимодействие, доступ к сертификатам ОС, криптографическая подпись и составные сценарии API.
● API МИГ24 — два логических контура: /api/v1 для ЭДО и /epd/v1 для ЭПД.
Форма 1С
  → функция модуля обработки или общего модуля
    → JSON { settings, data }
      → Mig24AddinExtension.ВызовМетодаJSON(Команда, JSON)
        → локальная криптография и/или HTTP API МИГ24
      ← JSON { response, data }
    ← Структура 1С
  ← сообщение пользователю и запись регистров
1.3. Состав Native-компоненты
КомпонентМИГ24.bin является ZIP-контейнером Native API 1С. В поставке находятся Mig24Addin_32.dll, Mig24Addin_64.dll, libMig24Addin.so и manifest.xml. Манифест объявляет Windows i386, Windows x86_64 и Linux x86_64. Это не COM-компонента: regsvr32 не используется.
● Класс: Mig24AddinExtension.
● Основной метод из 1С: ВызовМетодаJSON(ИмяКоманды, СтрокаJSON).
● В клиентском модуле подключение выполняется под именем МИГ24AddinClient; в общем модуле — МИГ24Addin.
● Для 1С 8.2 JSON сериализуется собственным совместимым кодом общего модуля; в 1С 8.3 применяются ЗаписьJSON и ЧтениеJSON.
⚠️ Платформенная совместимость и ограничения Linux: Реестры Windows (x86 и x64) содержат по 72 команды и полностью поддерживают локальную криптографию. Linux-библиотека (libMig24Addin.so) содержит 64 команды: в ней доступны все сетевые операции (чтение ЭЗЗ, экспедиций, событий, файлов), но отсутствуют локальные криптографические команды (epd-sign-entity, certificates-list, sign-hash-array и др.). Сценарий подписания новых документов на Linux требует согласованного альтернативного механизма или использования Windows-клиента..
1.4. Единый формат вызова
Практически все сетевые команды получают корневую структуру из двух разделов:
{
  "settings": {
    "host": "epd.mig24.online",
    "token": "<секретный API-токен>"
  },
  "data": {
    "...": "параметры конкретной команды"
  }
}
● settings.host — узел сервиса выбранной организации. Код умеет нормализовать схему для прямых GET ЭПД; компонента обычно получает адрес из регистра.
● settings.token — токен именно выбранной организации. Токен другой организации меняет роль и доступные данные.
● data — параметры команды. Для некоторых команд раздел отсутствует.
Типовой ответ компоненты:
{
  "response": {
    "valid": "1",
    "httpCode": "200",
    "hasData": "1",
    "error": ""
  },
  "data": { "...": "результат" }
}
Важно. В существующем контракте httpCode, valid и hasData часто представлены строками, а не числами/булевыми. Сравнение с "200" и "0" менять без проверки версии компоненты нельзя.
1.5. Почему в коде есть английские имена
В формах встречаются host, token, thumbprint, mchdInfoId, documentId, packageId, packageGroupId, transportationId, signingEntity, response, data, user_data, issuer, validTo и другие имена. Это не случайно вставленный иностранный код. Большая часть имен является контрактом API, ответа компоненты или существующих регистров 1С.
● Строки внутри Вставить("documentId", ...) формируют JSON. Перевод ключа изменит запрос и сломает API.
● Обращение Ответ.data.user_data читает точное поле ответа. Переименование приведет к отсутствию значения.
● Реквизиты регистра documentId/packageId уже являются именами метаданных. Их переименование требует миграции конфигурации и данных.
● Русифицировать безопасно локальные переменные, комментарии и пользовательские сообщения. В боевых формах добавлено пояснение контракта и убраны отладочные англоязычные сообщения; технические ключи сохранены.
1.6. Безопасность
● token является секретом. Не помещать его в Сообщить(), журнал регистрации, скриншоты и текст ошибок.
● Протоколировать имя команды, HTTP-код и обезличенный идентификатор; тело запроса — только после маскирования token.
● МИГ24_НастройкиОрганизаций и МИГ24_Пользователи закрыть правами от обычного просмотра.
● pincode не хранить и не передавать. При необходимости PIN запрашивает криптопровайдер в своем интерфейсе.
● Полный JSON МЧД может содержать персональные данные; доступ к МИГ24_МЧД_Кэш ограничить.

2. Методы Native-компоненты

2.1. Методы, которые вызывает текущая обработка
Таблица фиксирует фактические строки команд из исходников. Маршруты указаны по исходникам общего модуля и строкам бинарной компоненты.
Важно. Команды package-groups-list, package-info и package-actions присутствуют в обертках общего модуля, но отсутствуют в реестре строк JSON-команд поставляемого бинарника. Перед включением страницы входящих ЭДО их необходимо проверить с фактической версией компоненты или заменить поддерживаемыми командами. В текущем комплекте этот участок нельзя считать доказанным рабочим контрактом..
2.2. Полный реестр команд компоненты
В поставке версии 1.0.0598 содержится 72 команды для Windows (x86 и x64) и 64 команды для Linux. Статус «не вызывается» означает только отсутствие прямого вызова в текущих исходниках; команда может использоваться внутри составной команды компоненты.
2.3. Пример вызова компоненты
Клиентский вызов из модуля объекта обработки:
НастройкиВызова = Новый Структура("host,token", host, token);
ДанныеВызова = Новый Структура;
ДанныеВызова.Вставить("inn", Контрагент.ИНН);
ДанныеВызова.Вставить("kpp", Контрагент.КПП);
ПолезнаяНагрузка = Новый Структура;
ПолезнаяНагрузка.Вставить("settings", НастройкиВызова);
ПолезнаяНагрузка.Вставить("data", ДанныеВызова);
Ответ = ВызовМетодаJSON("abonents-by-requisites", ПолезнаяНагрузка);
Серверный вызов через общий модуль отличается только местом подключения макета:
Макет = ПолучитьОбщийМакет("КомпонентМИГ24");
Ответ = ОбщийМодульМИГ24.ВызовМетодаНаСервереJSON(
    Макет, "epd-create-transportation", ПолезнаяНагрузка);
2.4. Правила обработки ответа
● Сначала проверить наличие response и response.httpCode.
● Успех текущего контракта — строка response.httpCode = "200". Для прямого HTTP ЭПД используется числовой КодСостояния.
● response.hasData = "0" означает корректный ответ без массива данных, а не сетевую ошибку.
● Текст response.error показывать пользователю без settings.token и полного запроса.
● После исключения компоненты формировать унифицированный локальный ответ с httpCode = "500" и понятным источником ошибки.

3. Устройство обработок 1С

3.1. Основные модули
3.2. Хранение данных
Важно. В комплекте 8.2 измерение строки груза называется НомерСтрокиГруза. В текущем комплекте 8.3 используется НомерСтроки. Программист должен применять имя своей конфигурации и не смешивать тексты модулей между версиями.
3.3. Жизненный цикл идентификаторов
3.4. Сертификат и МЧД
Сертификат выбирается не из регистра 1С, а из локального хранилища сертификатов пользователя Windows. Регистр хранит только привязку результата к паре Организация + Пользователь.
Выбранная организация
  → чтение host/token
  → certificates-list-match
  → локальные сертификаты + /api/v1/organization-users
  → фильтрация просроченных
  → выбор thumbprint и необязательного mchdInfoId
  → запись МИГ24_Пользователи
Важно. Привязанный thumbprint не заменяет host/token. certificates-list-match сначала должен определить пользователей организации на сервере. Запрос с {"host":"","token":""} завершится до проверки сертификата. Формы должны перечитывать настройки непосредственно перед вызовом и не отправлять пустые settings.

4. Контур ЭДО

4.1. Назначение
Контур ЭДО обслуживает формализованные документы и пакетную модель /api/v1. В текущей обработке создаются УПД из реализации, счета на оплату и акты сверки. Документ сначала получает documentId, затем выгружается, включается в пакет/группу и подписывается.
4.2. Настройка организации и контрагентов
● В МИГ24_НастройкиОрганизаций создается одна запись на каждую организацию с host/token.
● Команда counteragents получает подключенных контрагентов сервера.
● Обработка сопоставляет их со справочником Контрагенты по ИНН/КПП и записывает МИГ24_НастройкиКонтрагентов.
● abonents-by-requisites применяется для поиска кодов абонентов по реквизитам.
● counteragent-requests создает приглашение; локальный статус меняется на ОжиданиеПрисоединения или Ошибка.
● Проведенная реализация подключенного контрагента автоматически попадает в 8.2-список, если Статус = Присоединен и ЭДО_Реализация = Истина. ЭДО_МИГ24 = Истина остается ручным разрешением.
4.3. Создание документа
До вызова создается и сохраняется documentId. Повторная операция обязана использовать тот же идентификатор, пока пользователь явно не выполнил сброс. JSON-поля документа имеют английские имена, поскольку повторяют DTO API.
4.4. Пакет и подпись
СоздатьПакет получает documentId, создает/читает packageId и packageGroupId, определяет получателя и вызывает create-package-group. ПодписатьПакет передает packageGroupId, thumbprint и при наличии mchdInfoId в sign-package-group.
Документ 1С
 → documentId
 → create-upd / create-payment-invoice / checking-payments-act
 → packageId + packageGroupId
 → create-package-group
 → sign-package-group
 → package-status-updated
 → запись МИГ24_Состояния
 → ack-single-event
4.5. События и статусы
● package-status-updated запрашивается с orderBy = ModificationDateTime и orderDir = ASC.
● Каждое событие записывается в периодический регистр МИГ24_Состояния.
● После успешной локальной записи eventId подтверждается через ack-single-event.
● При StatusId = 4 обработка устанавливает АктСдан у связанного документа 1С.
4.6. Входящие ЭДО
Общий модуль содержит обертки списка групп, карточки пакета и доступных действий. Они подготовлены под GET /api/v1/package-groups, /api/v1/packages/{id} и /actions. Однако строковые команды этих трех оберток не обнаружены в поставляемой компоненте. До подтверждения версии компоненты страницу входящих следует считать интеграционным заделом, а не гарантированно рабочим маршрутом.
4.7. Минимальная проверка ЭДО
● Выбрать организацию и убедиться, что host/token непустые.
● Получить контрагентов и проверить запись с корректным AbonentCode.
● Выгрузить один документ и убедиться, что documentId сохранен.
● Создать пакет и проверить МИГ24_Пакеты.
● Выбрать сертификат, подписать и получить серверное событие.
● Повторить обновление: уже подтвержденное eventId не должно обрабатываться как новое.

5. Контур ЭПД

5.1. Определение режима
Форма определяет контур по host. Известные узлы старого ЭДО test-edo.ntssoft.ru и edo.mig24.online относятся к ЭДО; остальные заполненные узлы рассматриваются как ЭПД. Заголовок формы меняется на «МИГ24 — ЭПД / ЭТрН» или «МИГ24 — ЭДО». Это эвристика: при появлении нового домена ЭДО список необходимо обновить.
5.2. Какие вызовы выполняются компонентой, а какие HTTPСоединением
5.3. Подготовка Т1
Основание Т1 — проведенная РеализацияТоваровУслуг. Форма «ДанныеТ1» объединяет данные документа и специализированных регистров.
● Код грузоотправителя получается по токену через /epd/v1/abonents/me.
● Код грузополучателя берется из маршрута/параметров Т1.
● Код перевозчика берется из МИГ24_Перевозчики и сохраняется в параметрах Т1.
● Маршрут определяется по Организация + Контрагент.
● Водитель и транспорт фильтруются по выбранному перевозчику.
● При смене перевозчика зависимые поля водителя и ТС очищаются.
● Грузы читаются из МИГ24_ГрузыЭТРН; при первом заполнении создаются из товаров реализации.
● УИД транспортной накладной создается и записывается при отсутствии.
Общий модуль формирует XML ФНС во временном файле в кодировке windows-1251. Имя файла включает коды участников и УИД. Временный файл должен удаляться после завершения сценария.
5.4. Создание, сохранение и защита от дублей
Реализация
 → чтение сохраненных параметров Т1
 → получение ролей/кодов
 → генерация XML
 → epd-create-transportation
 → transportationId + signingEntity
 → немедленная запись transportationId и signingEntity
 → epd-sign-entity
 → GET состояния перевозки
 → после успеха очистка signingEntity
Важно. transportationId и signingEntity должны сохраняться до подписи. Если криптопровайдер или сервер подписи вернул ошибку, повторный запуск подписывает сохраненный черновик и не создает новую перевозку.
Перед новым созданием обработка выполняет две проверки:
● если transportationId уже хранится — запрашивает его серверное состояние и продолжает допустимое действие;
● если локального идентификатора нет — ищет перевозку по номеру документа на сервере и при нахождении восстанавливает transportationId в 1С.
5.5. Подписание Т1
Ответ создания содержит signingEntity — серверное представление подписываемой сущности. Оно передается в epd-sign-entity вместе с типом сущности, thumbprint и необязательным mchdInfoId. Компонента получает данные для подписи, обращается к закрытому ключу через криптопровайдер и завершает серверную транзакцию подписи.
● Закрытый ключ не передается в 1С и не отправляется на сервер.
● thumbprint выбирает сертификат в локальном хранилище.
● mchdInfoId передается только когда API сопоставил действующую МЧД.
● PIN не берется из регистра; интерактивный запрос выполняет криптопровайдер.
● После вызова обработка перечитывает перевозку и различает принятую подпись и завершенную серверную регистрацию Т1.
5.6. Т2 и Т3
Т2 в текущей обработке не формируется. Его оформляет перевозчик в кабинете МИГ24 или другой интеграцией. Пока Т2 не принят, сервер не разрешает грузополучателю Т3.
Для Т3 обработка использует ПоступлениеТоваровУслуг, связанное с transportationId. Перед открытием формы проверяются организация, роль грузополучателя и список доступных действий. ФормаТ3 собирает фактические данные приемки. Сервер возвращает новый signingEntity, который подписывается той же командой epd-sign-entity с типом титула Т3.
5.7. Стадии перевозки
5.8. Дополнительные команды ЭПД в компоненте
Компонента содержит команды carrier-acceptance, carrier-cargo-release, carrier-financial-change, consignee-acceptance, partial-acceptance, refusal, driver-vehicle-replacement, readdressing и shipper-financial-change-confirmation. Текущая обработка напрямую использует только сценарии, необходимые для Т1 и Т3. Остальные команды нельзя подключать одной кнопкой без проектирования формы данных и проверки допустимых ролей/стадий на /actions.
5.9. Электронная заявка на перевозку (ЭЗЗ)
Order-requests - предварительный этап согласования условий перевозки до создания самой перевозки (Т1). Основной идентификатор — orderRequestId.
Жизненный цикл ЭЗЗ:
  1. Грузоотправитель формирует XML ЭЗЗ → вызов epd-create-order-request.
  2. Получение ответа: сохранение orderRequestId, packageFileId и signingEntity.
  3. Подпись: вызов существующей команды epd-sign-entity с полученным signingEntity.
  4. Получение карточки (epd-order-requests) и доступных действий (epd-order-requests-actions).
  5. Согласование/отклонение/уточнение → получение нового signingEntity → повторная подпись через epd-sign-entity.
  6. Создание перевозки (epd-order-request-transportations) только когда сервер возвращает kind: OrderRequestContinueWithWaybill.
Важные правила обработки:
  • Валидация: Поле validation.isValid в примере приходит как строка "true", а не как JSON boolean. Всегда проверяйте errors и warnings даже при HTTP 200.
  • Тип подписи: При создании ЭЗЗ signingEntity.type = PackageGroupAction. При согласовании перевозчиком (approve) тип меняется на PackageAction. Всегда берите тип из ответа, не жестко кодируйте его.
  • Идемпотентность: Если orderRequestId уже сохранен, повторное нажатие кнопки не должно создавать новую заявку. Используйте сохраненный signingEntity для повторной попытки подписи.
OpenAPI объявляет перечисления в lowerCamelCase, но фактические ответы могут возвращать PascalCase. Сравнивать kind, formalizedDocType и actionStatus нужно без учета регистра.
XSD-схемы для ЭЗЗ:
  • Т1 грузоотправителя: ON_ZAKZVGO_1_969_01_05_01_01_external.xsd
  • Т2 перевозчика (5.01.03): ON_ZAKZVPER_1_969_02_05_01_03_external.xsd
  • Т2 перевозчика (5.01.02): ON_ZAKZVPER_1_969_02_05_01_02_external.xsd
5.10. Хранение данных для ЭЗЗ (Рекомендуемые поля регистра)
Для корректной работы добавьте в регистры хранения (аналогично МИГ24_ПараметрыЭТРН) следующие поля:
  • orderRequestId (сразу после create, для идемпотентности).
  • processId (связь серверного процесса).
  • packageFileId и formalizedDocType (для различения Shipper/Carrier).
  • signingEntity.id и signingEntity.type (до момента успешной подписи).
  • transportationStatus и modificationDateTime (для контроля устаревания кэша).
5.11. Экспедиции, события и файлы
Компонента 1.0.0598 поддерживает полный цикл экспедиционных документов и специализированных событий.
Экспедиции: Создание (epd-create-expedition), чтение и действия. Поддерживаются следующие типы документов и XSD-схемы:
  • Т1 — поручение экспедитору (ON_POREXPKLT_1_958_05_05_01_01_external.xsd)
  • Т2 — информация экспедитора (ON_POREXPEXP_1_958_06_05_01_01_external.xsd)
  • Т3 — отзыв поручения (ON_POREXPOTZ_1_958_07_05_01_01_external.xsd)
  • Экспедиторская расписка (ON_EXPRASP_1_958_01_05_01_01_external.xsd)
  • Складская расписка (ON_SKLADRASP_1_958_03_05_01_01_external.xsd)
События: Для асинхронного получения статусов используются команды epd-events (все неподтвержденные), а также специализированные epd-order-request-status-changed и epd-expedition-status-changed. Правило: После успешной локальной обработки события его необходимо подтвердить через существующие epd-ack-single-event или epd-ack-events. Сначала фиксируйте результат в 1С, затем отправляйте ack.
Файлы: Команда epd-get-file принимает fileId из массива files[] карточки документа и возвращает бинарное тело файла с фактическим MIME-типом и Content-Disposition.

6. Диагностика

6.1. Ошибка certificates-list-match / OrganizationUsers 404
Если в тексте ошибки виден запрос {"settings":{"host":"","token":""}}, проблема возникает до проверки сертификата. Компонента не может обратиться к /api/v1/organization-users без настроек организации.
● Проверить запись МИГ24_НастройкиОрганизаций именно для выбранной ссылки Организация.
● Проверить непустые host и token без пробелов и переносов.
● Перечитать настройки после изменения организации.
● Не считать запись МИГ24_Пользователи источником host/token: она хранит только привязку сертификата.
● В исправленных формах 8.2/8.3 настройки перечитываются при открытии и непосредственно перед выбором сертификата; пустой запрос блокируется локально.
6.2. Разделение источников ошибки
6.3. Что собирать для разбора
● Версия платформы 1С и разрядность процесса.
● Имя команды компоненты и HTTP-код.
● host без token; token передавать только защищенным каналом ответственному специалисту.
● Тип документа, его ссылка/номер и сохраненные ID.
● Стадия перевозки и ответ /actions для ЭПД.
● Текст исключения криптопровайдера без PIN и закрытых данных.

7. Правила изменения кода

● Не переводить и не менять регистр строковых команд Native-компоненты.
● Не переводить JSON-ключи и свойства ответа. Для понятности использовать русские локальные переменные и комментарии вокруг них.
● Не смешивать модуль 8.2 с модулем 8.3: сериализация JSON и доступные методы платформы различаются.
● Не создавать новый transportationId/documentId при повторной попытке подписи.
● Не подтверждать eventId до успешной записи события в 1С.
● Не выполнять действие ЭПД без проверки /actions и роли организации.
● Не хранить PIN и не выводить token в протокол.
● После изменения исходника формы обновить тот же модуль внутри EPF и проверить выгрузку Конфигуратором.
● Не создавайте новый orderRequestId при повторной попытке подписи или ошибке сети. Используйте сохраненный signingEntity.
● Никогда не создавайте кнопки действий (Approve/Reject/Clarification) на основе локального статуса. Всегда запрашивайте массив /actions и создавайте кнопки только для тех kind, которые вернул сервер.
● Не предполагайте, что поле drivers в списке ЭЗЗ является массивом (в примерах оно приходит как пустая строка). Проверяйте тип данных.
● На Linux команда epd-sign-entity для новых сущностей может отсутствовать. Полный сценарий подписания ЭЗЗ требует Windows-компоненты или согласованного альтернативного механизма.
● Обязательный переход имени команды: Для создания перевозки по ЭЗЗ используйте только epd-order-request-transportations. Старое имя epd-action-order-request-transportations удалено из реестра 1.0.0598; оставлять alias не требуется.
● Сравнение перечислений: OpenAPI объявляет значения в lowerCamelCase, но фактические ответы сервера могут возвращать PascalCase. Сравнивайте поля kind, formalizedDocType, actionStatus и signingEntity.type без учета регистра, сохраняя исходное значение для последующей отправки.
● Нормализация типов: Ответ компоненты может строкифицировать boolean и number. Обертка 1С должна нормализовать response.valid, httpCode, hasData и validation.isValid перед использованием в условиях.

8. Контрольный сценарий сопровождения

После установки или изменения выполнить последовательно:
● Открыть обработку, выбрать организацию и убедиться, что заголовок показывает правильный контур.
● Проверить host/token и выполнить безопасный запрос списка контрагентов или состояния.
● Выбрать сертификат; проверить восстановление привязки после повторного открытия формы.
● Для ЭДО создать документ, пакет, подпись и обработать событие статуса.
● Для ЭПД создать Т1, проверить сохранение transportationId до подписи и отсутствие дубля при повторе.
● После Т2 проверить доступность Т3 и серверное подтверждение его регистрации.
● Проверить регистры и отсутствие token/PIN в пользовательских сообщениях.
● ЭЗЗ: Создать ЭЗЗ, убедиться, что возвращены orderRequestId, packageFileId и signingEntity. Проверить, что ошибки валидации XML (isValid: false) обрабатываются, а не игнорируются из-за HTTP 200.
● ЭЗЗ: Выполнить действие approve, убедиться, что пришел новый signingEntity с типом PackageAction, успешно подписать его и перечитать карточку
● Регрессия: Убедиться, что старые сценарии ЭДО (создание пакета, подпись) и ЭПД (создание Т1, Т3) работают с новой версией компоненты без изменений в коде.
● Версия и реестр: Убедиться, что ProductVersion DLL равна 1.0.0598. Проверить наличие команды epd-order-request-transportations и отсутствие старого имени с action-.
● События и файлы: Проверить чтение специализированных событий статуса ЭЗЗ/экспедиции и корректное получение бинарного файла через epd-get-file.
● Регрессия POST-запросов: Перед промышленным выпуском выполнить полный smoke-тест изменяющих операций (создание ЭЗЗ, согласование, создание перевозки), так как бинарный анализ подтверждает только маршруты и GET-запросы.

9. Карта исходных файлов

Запросить исходные файлы можно через info@mig24.ru