AcquireCounteragent (V3)

Отправляет контрагенту приглашение к партнерским отношениям.

С помощью этого метода можно добавить организацию в список активных контрагентов.

POST /V3/AcquireCounteragent

Query Parameters:

myBoxId – идентификатор ящика организации, от имени которой производится инициация отношения партнерства.
myDepartmentId – идентификатор подразделения, от имени которого производится инициация отношения партнерства. Необязательный параметр.

Request Headers:

Authorization – данные, необходимые для авторизации.

Request Body:

Тело запроса должно содержать структуру AcquireCounteragentRequest:

message AcquireCounteragentRequest {
    optional string OrgId = 1;
    optional string Inn = 2;
    optional string MessageToCounteragent = 3;
    optional InvitationDocument InvitationDocument = 4;
    optional string BoxId = 5;
}

message InvitationDocument {
    required Events.SignedContent SignedContent = 1;
    required string FileName = 2;
    optional bool SignatureRequested = 3 [default = false];
    optional string Type = 4;
}

OrgId — идентификатор организации контрагента.
Inn — ИНН организации контрагента.
MessageToCounteragent — текст сообщения для контрагента. Длина не более 2000 символов.
InvitationDocument — вложенный файл, представленный структурой InvitationDocument с полями:
- SignedContent — содержимое файла документа с электронной подписью, представленное структурой SignedContent.
- FileName — имя файла.
- SignatureRequested — признак того, что от контрагента требуется ответная подпись.
- Type — тип приглашения. Принимает значение TrustConnectionRequest.
BoxId — идентификатор ящика организации контрагента.

При заполнении структуры руководствуйтесь следующими рекомендациями:

Если организация контрагента зарегистрирована в Диадоке, укажите параметры BoxId или OrgId контрагента — получить их можно с помощью метода GetOrganizationsByInnKpp. Рекомендуем указывать параметр BoxId.

Если организация контрагента не зарегистрирована в Диадоке и у нее нет параметров BoxId и OrgId, укажите параметр Inn. Если организация с таким ИНН существует в ЕГРЮЛ, то для нее в Диадоке будет создан ящик. В этот ящик будет помещено приглашение к партнерству. Организация получит приглашение, когда сотрудник организации с сертификатом КЭП войдет в Диадок. Таким способом можно отправить запрос только в головную организацию: в филиал организации отправить запрос нельзя.

Если для поиска организации контрагента вы указываете ИНН, и при этом будет найдено несколько организаций с таким ИНН, то приглашение будет отправлено в организацию, созданную последней.

Status Codes:

200 OK – операция успешно завершена.
400 Bad Request – данные в запросе имеют неверный формат или отсутствуют обязательные параметры.
401 Unauthorized – в запросе отсутствует HTTP-заголовок Authorization или в этом заголовке содержатся некорректные авторизационные данные.
402 Payment Required – у указанного ящика закончилась подписка на API.
403 Forbidden – доступ к ящику с предоставленным авторизационным токеном запрещен, или у пользователя недостаточно прав для доступа ко всем документам организации, или у пользователя нет права работать со списком контрагентов (см. OrganizationUserPermissions.CanManageCounteragents).
404 Not Found – в указанном ящике нет документов с указанными идентификаторами.
405 Method Not Allowed – используется неподходящий HTTP-метод.
409 Conflict – требуется заявка на роуминг для отправки приглашения роуминговому контрагенту (подробнее https://www.diadoc.ru/roaming).
500 Internal Server Error – при обработке запроса возникла непредвиденная ошибка.

Response Body:

Тело ответа содержит идентификатор операции taskId в структуре AsyncMethodResult. По этому идентификатору с помощью метода AcquireCounteragentResult (V2) можно узнать результат обработки запроса.

Метод доступен только сотрудникам с доступом к ящику и разрешением OrganizationUserPermissions.CanManageCounteragents, которое позволяет видеть списки контрагентов и работать с ними.

В случае с другим оператором ЭДО используйте метод GetRoamingOperators, чтобы узнать, поддерживает ли он автоматическую обработку приглашений.

Отправка приглашений с вложением роуминговым контрагентам невозможна. В случае, если вы отправляете роуминговому контрагенту приглашение с вложенным документом, то такой документ не будет отправлен, а контрагент его не получит, — при этом метод не сообщит об ошибке.

Метод работает по следующим правилам:

Если между организациями myBoxId и контрагентом нет действующего отношения партнерства, то от имени организации myBoxId будет отправлен запрос на установление отношения партнерства в адрес организации контрагента. Контрагент перейдет в статус IsInvitedByMe.

Если организация контрагента отправила запрос на установление отношения партнерства к организации myBoxId (то есть контрагент находится в статусе InvitesMe), то этот запрос будет подтвержден, и между организациями myBoxId и контрагентом установится действующее отношение партнерства. Контрагент перейдет в статус IsMyCounteragent.

Принять приглашение без вложенного документа или приглашение со вложенным документом, не требующим подписи, можно отправкой взаимного запроса без вложенного документа.

Нельзя принять приглашение с помощью взаимного запроса со вложенным документом.

Нельзя принять приглашение с вложением, требующим подписи, с помощью взаимного запроса. Для принятия такого приглашения через API нужно подписать вложенный документ с помощью метода PostMessagePatch (V3) или PostMessagePatch (V4). После подписания вложенного документа будет установлено отношение партнерства.

Если между организациями myBoxId и контрагентом отношение партнерства уже установлено или есть исходящий запрос от организации myBoxId к организации контрагента, то в результате выполнения метода ничего не произойдет.

Примеры использования

Пример HTTP-запроса:

POST /V3/AcquireCounteragent?myBoxId={{boxId}} HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}

Пример тела запроса:

{
    "BoxId": "{{counteragentBoxId}}",
    "MessageToCounteragent": "Примите приглашение к сотрудничеству",
    "InvitationDocument": {
        "FileName": "invitation",
        "SignedContent": {
            "Content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0...NC50Ls+",        // содержимое XML-файла в кодировке base-64
            "Signature": "MIIN5QYJKoZIhvcNAQcCoIIN1jCCDdIA...kA9MJfsplqgW",        // содержимое файла подписи в кодировке base-64
        }
    }
}

Пример тела ответа:

{
    "TaskId": "997818e1-9420-4f8f-857f-c86fb070d0a7"
}

См. также

Инструкции:

Контрагенты

Методы для работы с контрагентами:

AcquireCounteragent (V3) — отправляет контрагенту приглашение к партнерским отношениям
AcquireCounteragentResult (V2) — возвращает результат приглашения контрагента к партнерским отношениям
BreakWithCounteragent (V2) — разрывает партнерские отношения с контрагентом
GetCounteragent (V3) — возвращает данные контрагента по указанному идентификатору
GetCounteragentCertificates (V2) — возвращает список сертификатов контрагента
GetCounteragents (V3) — выполняет поиск контрагентов по указанным параметрам

Устаревшие версии метода: