Skip to content

Latest commit

 

History

History
107 lines (70 loc) · 10.3 KB

AcquireCounteragent.rst

File metadata and controls

107 lines (70 loc) · 10.3 KB
Raw

AcquireCounteragent

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

.. http:post:: /V3/AcquireCounteragent

        :queryparam myBoxId: идентификатор :doc:`ящика <../../entities/box>` организации, от имени которой производится инициация отношения партнерства.
        :queryparam myDepartmentId: идентификатор подразделения, от имени которого производится инициация отношения партнерства. Необязательный параметр.

        :requestheader Authorization: данные, необходимые для :doc:`авторизации <../Authorization>`.

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

                .. code-block:: protobuf

                    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];
                    }

                ..

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

                   - ``SignedContent`` — содержимое файла документа с электронной подписью, представленное структурой :doc:`../../proto/SignedContent`.
                   - ``FileName`` — имя файла.
                   - ``SignatureRequested`` — флаг, указывающий, что от контрагента требуется ответная подпись.

                - ``BoxId`` — идентификатор ящика организации контрагента.

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

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

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

        :statuscode 200: операция успешно завершена.
        :statuscode 400: данные в запросе имеют неверный формат или отсутствуют обязательные параметры.
        :statuscode 401: в запросе отсутствует HTTP-заголовок ``Authorization`` или в этом заголовке содержатся некорректные авторизационные данные.
        :statuscode 402: у организации с указанным идентификатором ``myBoxId`` закончилась подписка на API.
        :statuscode 403: доступ к ящику с предоставленным авторизационным токеном запрещен, или у пользователя недостаточно прав для доступа ко всем документам организации, или у пользователя нет права работать со списком контрагентов (см. :doc:`OrganizationUserPermissions.CanManageCounteragents <../proto/OrganizationUserPermissions>`).
        :statuscode 404: в указанном ящике нет документов с указанными идентификаторами.
        :statuscode 405: используется неподходящий HTTP-метод.
        :statuscode 409: требуется заявка на роуминг для отправки приглашения роуминговому контрагенту (подробнее https://www.diadoc.ru/roaming).
        :statuscode 500: при обработке запроса возникла непредвиденная ошибка.

        :response Body: Тело ответа содержит идентификатор операции ``taskId`` в структуре :doc:`../proto/AsyncMethodResult`. По этому идентификатору с помощью метода :doc:`AcquireCounteragentResult` можно узнать результат обработки запроса.

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

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

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

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

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

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

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

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

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

.. literalinclude:: ../include/acquireCounteragent_query.txt

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

.. literalinclude:: ../include/acquireCounteragent_body.txt
        :language: json

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

.. literalinclude:: ../include/acquireCounteragent_resp.txt
        :language: json

См. также

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