---
slug: "diadoc"
name: "Контур.Диадок API"
vendor: "СКБ Контур"
industry: "accounting"
docsUrl: "https://developer.kontur.ru/doc/diadoc-api/"
version: 1
updatedAt: "2026-10-25"
---

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

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

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

## Охват

Есть:

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

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

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

## Сценарии

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

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

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

```bash
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"
```

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

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

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

```bash
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-титул отправителя с электронной подписью.

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

```bash
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"'"}
    }]
  }'
```

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

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

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

```bash
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
```

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

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

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

```bash
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

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

```bash
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.

## Источники

- [Diadoc API — справочник методов](https://developer.kontur.ru/doc/diadoc.api)
- [Документация Диадок API](https://developer.kontur.ru/doc/diadoc-api/)
- [Быстрый старт](https://developer.kontur.ru/doc/diadoc-api/howtostart/quickstart.html)
- [Авторизация](https://developer.kontur.ru/doc/diadoc-api/Authorization.html)
- [Варианты интеграции и SDK](https://developer.kontur.ru/doc/diadoc-api/howtostart/integrationChoise.html)
- [Документооборот](https://developer.kontur.ru/doc/diadoc-api/docflows/index.html)

---

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