AcquireCounteragent¶

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

Версии метода:

v1.21:
- поддерживает отправку приглашений с вложением;
- позволяет указать контрагента по идентификатору организации или по ИНН.
v1.20 — устаревшая версия.

v1.21¶

POST /V2/AcquireCounteragent¶

Query Parameters:

myOrgId – идентификатор организации, от имени которой производится инициация отношения партнерства.
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;
}

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

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

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

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

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

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

Status Codes:

200 OK – операция успешно завершена.
400 Bad Request – данные в запросе имеют неверный формат или отсутствуют обязательные параметры.
401 Unauthorized – в запросе отсутствует HTTP-заголовок Authorization или в этом заголовке содержатся некорректные авторизационные данные.
402 Payment Required – у организации с указанным идентификатором myOrgId закончилась подписка на 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 можно узнать результат обработки запроса.

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

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

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

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

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

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

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

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

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

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

v1.20¶

POST /AcquireCounteragent¶

Query Parameters:

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

Request Headers:

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

Status Codes:

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

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

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

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

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

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

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