.. _Integration_IntegrationApi_WorkingWithContractors_QueryingContractors:

Запрос данных контрагентов
##########################

| Запрос: ``POST /v2/contractors``
| HTTP-заголовки:

.. code-block::

    Authorization: Bearer access_token
    Content-Type: application/json
    Accept: application/json

Тело запроса:

.. code-block:: JSON

    {
        "OperatorIds": [                        // фильтр по идентификаторам операторов ЭДО или EDI-провайдеров
            "string"
        ],
        "Boxes": [                              // фильтр по идентификаторам ящиков контрагентов
            {
                "BoxId": "string",              // идентификатор ящика
                "DepartmentId": "string"        // идентификатор подразделения
            }
        ],
        "FnsIds": [                             // фильтр по ФНС-идентификаторам контрагентов
            "string"
        ],
        "Contractors": [                        // фильтр по ИНН/КПП контрагентов
            {
                "Inn": "string",                // ИНН контрагента
                "Kpp": "string"                 // КПП контрагента
            }
        ],
        "IncludeAutoCreatedContractors": false  // признак того, что в ответ должны быть включены контрагенты, созданные в результате обработки документов
    }

Описание запроса
****************

Запрос позволяет получить данные контрагентов. 

Поле ``OperatorIds`` позволяет отфильтровать результаты по операторам ЭДО или EDI-провайдерам.

Поле ``Boxes`` позволяет отфильтровать результаты по идентификаторам ящиков и подразделений контрагентов.
Идентификатор подразделения нужно указывать для получения данных по контрагенту-подразделению, а не по головной организации.

Поле ``FnsIds`` позволяет отфильтровать результаты по ФНС-идентификаторам контрагентов.

Поле ``Contractors`` позволяет отфильтровать результаты по ИНН/КПП контрагентов.

Если поле ``IncludeAutoCreatedContractors`` установлено в ``true``, то в ответ включаются контрагенты, созданные в результате обработки документов.
У таких контрагентов нет статусов отношений партнерства: эти статусы появляются в результате обмена приглашениями.
Если это поле установлено в ``false``, то такие контрагенты отбрасываются.

.. note::
    У контрагентов-подразделений нет статусов отношений партнерства, т. к. отношения устанавливаются между головными организациями.
    Для запроса данных контрагентов-подразделений поле ``IncludeAutoCreatedContractors`` должно быть установлено в ``true``.

.. warning::
    Запрос данных контрагентов не предназначен для использования без фильтров.
    Попытка вызова этого запроса без фильтров на большом количестве контрагентов может привести к существенному увеличению времени выполнения запроса.
    
Ответ на запрос
***************

Ответ на запрос содержит коллекцию элементов вида:

.. code-block:: JSON

    {
        "OperatorId": "string",
        "BoxId": "string",                              // идентификатор ящика контрагента
        "DepartmentId": "string",                       // идентификатор подразделения
        "FnsId": "string",                              // ФНС-идентификатор контрагента
        "NameFull": "string",                           // полное наименование контрагента
        "NameShort": "string",                          // краткое наименование контрагента
        "Inn": "string",                                // ИНН контрагента
        "Kpp": "string",                                // КПП контрагента
        "Region": "string",                             // регион
        "City": "string",                               // город
        "Address": "string",                            // адрес
        "UpdateDateTime": "YYYY-MM-DDThh:mm:ss.fffZ",   // дата и время предыдущего обновления данных контрагента
        "Statuses": [                                   // статусы отношений партнерства с контрагентом
        ]
    }

В поле ``OperatorId`` указывается код оператора, к которому привязаны данные контрагента.

Идентификатор подразделения заполняется только для контрагентов-подразделений.

КПП заполняется только для контрагентов-юридических лиц.

В полях ``Region``, ``City`` и ``Address`` хранится адресная информация. Ее полнота и формат не регламентированы.
Внешняя система не должна рассчитывать на регулярную структуру этих данных.

В поле ``UpdateDateTime`` находится дата и время предыдущего обновления данных контрагента. Это момент времени, на который данные были актуальны.

Статусы отношений партнерства
=============================

Коллекция ``Statuses`` содержит статусы отношений партнерства с контрагентом.

Структура данных статуса:

.. code-block:: JSON

    {
        "Id": 0,                // идентификатор  статуса
        "BoxId": "string",      // идентификатор "нашего" ящика, с которым производился обмен приглашениями
        "StatusCode": "string", // код статуса
        "Comment": "string"     // комментарий к статусу
    }

Статусы отсортированы по возрастанию идентификатора и передаются в разрезе "наших" ящиков, т. е. ящиков, 
:ref:`настроенных <Setup_Integration_BasicSetup_Operators>` в Продукте.
Статус с максимальным значением идентификатора является актуальным статусом отношений партнерства.

Возможные статусы отношений партнерства:

* "Приглашение отправлено" (код статуса ``CS``);
* "Приглашение получено" (код статуса ``CI``);
* "Отношения партнерства установлены" (код статуса ``CV``);
* "Отношение партнерства не установлены" (код статуса ``CX``).

| См. также:
| :ref:`Integration_IntegrationApi_Helpers_WorkingWithReferences_GettingStatusesReference`