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

Сценарий из mcp-everything. Актуально на 2026-10-25.

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

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

## Базовые 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}}
```

## Методы сценария

### 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 /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 | да | Сущность в сообщении |

## Нюансы

- В методы передавайте `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`.

## Другие сценарии

- [Войти и найти свой ящик](https://mcp-everything.ru/integrations/diadoc/scenarios/voyti-i-nayti-svoy-yaschik.md)
- [Пригласить контрагента к обмену](https://mcp-everything.ru/integrations/diadoc/scenarios/priglasit-kontragenta-k-obmenu.md)
- [Отправить УПД или другой формализованный документ](https://mcp-everything.ru/integrations/diadoc/scenarios/otpravit-upd-ili-drugoy-formalizovannyy.md)
- [Подписать входящий документ](https://mcp-everything.ru/integrations/diadoc/scenarios/podpisat-vhodyaschiy-dokument.md)
- [Получить печатную форму PDF](https://mcp-everything.ru/integrations/diadoc/scenarios/poluchit-pechatnuyu-formu-pdf.md)

---

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