# Контур.Диадок API: Пригласить контрагента к обмену

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

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

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

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

## Нюансы

- В методы передавайте `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/otpravit-upd-ili-drugoy-formalizovannyy.md)
- [Забирать входящие документы](https://mcp-everything.ru/integrations/diadoc/scenarios/zabirat-vhodyaschie-dokumenty.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