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

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

Формализованный документ отправляется как 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"'"}
    }]
  }'
```

## Базовые 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 /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 | нет | Сохранить без отправки |

## Нюансы

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