Перейти к основному содержимому

AcquireCounteragent (V3)

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

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

POST /V3/AcquireCounteragent

Параметры запроса

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

Заголовки запроса

Тело запроса

Тело запроса должно содержать структуру 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) — выполняет поиск контрагентов по указанным параметрам

Оцените материал страницы

Нашли ошибку или столкнулись с проблемой?

СКБ Контурс 1988 года