API Диадока: как интегрировать ЭДО с 1С и собственной системой

ЭДО редко заканчивается на отправке одного документа из интерфейса оператора. В реальном бизнес-процессе УПД или другой электронный документ сначала появляется в учётной системе, затем должен попасть в Диадок, пройти документооборот, получить подпись или подтверждение, а результат должен вернуться обратно в 1С или корпоративную систему.

Если документооборот нужно встроить в собственный бизнес-процесс, одного готового интерфейса ЭДО становится недостаточно. Нужен интеграционный слой, который понимает, какой документ отправлять, в какой ящик, в каком состоянии находится документооборот и что делать после получения нового события.

У Диадока для этого есть HTTP API. Официальная документация описывает API как универсальный способ построения собственного решения, работающего с системой из внешней учётной системы. Доступны также SDK и готовые интеграционные решения, включая модуль для 1С.

Что такое API Диадока

Диадок — система обмена юридически значимыми электронными документами между организациями. API позволяет внешней системе обращаться к Диадоку программно, без ручной работы оператора. Официальная документация предусматривает HTTP API как платформо-независимый способ интеграции.

Точка входа основной площадки API:

https://diadoc-api.kontur.ru

Для разработки и проверки интеграции предусмотрена отдельная тестовая площадка:

https://diadoc-api-staging.kontur.ru

Точные методы и версии API меняются, поэтому при реализации конкретной интеграции нужно ориентироваться на актуальную документацию и политику устаревания методов. В текущем каталоге API есть отдельные группы методов для документов, документооборота, событий, организаций и ящиков, контрагентов, подписания и других операций.

Когда нужен именно API, а когда достаточно готового решения

У Диадока есть несколько вариантов интеграции. Помимо прямого HTTP API, официальная документация перечисляет SDK, Диадок.Коннектор и модуль для 1С. Выбор зависит от требований к бизнес-процессу, клиентской части и средствам разработки.

Вариант	Когда подходит
Модуль для 1С	Нужно встроить ЭДО непосредственно в конфигурацию 1С
Диадок.Коннектор	Нужна готовая интеграция с учётной системой без разработки собственного HTTP-контура
SDK	Нужно упростить разработку клиентского приложения
HTTP API	Нужна собственная интеграционная архитектура, несколько систем или нестандартный бизнес-процесс

Для связки 1С + Symfony/Go + несколько внешних систем прямой API обычно интереснее архитектурно: интеграционную логику можно вынести из 1С в отдельный сервис и централизовать очереди, retry, журналирование и контроль состояния.

Авторизация в API Диадока

Для начала работы с HTTP API необходимо зарегистрировать интеграционное решение и получить данные для авторизации. После получения токена API вызывается с заголовком:

Authorization: Bearer <access_token>

Например, запрос к получению организаций выглядит концептуально так:

GET /GetMyOrganizations
Host: diadoc-api.kontur.ru
Authorization: Bearer <access_token>
Accept: application/json

Срок жизни access token ограничен, поэтому интеграционный сервис должен уметь обновлять токен до истечения его действия, а не рассчитывать на постоянное значение.

На практике credentials и токены нельзя хранить в исходном коде приложения. Их следует вынести в защищённое хранилище секретов или переменные окружения, а доступ к ним ограничить.

Какие задачи можно решать через API Диадока

API покрывает существенно больше, чем простую отправку XML. В каталоге есть методы для работы с документами, событиями, документооборотом, организациями и ящиками, контрагентами, подписями и другими сущностями.

Типовой интеграционный контур может включать:

• получение организаций и ящиков;
• поиск и получение документов;
• получение содержимого документа;
• получение истории документа;
• отслеживание событий;
• контроль статуса документооборота;
• работу с контрагентами;
• подписание и другие действия, доступные конкретному документу;
• синхронизацию результата обратно в 1С или ERP.

Архитектура 1С → Диадок

Самая простая схема выглядит так:

1С
 ↓
HTTP API
 ↓
Диадок
 ↓
Контрагент

Для небольшого обмена этого может быть достаточно. Но при большом объёме документов или нескольких системах лучше использовать отдельный Integration Layer:

                 ┌──────────────┐
                 │     1С       │
                 └──────┬───────┘
                        │
                 ┌──────▼───────┐
                 │ Integration  │
                 │    Layer     │
                 └──────┬───────┘
                        │
                ┌───────▼────────┐
                │ Queue / Retry  │
                └───────┬────────┘
                        │
                ┌───────▼────────┐
                │ Диадок HTTP API│
                └───────┬────────┘
                        │
                 ┌──────▼───────┐
                 │ Контрагент   │
                 └──────────────┘

Такой слой особенно полезен, когда кроме 1С нужно подключить CRM, WMS, собственный портал, сервис согласования или архив документов.

Почему не стоит делать всю интеграцию внутри 1С

В простом сценарии отправка документа непосредственно из 1С выглядит логично. Но по мере роста требований внутри учётной системы начинает появляться слишком много интеграционной логики:

• авторизация;
• очередь отправки;
• повторные попытки;
• обработка ошибок API;
• синхронизация статусов;
• логирование HTTP-запросов;
• идемпотентность;
• мониторинг;
• маршрутизация документов между несколькими системами.

Для enterprise-контура разумнее оставить 1С владельцем бизнес-данных и документов, а техническую интеграцию вынести в отдельный сервис.

Как получать документы из Диадока

В API есть методы получения списка документов. Например, актуальный метод GetDocuments (V4) принимает идентификатор ящика и параметры поиска. В ответ возвращается список документов, но содержимое документа не включается автоматически; его можно получать отдельным вызовом. В одном ответе возвращается не более 100 документов.

Это важный архитектурный момент. Не стоит строить синхронизацию как постоянный полный импорт всех документов.

Лучше использовать инкрементальный механизм:

Последний обработанный индекс
        ↓
Получить новые события
        ↓
Определить изменившиеся документы
        ↓
Забрать необходимые данные
        ↓
Сохранить состояние
        ↓
Обновить 1С

События: как не опрашивать Диадок целиком

Для интеграционного сервиса особенно важна работа с событиями. Документация Диадока содержит методы получения ленты событий в ящике, включая GetNewEvents, а также методы работы с событиями документооборота.

Отдельно существует GetDocflowEvents (V4), который возвращает события, произошедшие с документами: появление нового документа или изменение существующего. Для постраничного получения событий используется индекс, что позволяет строить инкрементальную синхронизацию.

Это намного надёжнее архитектуры вида:

Каждые 5 минут
    ↓
Скачать все документы
    ↓
Сравнить
    ↓
Найти изменения

Правильнее хранить checkpoint и получать только изменения после него.

Что такое index key и зачем он нужен

В событиях Диадока используется индекс для постраничного получения данных. Например, в структуре BoxEvent поле IndexKey может передаваться как afterIndexKey при последующем вызове GetNewEvents. При передаче его необходимо корректно кодировать для URL.

На уровне собственного сервиса это можно представить так:

diadoc_sync_state
------------------
box_id
last_index_key
last_success_at
status

Тогда после перезапуска сервиса синхронизация продолжается с последней подтверждённой позиции, а не начинается с начала.

Получение содержимого документа

Метод получения документа возвращает данные документа по его идентификаторам. В зависимости от способа запроса содержимое может включаться непосредственно в ответ, но для больших данных предусмотрен отдельный механизм получения содержимого. В текущей документации для GetDocument (V3) указано ограничение: если размер содержимого превышает 1 048 576 байт, его нужно получать через GetEntityContent (V4).

Поэтому не стоит проектировать интеграцию как «каждый найденный документ всегда возвращает весь XML». Метаданные документа и его содержимое лучше рассматривать как отдельные части данных.

Как синхронизировать статусы документов

У документа есть жизненный цикл, а бизнес-система обычно должна знать не только сам факт существования УПД, но и его состояние в документообороте.

Внутреннюю модель можно сделать нормализованной:

Document
 ├── external_id
 ├── message_id
 ├── entity_id
 ├── document_type
 ├── document_date
 ├── number
 ├── counterparty
 ├── direction
 └── status

Docflow
 ├── sent_at
 ├── delivered_at
 ├── signed_at
 ├── rejected_at
 └── completed_at

В таком случае 1С или CRM не обязаны знать все технические сущности API Диадока. Они получают нормализованный бизнес-статус.

Диадок + 1С: типовой сценарий отправки УПД

Рассмотрим типовую последовательность:

1. В 1С проведён документ
        ↓
2. Integration Layer получает задачу
        ↓
3. Проверяет контрагента
        ↓
4. Формирует сообщение для Диадока
        ↓
5. Отправляет документ
        ↓
6. Сохраняет внешний идентификатор
        ↓
7. Получает события документооборота
        ↓
8. Обновляет статус
        ↓
9. Возвращает результат в 1С

Ключевой момент — внешний идентификатор должен сохраняться сразу после успешной операции. Иначе повторный запуск может создать дубликат.

Идемпотентность: как не отправить один документ дважды

Для ЭДО это особенно важно. Если HTTP-запрос завершился таймаутом, интеграционный сервис не всегда знает, успел ли Диадок принять документ. Простое правило «если ошибка — отправить ещё раз» может привести к повторной операции.

Поэтому нужно хранить собственный correlation/idempotency key и состояние операции:

integration_operation
---------------------
operation_id
source_system
source_document_id
external_message_id
operation_type
status
attempts
created_at
updated_at

После этого retry становится контролируемым процессом, а не повторной отправкой «на всякий случай».

Retry и Dead Letter Queue

Внешний API может временно быть недоступен, вернуть сетевую ошибку или ответить, который требует повторной попытки. Поэтому отправку документов лучше выполнять асинхронно.

1С
 ↓
Outbox
 ↓
Queue
 ↓
Диадок API
 ├── success → completed
 ├── temporary error → retry
 └── permanent error → DLQ

В очередь можно вынести:

• отправку документов;
• получение событий;
• загрузку содержимого;
• обновление статусов;
• повторные попытки;
• уведомления бизнес-системы.

Symfony + Диадок API

Для собственного integration service Symfony хорошо подходит как HTTP/API слой, а Symfony Messenger — как механизм асинхронной обработки.

1С
 ↓
Symfony API
 ↓
Doctrine / PostgreSQL
 ↓
Symfony Messenger
 ↓
DiadocClient
 ↓
Диадок API

Клиент Диадока при этом лучше вынести в отдельный сервис с понятным контрактом:

interface DiadocClientInterface
{
    public function getOrganizations(): array;

    public function getEvents(
        string $boxId,
        ?string $afterIndexKey = null
    ): array;

    public function getDocument(
        string $boxId,
        string $messageId,
        string $entityId
    ): DocumentDto;
}

Бизнес-логика не должна напрямую зависеть от HTTP-формата конкретного endpoint. Это упрощает тестирование и замену реализации.

Go + Диадок API

Для высоконагруженного интеграционного шлюза можно использовать Go:

1С / ERP
    ↓
Go Integration Gateway
    ↓
Queue
    ↓
Diadoc API
    ↓
PostgreSQL
    ↓
1С / CRM / DWH

Особенно полезен такой подход, когда через один gateway проходят Диадок, СБИС, ФНС, маркетплейсы и другие внешние API.

Диадок + несколько систем

На enterprise-проекте задача часто выглядит не как «подключить Диадок к 1С», а как построить единый контур документов:

                 ┌─────────────┐
                 │     1С      │
                 └──────┬──────┘
                        │
┌─────────────┐         ▼         ┌─────────────┐
│     CRM     │ ──► Integration ◄─│     WMS     │
└─────────────┘       Layer       └─────────────┘
                        │
                 ┌──────▼──────┐
                 │    Queue    │
                 └──────┬──────┘
                        │
              ┌─────────▼─────────┐
              │      Диадок       │
              └─────────┬─────────┘
                        │
                  Контрагенты

В этом случае Диадок становится одним из внешних каналов документооборота, а Integration Layer отвечает за маршрутизацию и состояние.

Что хранить в собственной базе

Не нужно копировать в PostgreSQL весь внутренний объектный граф Диадока. Достаточно хранить данные, необходимые для идемпотентности, поиска и бизнес-процессов.

diadoc_document
----------------
id
box_id
message_id
entity_id
counteragent_box_id
document_type
document_number
document_date
direction
status
source_system
source_document_id
created_at
updated_at

diadoc_sync_state
-----------------
box_id
last_index_key
last_success_at

integration_operation
---------------------
operation_id
source_document_id
external_id
operation
status
attempts

Безопасность

ЭДО работает с юридически значимыми документами, поэтому интеграционный сервис должен рассматриваться как критичный контур.

Минимальный набор мер:

• секреты и токены не хранятся в Git;
• доступ к API ограничен сервисными credentials;
• все операции журналируются;
• чувствительные данные не попадают без необходимости в обычные application logs;
• доступ к документам разделяется по организациям и подразделениям;
• retry не должен приводить к повторному бизнес-действию;
• все внешние идентификаторы сохраняются.

Какую архитектуру выбрать

Для небольшого проекта:

1С → Диадок

Для проекта со сложными бизнес-процессами:

1С
 ↓
Integration Service
 ↓
Queue
 ↓
Диадок

Для enterprise-контура:

┌──────────┐
│    1С    │
└────┬─────┘
     │
┌────▼───────────────┐
│ Integration Layer  │
│ API / Mapping      │
│ Validation         │
│ Idempotency        │
└────┬───────────────┘
     │
┌────▼───────────────┐
│ Queue              │
│ Retry / DLQ        │
└────┬───────────────┘
     │
┌────▼───────────────┐
│ Diadoc Adapter     │
└────┬───────────────┘
     │
┌────▼───────────────┐
│ Диадок HTTP API    │
└────────────────────┘
     │
     ▼
Контрагенты

     +
     │
     ▼
PostgreSQL / Audit / Monitoring

Типичные ошибки при интеграции Диадока

Ошибка	Последствие
Хранить access token как константу	Интеграция перестаёт работать после истечения срока действия
Полностью импортировать документы при каждом запуске	Растёт нагрузка и усложняется синхронизация
Игнорировать события	Статусы документов обновляются с задержкой
Повторять запрос после любого timeout	Можно получить повторное бизнес-действие
Не хранить внешние ID	Невозможно надёжно связать документ 1С и Диадока
Зашивать API Диадока непосредственно в бизнес-логику	Изменения API начинают затрагивать весь код приложения
Считать 1С единственным integration engine	Очереди, retry и мониторинг начинают смешиваться с учётной логикой

Минимальный MVP интеграции

Для первого этапа необязательно реализовывать весь каталог API. Достаточно одного бизнес-сценария.

Диадок API и AI

После построения надёжного интеграционного слоя поверх ЭДО можно добавлять AI-функции. Но LLM не должна напрямую управлять API Диадока и самостоятельно принимать юридически значимые решения.

Например, AI может:

• классифицировать входящие документы;
• извлекать реквизиты;
• сопоставлять документ с заказом или договором;
• объяснять причину ошибки обработки;
• готовить уведомление ответственному сотруднику;
• искать документы по естественному языковому запросу.

А выполнение юридически значимого действия должно проходить через контролируемый business tool и заданные права.

Диадок
   ↓
Integration Layer
   ↓
Business Tools
   ↓
AI Orchestrator
   ↓
LLM

LLM → рекомендация
Business Tool → проверка
Business Rule → разрешение
Action → выполнение

Итог

API Диадока позволяет встроить ЭДО непосредственно в собственную информационную систему, а не ограничиваться готовым пользовательским интерфейсом.

Для простой задачи достаточно связать 1С с API. Для сложного enterprise-сценария лучше строить отдельный Integration Layer с очередью, retry, идемпотентностью, журналом операций и собственной моделью состояния документов.

Особенно важен переход от модели «периодически забираем документы» к событийной синхронизации: храним checkpoint, получаем изменения, обрабатываем их и подтверждаем состояние в собственной системе.

В результате получается не просто интеграция с ЭДО, а управляемый контур:

1С / ERP
    ↓
Integration Layer
    ↓
Queue / Retry / Idempotency
    ↓
Диадок API
    ↓
Контрагент
    ↓
Events / Docflow
    ↓
1С / ERP / CRM / Analytics

Именно такой подход позволяет постепенно расширять решение: добавить новые типы документов, новые системы, автоматическую маршрутизацию, мониторинг и AI-аналитику, не превращая 1С в монолитный integration gateway.