AcquireCounteragent (V3)
Отправляет контрагенту приглашение к партнерским отношениям.
С помощью этого метода можно добавить организацию в список контрагентов.
POST /V3/AcquireCounteragent
Параметры запроса
myBoxId— идентификатор ящика организации, от имени которой производится инициация отношения партнерства, в формате GUID.myDepartmentId— идентификатор подразделения, от имени которого производится инициация отношения партнерства. Необязательный параметр.
Заголовки запроса
Authorization— данные, необходимые для авторизации.
Тело запроса
Тело запроса должно содержать структуру 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. Если организация с таким ИНН существует в ЕГРЮЛ, то для нее в Диадоке будет создан ящик. В этот ящик будет помещено приглашение к партнерству. Организация получит приглашение, когда сотрудник организации с сертификатом КЭП войдет в Диадок. Таким способом можно отправить запрос только в головную организацию: в филиал организации отправить запрос нельзя.
Если для поиска организации контрагента вы указываете ИНН, и при этом будет найдено несколько организаций с таким ИНН, то приглашение будет отправлено в организацию, созданную последней.
Коды ответа
200— операция успешно завершена.400— данные в запросе имеют неверный формат или отсутствуют обязательные параметры.401— в запросе отсутствует HTTP-заголовокAuthorizationили в этом заголовке содержатся некорректные авторизационные данные.402— у указанного ящика закончилась подписка на API.403— доступ к ящику с предоставленным авторизационным токеном запрещен, или у пользователя недостаточно прав для доступа ко всем документам организации, или у пользователя нет права работать со списком контрагентов (см. OrganizationUserPermissions.CanManageCounteragents), или в запросе передано вложениеInvitationDocument, а у пользователя нет права создавать и редактировать документы.404— в указанном ящике нет документов с указанными идентификаторами.405— используется неподходящий HTTP-метод.409— требуется заявка на роуминг для отправки приглашения роуминговому контрагенту (подробнее https://www.diadoc.ru/roaming).415— тип содержимого запроса не поддерживается.429— превышено ограничение на количество запросов в единицу времени.500— при обработке запроса возникла непредвиденная ошибка.
Тело ответа
Тело ответа содержит идентификатор операции taskId в структуре AsyncMethodResult. По этому идентификатору с помощью метода AcquireCounteragentResult (V3) можно узнать результат обработки запроса.
Метод доступен только сотрудникам с доступом к ящику и разрешением OrganizationUserPermissions.CanManageCounteragents, которое позволяет видеть списки контрагентов и работать с ними.
В случае с другим оператором ЭДО используйте метод GetRoamingOperators, чтобы узнать, поддерживает ли он автоматическую обработку приглашений.
Приглашение физическому лицу отправляется без вложения. Это значит, что при отправке приглашения организации со свойством OrganizationType = PhysicalPerson вложение из поля запроса AcquireCounteragentRequest.InvitationDocument не будет отправлено. При этом метод будет выполнен успешно и не вернет ошибок, а поле ответа AcquireCounteragentResult.InvitationDocumentId будет пустым. Приглашение, отправленное физическому лицу, будет принято автоматически.
Метод работает по следующим правилам:
- Нельзя отправить или принять приглашение, если одна из организаций отключена от оператора ЭДО и у нее заполнено поле
DisconnectionFromOperatorDateв структуре Organization. В этом случае метод вернет ошибку. - Если между организациями
myBoxIdи контрагентом нет действующего отношения партнерства, то от имени организацииmyBoxIdбудет отправлен запрос на установление отношения партнерства в адрес организации контрагента. Дальнейшая обработка зависит от свойстваSociabilityу ящика контрагента:- Если
Sociability = AllOrganizations, то приглашение без запроса подписи, независимо от наличия вложения, принимается автоматически. Контрагент сразу появится в списке контрагентов в статусеIsMyCounteragent. При наличии вложения контрагент также получит документ типаTrustConnectionRequestсо статусом «Документооборот завершен». - Если
Sociability = CounteragentsOnlyили приглашение содержит запрос подписи и вложение, то контрагент сначала появится в списке контрагентов в статусеIsInvitedByMe. После того, как он примет приглашение, его статус изменится наIsMyCounteragent.
- Если
- Если организация контрагента отправила запрос на установление отношения партнерства к организации
myBoxId(то есть контрагент находится в статусеInvitesMe), то этот запрос будет подтвержден, и между организациямиmyBoxIdи контрагентом установится действующее отношение партнерства. Контрагент перейдет в статусIsMyCounteragent.- Принять приглашение без вложенного документа или приглашение со вложенным документом, не требующим подписи, можно отправкой взаимного запроса без вложенного документа.
- Нельзя принять приглашение с помощью взаимного запроса со вложенным документом.
- Нельзя принять приглашение с вложением, требующим подписи, с помощью взаимного запроса. Для принятия такого приглашения через API нужно подписать вложенный документ с помощью метода PostMessagePatch (V4). После подписания вложенного документа будет установлено отношение партнерства.
- Если между организациями
myBoxIdи контрагентом отношение партнерства уже установлено или есть исходящий запрос от организацииmyBoxIdк организации контрагента, то в результате выполнения метода ничего не произойдет. - Если при отправке приглашения в адрес ящика роумингового контрагента добавить вложенный файл, то получателю будет доставлено только приглашение без прилагаемого документа, а запрос завершится успешно.
Значение свойства Sociability у ящика роумингового контрагента Диадок получает из базы ФНС и обновляет раз в сутки.
Примеры использования
Пример HTTP-запроса:
POST /V3/AcquireCounteragent?myBoxId={{boxId}} HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Content-Type: application/json; charset=utf-8
Accept: application/json
Пример тела запроса:
{
"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 (V3) — возвращает результат приглашения контрагента к партнерским отношениям
- BreakWithCounteragent (V2) — разрывает партнерские отношения с контрагентом
- GetCounteragents (V3) — выполняет поиск контрагентов по указанным параметрам