Контур.Диадок API API

Отрасль: Учёт и ERP. Актуально на 2026-10-25.

API системы электронного документооборота Контур.Диадок для обмена юридически значимыми документами между организациями. Позволяет интегрировать учётную систему (1С, ERP) с Диадоком: авторизоваться, найти свои ящики и ящики контрагентов, пригласить контрагента, отправить УПД, счёт-фактуру, акт или неформализованный документ, получать входящие события, подписывать документы титулом получателя, скачивать содержимое и печатные формы. Данные передаются в JSON (часть методов поддерживает protobuf).

Охват

Есть:

Аутентификация по логину и паролю, заголовок DiadocAuth
Свои организации и ящики, поиск организации по ИНН/КПП
Список контрагентов и приглашение к обмену
Типы документов ящика и генерация XML-титула формализованного документа
Отправка документов любых типов (DocumentAttachments)
Лента событий ящика для получения входящих
Список документов, содержимое сущности, печатная форма PDF
Подпись входящего документа: титул получателя через дополнение к сообщению

Нет — смотри официальную документацию:

Вход по сертификату и auth.sid, расшифровка токена (проще через SDK)
Формирование электронной подписи (CMS, КЭП) — делается на стороне клиента
Машиночитаемые доверенности (МЧД), DSS-подпись
Аннулирование, отказ в подписи, уведомления об уточнении, извещения о получении
Согласование, маршруты, подразделения, сотрудники, группы контрагентов
Шаблоны и черновики, полка документов для больших файлов, роуминг

Сценарии

Войти и найти свой ящик

Без авторизационного токена и идентификатора ящика (BoxId) не работает ни один метод.

Получи токен: POST /V3/Authenticate?type=password с JSON {"login": ..., "password": ...} и заголовком Authorization: DiadocAuth ddauth_api_client_id={ключ разработчика}.
Дальше в каждом запросе передавай Authorization: DiadocAuth ddauth_api_client_id={ключ}, ddauth_token={токен}.
Получи организации пользователя: GET /GetMyOrganizations.
Возьми Organizations[].Boxes[].BoxIdGuid — его передают в методы как boxId.

curl -X POST "https://diadoc-api.kontur.ru/V3/Authenticate?type=password" \
  -H "Authorization: DiadocAuth ddauth_api_client_id=$CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"login": "user@example.com", "password": "secret"}'

curl "https://diadoc-api.kontur.ru/GetMyOrganizations" \
  -H "Authorization: DiadocAuth ddauth_api_client_id=$CLIENT_ID, ddauth_token=$TOKEN"

Пригласить контрагента к обмену

Документы можно отправлять организациям, с которыми установлены партнёрские отношения (если получатель принимает документы только от контрагентов).

Найди организацию по ИНН: GET /GetOrganizationsByInnKpp?inn=... — возьми OrgId и ящик.
Проверь текущий статус: GET /V3/GetCounteragents?myBoxId=...&query={ИНН} — CurrentStatus (IsMyCounteragent, InvitesMe, IsInvitedByMe и др.).
Отправь приглашение: POST /V3/AcquireCounteragent?myBoxId=... с OrgId или Inn и сообщением — в ответе TaskId.
Получи результат: GET /V2/AcquireCounteragentResult?taskId=... — при 204 повтори через время из заголовка Retry-After.

curl "https://diadoc-api.kontur.ru/GetOrganizationsByInnKpp?inn=6663003127" \
  -H "Authorization: DiadocAuth ddauth_api_client_id=$CLIENT_ID, ddauth_token=$TOKEN"

curl -X POST "https://diadoc-api.kontur.ru/V3/AcquireCounteragent?myBoxId=$BOX_ID" \
  -H "Authorization: DiadocAuth ddauth_api_client_id=$CLIENT_ID, ddauth_token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"Inn": "6663003127", "MessageToCounteragent": "Предлагаем обмениваться документами через Диадок"}'

curl "https://diadoc-api.kontur.ru/V2/AcquireCounteragentResult?taskId=$TASK_ID" \
  -H "Authorization: DiadocAuth ddauth_api_client_id=$CLIENT_ID, ddauth_token=$TOKEN"

Отправить УПД или другой формализованный документ

Формализованный документ отправляется как XML-титул отправителя с электронной подписью.

Узнай доступные типы: GET /V3/GetDocumentTypes?boxId=... — нужны Name (TypeNamedId), функция и версия.
Сгенерируй XML титула: POST /GenerateTitleXml?boxId=...&documentTypeNamedId=...&documentFunction=...&documentVersion=...&titleIndex=0, в теле — упрощённый UserDataXml по XSD контракта.
Подпиши XML своей КЭП (CMS SignedData, DER) на стороне клиента.
Отправь: POST /V3/PostMessage с FromBoxId, ToBoxId и DocumentAttachments[] (TypeNamedId, Function, Version, SignedContent.Content, SignedContent.Signature). В ответе — MessageId и Entities.
Передавай operationId, чтобы повтор запроса не создал дубликат.

curl -X POST "https://diadoc-api.kontur.ru/V3/PostMessage?operationId=$OPERATION_ID" \
  -H "Authorization: DiadocAuth ddauth_api_client_id=$CLIENT_ID, ddauth_token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "FromBoxId": "'"$BOX_ID"'",
    "ToBoxId": "'"$COUNTERAGENT_BOX_ID"'",
    "DocumentAttachments": [{
      "TypeNamedId": "'"$TYPE_NAMED_ID"'",
      "Function": "'"$FUNCTION"'",
      "Version": "'"$VERSION"'",
      "SignedContent": {"Content": "'"$XML_BASE64"'", "Signature": "'"$SIGNATURE_BASE64"'"}
    }]
  }'

Забирать входящие документы

Лента событий ящика: каждое событие содержит новое сообщение или дополнение к нему.

Вызови GET /V8/GetNewEvents?boxId=...&documentDirection=Inbound.
Обработай Events[]: Message — новые документы, Patch — подписи, отказы, титулы.
Сохрани IndexKey последнего события и передавай его в afterIndexKey при следующем вызове.
Содержимое документа скачай: GET /V4/GetEntityContent?boxId=...&messageId=...&entityId=....

curl "https://diadoc-api.kontur.ru/V8/GetNewEvents?boxId=$BOX_ID&documentDirection=Inbound&afterIndexKey=$LAST_INDEX_KEY" \
  -H "Authorization: DiadocAuth ddauth_api_client_id=$CLIENT_ID, ddauth_token=$TOKEN"

curl "https://diadoc-api.kontur.ru/V4/GetEntityContent?boxId=$BOX_ID&messageId=$MESSAGE_ID&entityId=$ENTITY_ID" \
  -H "Authorization: DiadocAuth ddauth_api_client_id=$CLIENT_ID, ddauth_token=$TOKEN" -o document.xml

Подписать входящий документ

Для двусторонних документов (УПД, акт) получатель формирует и подписывает свой титул.

Сгенерируй титул получателя: POST /GenerateTitleXml с titleIndex титула получателя, letterId (сообщение) и documentId (документ отправителя).
Подпиши XML своей КЭП.
Отправь дополнение: POST /V3/PostMessagePatch с BoxId, MessageId и RecipientTitles[] (ParentEntityId — титул отправителя, SignedContent).

curl -X POST "https://diadoc-api.kontur.ru/V3/PostMessagePatch" \
  -H "Authorization: DiadocAuth ddauth_api_client_id=$CLIENT_ID, ddauth_token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "BoxId": "'"$BOX_ID"'",
    "MessageId": "'"$MESSAGE_ID"'",
    "RecipientTitles": [{
      "ParentEntityId": "'"$ENTITY_ID"'",
      "SignedContent": {"Content": "'"$XML_BASE64"'", "Signature": "'"$SIGNATURE_BASE64"'"}
    }]
  }'

Получить печатную форму PDF

Вызови GET /GeneratePrintForm?boxId=...&messageId=...&documentId=....
Если тело пустое и есть заголовок Retry-After — повтори запрос через указанное число секунд.
Готовая форма приходит PDF-файлом.

curl -i "https://diadoc-api.kontur.ru/GeneratePrintForm?boxId=$BOX_ID&messageId=$MESSAGE_ID&documentId=$DOCUMENT_ID" \
  -H "Authorization: DiadocAuth ddauth_api_client_id=$CLIENT_ID, ddauth_token=$TOKEN" -o printform.pdf

Базовые URL

Боевой: https://diadoc-api.kontur.ru
Тестовый: https://diadoc-api.testkontur.ru

Авторизация

Тип: Другое

Нужны ключ разработчика (выдаётся по заявке на https://www.diadoc.ru/integrations/api) и авторизационный токен пользователя. Оба передаются в заголовке по схеме DiadocAuth:

Токен выдаёт POST /V3/Authenticate: по логину и паролю (type=password, JSON с login и password), по сертификату (type=certificate, ответ расшифровывается закрытым ключом и подтверждается через /V3/AuthenticateConfirm) или по auth.sid (type=sid).

Authorization: DiadocAuth ddauth_api_client_id={{client_id}}, ddauth_token={{auth_token}}

Методы

POST /V3/Authenticate — Аутентификация

В ответе — авторизационный токен (для password) или зашифрованная строка (для certificate).

Документация: https://developer.kontur.ru/doc/diadoc.api/method?type=post&path=%2FV3%2FAuthenticate

Параметр	Где	Тип	Обяз.	Описание
`type`	query	string	да	password, certificate или sid
`Authorization`	header	string	да	DiadocAuth ddauth_api_client_id={ключ разработчика}
`login`	body	string	нет	Логин (при type=password)
`password`	body	string	нет	Пароль (при type=password)

GET /GetMyOrganizations — Организации пользователя

Organizations[]: OrgId, Inn, Kpp, FullName, ShortName, Ogrn, FnsParticipantId, Boxes[] (BoxId, BoxIdGuid, Title), Departments, IsRoaming, IsTest, Sociability.

Документация: https://developer.kontur.ru/doc/diadoc.api/method?type=get&path=%2FGetMyOrganizations

Параметр	Где	Тип	Обяз.	Описание
`Authorization`	header	string	да	Ключ разработчика и токен
`autoRegister`	query	boolean	нет	Регистрировать в организацию из сертификата (по умолчанию true)

GET /GetOrganizationsByInnKpp — Организация по ИНН/КПП

Может вернуть несколько организаций с одинаковым ИНН и ИНН-КПП.

Документация: https://developer.kontur.ru/doc/diadoc.api/method?type=get&path=%2FGetOrganizationsByInnKpp

Параметр	Где	Тип	Обяз.	Описание
`inn`	query	string	да	ИНН
`kpp`	query	string	нет	КПП; без него — ящики всех организаций с этим ИНН
`includeRelations`	query	boolean	нет	Вернуть число заинтересованных контрагентов

GET /V3/GetCounteragents — Список контрагентов

Counteragents[]: IndexKey, Organization, CurrentStatus (IsMyCounteragent, InvitesMe, IsInvitedByMe, RejectsMe, IsRejectedByMe …), сообщения; TotalCount.

Документация: https://developer.kontur.ru/doc/diadoc.api/method?type=get&path=%2FV3%2FGetCounteragents

Параметр	Где	Тип	Обяз.	Описание
`myBoxId`	query	string	да	Ящик организации (GUID)
`counteragentStatus`	query	string	нет	Фильтр по статусу
`query`	query	string	нет	Поиск по наименованию или ИНН
`afterIndexKey`	query	string	нет	Ключ следующей страницы (URL-кодированный)
`pageSize`	query	integer	нет	1–100, по умолчанию 100

POST /V3/AcquireCounteragent — Приглашение контрагента

Асинхронный: возвращает TaskId, результат — в /V2/AcquireCounteragentResult.

Документация: https://developer.kontur.ru/doc/diadoc.api/method?type=post&path=%2FV3%2FAcquireCounteragent

Параметр	Где	Тип	Обяз.	Описание
`myBoxId`	query	string	да	Ящик, от имени которого приглашаем
`myDepartmentId`	query	string	нет	Подразделение
`OrgId`	body	string	нет	ID организации контрагента
`Inn`	body	string	нет	ИНН контрагента
`BoxId`	body	string	нет	Ящик контрагента
`MessageToCounteragent`	body	string	нет	Сообщение, до 2000 символов
`InvitationDocument`	body	object	нет	Файл приглашения (FileName, SignedContent, SignatureRequested)

GET /V2/AcquireCounteragentResult — Результат приглашения

200 — BoxId приглашённой организации; 204 — ещё выполняется (заголовок Retry-After); 409 — приглашение не удалось.

Документация: https://developer.kontur.ru/doc/diadoc.api/method?type=get&path=%2FV2%2FAcquireCounteragentResult

Параметр	Где	Тип	Обяз.	Описание
`taskId`	query	string	да	TaskId из AcquireCounteragent

GET /V3/GetDocumentTypes — Типы документов ящика

DocumentTypes[]: Name (TypeNamedId), Title, SupportedDocflows, RequiresFnsRegistration, Functions (с версиями и титулами).

Документация: https://developer.kontur.ru/doc/diadoc.api/method?type=get&path=%2FV3%2FGetDocumentTypes

Параметр	Где	Тип	Обяз.	Описание
`boxId`	query	string	да	Ящик (GUID)

POST /GenerateTitleXml — Генерация XML титула

Тело — упрощённый XML UserDataXml по XSD-схеме контракта типа документа.

Документация: https://developer.kontur.ru/doc/diadoc.api/method?type=post&path=%2FGenerateTitleXml

Параметр	Где	Тип	Обяз.	Описание
`boxId`	query	string	да	Ящик (GUID)
`documentTypeNamedId`	query	string	да	Тип документа из GetDocumentTypes
`documentFunction`	query	string	да	Функция документа
`documentVersion`	query	string	да	Версия документа
`titleIndex`	query	integer	да	Номер титула
`letterId`	query	string	нет	Сообщение с титулом отправителя (для титула получателя)
`documentId`	query	string	нет	Документ с титулом отправителя
`editingSettingId`	query	string	нет	Настройка редактирования
`disableValidation`	query	boolean	нет	Отключить проверку по XSD

POST /V3/PostMessage — Отправка сообщения

В ответе: MessageId, Entities, FromBoxId, ToBoxId, MessageType. Поля Invoices, NonformalizedDocuments, Torg12Documents и т. п. устарели — используйте DocumentAttachments.

Документация: https://developer.kontur.ru/doc/diadoc.api/method?type=post&path=%2FV3%2FPostMessage

Параметр	Где	Тип	Обяз.	Описание
`operationId`	query	string	нет	ID операции для идемпотентности
`FromBoxId`	body	string	да	Ящик отправителя
`ToBoxId`	body	string	да	Ящик получателя
`DocumentAttachments[].TypeNamedId`	body	string	да	Тип документа
`DocumentAttachments[].Function`	body	string	нет	Функция документа
`DocumentAttachments[].Version`	body	string	нет	Версия документа
`DocumentAttachments[].SignedContent.Content`	body	string	да	Содержимое (base64)
`DocumentAttachments[].SignedContent.Signature`	body	string	нет	Подпись CMS SignedData в DER (base64)
`DocumentAttachments[].Metadata`	body	array	нет	Метаданные (номер, дата и т. п.)
`DocumentAttachments[].NeedRecipientSignature`	body	boolean	нет	Нужна подпись получателя
`DocumentAttachments[].CustomDocumentId`	body	string	нет	ID во внешней системе
`DocumentAttachments[].Comment`	body	string	нет	Комментарий, до 5000 символов
`ToDepartmentId`	body	string	нет	Подразделение получателя
`IsDraft`	body	boolean	нет	Сохранить черновиком
`DelaySend`	body	boolean	нет	Сохранить без отправки

POST /V3/PostMessagePatch — Дополнение к сообщению

Подписи, титулы получателя, извещения, отказы, аннулирование, согласование.

Документация: https://developer.kontur.ru/doc/diadoc.api/method?type=post&path=%2FV3%2FPostMessagePatch

Параметр	Где	Тип	Обяз.	Описание
`operationId`	query	string	нет	ID операции для идемпотентности
`BoxId`	body	string	да	Ящик с исходным сообщением
`MessageId`	body	string	да	Исходное сообщение
`RecipientTitles[].ParentEntityId`	body	string	нет	Титул отправителя, к которому относится титул получателя
`RecipientTitles[].SignedContent`	body	object	нет	Титул получателя и подпись
`Signatures`	body	array	нет	Подписи под документами (ParentEntityId, Signature)
`XmlSignatureRejections`	body	array	нет	Отказы в подписи
`RevocationRequests`	body	array	нет	Предложения об аннулировании

GET /V8/GetNewEvents — Лента событий ящика

Events[]: EventId, Message, Patch, IndexKey; TotalCount.

Документация: https://developer.kontur.ru/doc/diadoc.api/method?type=get&path=%2FV8%2FGetNewEvents

Параметр	Где	Тип	Обяз.	Описание
`boxId`	query	string	да	Ящик (GUID)
`afterIndexKey`	query	string	нет	Ключ последнего полученного события
`documentDirection`	query	array	нет	Inbound, Outbound и др., через запятую
`messageType`	query	array	нет	Тип сообщения, например Draft
`typeNamedId`	query	array	нет	Типы документов
`counteragentBoxId`	query	string	нет	Ящик контрагента
`timestampFromTicks`	query	string	нет	Начало периода (тики от 01.01.0001)
`timestampToTicks`	query	string	нет	Конец периода
`orderBy`	query	string	нет	Ascending (по умолчанию) или Descending
`limit`	query	integer	нет	Элементов на странице

GET /V3/GetDocuments — Список документов

Без содержимого. Documents[]: MessageId, EntityId, TypeNamedId, Title, DocumentDirection, CounteragentBoxId, Metadata, DocflowStatus, IndexKey; HasMoreResults.

Документация: https://developer.kontur.ru/doc/diadoc.api/method?type=get&path=%2FV3%2FGetDocuments

Параметр	Где	Тип	Обяз.	Описание
`boxId`	query	string	да	Ящик (GUID)
`filterCategory`	query	string	да	Категория фильтра (тип и статус документа, см. документацию метода)
`counteragentBoxId`	query	string	нет	Ящик контрагента
`documentNumber`	query	string	нет	Номер первичного документа
`fromDocumentDate`	query	string	нет	Дата документа с, ДД.ММ.ГГГГ
`toDocumentDate`	query	string	нет	Дата документа по
`timestampFromTicks`	query	integer	нет	Начало периода (тики)
`timestampToTicks`	query	integer	нет	Конец периода
`afterIndexKey`	query	string	нет	Ключ следующей страницы
`sortDirection`	query	string	нет	Ascending или Descending
`count`	query	integer	нет	Элементов на странице

GET /V4/GetEntityContent — Содержимое сущности

Возвращает файл документа, титула или подписи.

Документация: https://developer.kontur.ru/doc/diadoc.api/method?type=get&path=%2FV4%2FGetEntityContent

Параметр	Где	Тип	Обяз.	Описание
`boxId`	query	string	да	Ящик (GUID)
`messageId`	query	string	да	Сообщение
`entityId`	query	string	да	Сущность в сообщении

GET /GeneratePrintForm — Печатная форма

PDF; если форма ещё готовится — 200 с пустым телом и заголовком Retry-After.

Документация: https://developer.kontur.ru/doc/diadoc.api/method?type=get&path=%2FGeneratePrintForm

Параметр	Где	Тип	Обяз.	Описание
`boxId`	query	string	да	Ящик (GUID)
`messageId`	query	string	да	Сообщение
`documentId`	query	string	да	Документ в сообщении

Нюансы

В методы передавайте BoxIdGuid из GetMyOrganizations (GUID).
Электронная подпись (CMS SignedData в DER) формируется на стороне клиента; для работы с сертификатами и подписью Контур рекомендует SDK.
Время в API — тики (100-наносекундные интервалы от 00:00:00 01.01.0001).
Асинхронные методы (AcquireCounteragent, генерация печатных форм) отвечают 204 или пустым телом с Retry-After.
operationId защищает от повторной отправки: при успешном вызове с тем же ID все следующие вернут тот же результат.
Документы с тестовыми ящиками помечаются IsTest и не имеют юридической силы.
Устаревшие поля сообщения (Invoices, Torg12Documents, UniversalTransferDocumentSellerTitles и др.) заменены универсальными DocumentAttachments и RecipientTitles.

Ошибки

Код	Описание
`400`	Неверный формат данных или нет обязательных параметров
`401`	Нет заголовка Authorization или неверные авторизационные данные / ключ разработчика
`402`	У ящика закончилась подписка на API
`403`	Доступ к ящику запрещён или организация ликвидирована
`404`	Документы или объекты не найдены
`405`	Неподходящий HTTP-метод
`409`	Дубликат сообщения, запрет приёма документов (Sociability) или конфликт операции
`500`	Непредвиденная ошибка сервера

Ограничения

GetCounteragents: до 100 записей на страницу.
GetDocuments: если найдено больше 1000 документов, HasMoreResults = true — продолжайте по afterIndexKey.
Комментарий к документу — до 5000 символов, сообщение контрагенту — до 2000.

Источники

Если этого недостаточно — официальная документация: https://developer.kontur.ru/doc/diadoc-api/ JSON: https://mcp-everything.ru/api/integrations/diadoc. MCP: https://mcp-everything.ru/mcp