GetCounteragents (V3)

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

GET /V3/GetCounteragents

Query Parameters:

• myBoxId – идентификатор ящика организации, для которой осуществляется поиск контрагентов.

• counteragentStatus – статус контрагента, используется для фильтрации результатов поиска. Необязательный параметр.

• afterIndexKey – ключ для постраничного получения списка найденных контрагентов, указывающий на начало очередной страницы. Ключ может содержать недопустимые символы, поэтому должен быть закодирован в URL-формат. Необязательный параметр.

• query – текстовая строка для поиска организации по краткому или полному наименованию ящика контрагента или ИНН. Нельзя указывать одновременно с afterIndexKey.

• pageSize – максимальное количество контрагентов в ответе. Может принимать значения от 1 до 100, по умолчанию равен 100. Необязательный параметр.

Request Headers:

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

Status Codes:

• 200 OK – операция успешно завершена.

• 400 Bad Request – данные в запросе имеют неверный формат или отсутствуют обязательные параметры.

• 401 Unauthorized – в запросе отсутствует HTTP-заголовок Authorization или в этом заголовке содержатся некорректные авторизационные данные.

• 402 Payment Required – у указанного ящика закончилась подписка на API.

• 403 Forbidden – доступ к списку контрагентов указанной организации с предоставленным авторизационным токеном запрещен.

• 405 Method Not Allowed – используется неподходящий HTTP-метод.

• 500 Internal Server Error – при обработке запроса возникла непредвиденная ошибка.

Response Body:

Тело ответа содержит список контрагентов организации myBoxId, находящихся в статусе counteragentStatus, представленный структурой CounteragentList.

Метод доступен только сотрудникам с доступом к ящику.

Параметр counteragentStatus предназначен для фильтрации результатов поиска. Если параметр counteragentStatus не задан, метод вернет весь список контрагентов. Значения статусов контрагента описаны в перечислении CounteragentStatus. В качестве параметра counteragentStatus можно передавать следующие значения:

• IsMyCounteragent,

• InvitesMe,

• IsInvitedByMe,

• Rejected.

Во вложенной структуре Counteragent.Organization поле Departments будет пустым.

Список контрагентов Counteragents в ответе CounteragentList может содержать не больше 100 элементов. Поэтому:

• Если найденных контрагентов меньше 100, то метод вернет их полностью.

• Если найденных контрагентов больше 100, то в ответе Counteragents вернутся только первые 100 элементов. При этом параметр TotalCount будет содержать общее количество найденных контрагентов, а параметр TotalCountType покажет, точно ли посчитано значение TotalCount или подсчет был ограничен.

  В этом случае получить весь список найденных контрагентов можно постранично. Для этого вызывайте метод GetCounteragents с теми же параметрами запроса и с указанием параметра afterIndexKey до тех пор, пока список контрагентов не будет вычитан полностью. В качестве параметра afterIndexKey нужно указывать ключ контрагента из поля Counteragent.IndexKey, предварительно закодировав его в URL-формат.

В зависимости от значения параметра afterIndexKey метод работает следующим образом:

• Если в запросе отсутствует параметр afterIndexKey, то метод вернет начало списка найденных контрагентов.

• Если в запросе указан параметр afterIndexKey, то метод вернет список контрагентов, следующих за контрагентом с ключом afterIndexKey; контрагент с ключом afterIndexKey в этот список не попадает.

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

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

GET /V3/GetCounteragents?myBoxId={{myBoxId}}&counteragentStatus=IsMyCounteragent&query=Ромашка HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Accept: application/json; charset=utf-8

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

{
    "TotalCount": 1,
    "Counteragents": [
        {
            "LastEventTimestamp": "2024-08-06T12:36:38.8979088Z",
            "IndexKey": "40623A7CD898B2EA038D201F602A644F91B1B7AAD54CFAF3",
            "Organization": {
                "OrgIdGuid": "72c3b5bf-3a9f-4fb5-a3ef-112cb2b3a8dc",
                "OrgId": "72c3b5bf-3a9f-4fb5-a3ef-112cb2b3a8dc",
                "Inn": "9147414342",
                "Kpp": "757645784",
                "FullName": "Ромашка",
                "ShortName": "Ромашка",
                "JoinedDiadocTreaty": true,
                "Boxes": [
                    {
                        "BoxId": "2a208d032a604f6491b1b7aad54cfaf3@diadoc.ru",
                        "BoxIdGuid": "2a208d03-2a60-4f64-91b1-b7aad54cfaf3",
                        "Title": "Ромашка",
                        "InvoiceFormatVersion": "v5_02",
                        "EncryptedDocumentsAllowed": false
                    }
                ],
                "Ogrn": "9130523523154",
                "FnsParticipantId": "2BM-9147414342-757645784-202407101104400484330",
                "Address": {
                    "RussianAddress": {
                        "ZipCode": "620142",
                        "Region": "66",
                        "City": "Екатеринбург",
                        "Street": "Сажинская",
                        "Building": "11"
                    },
                    "AddressCode": ""
                },
                "Departments": [],
                "IfnsCode": "6174",
                "IsPilot": false,
                "IsActive": true,
                "IsTest": false,
                "IsBranch": false,
                "IsRoaming": false,
                "IsEmployee": false,
                "InvitationCount": 0,
                "SearchCount": 0,
                "Sociability": "AllOrganizations",
                "IsForeign": false,
                "HasCertificateToSign": true
            },
            "CurrentStatus": "IsMyCounteragent",
            "LastEventTimestampTicks": 638585445988979088,
            "MessageToCounteragent": "Примите приглашение к сотрудничеству",
            "InvitationDocumentId": {
                "MessageId": "215a68d5-28a0-4c6a-b9ec-cdba1530fd49",
                "EntityId": "ad810ad2-8d4f-4fd9-9321-5359dfc0a37a"
            },
            "CounteragentGroupId": "ecd591dd-b56f-4178-ab4a-8a5532f231f7"
        }
    ],
    "TotalCountType": "Equal"
}

---

См. также

Инструкции:

• Контрагенты

Методы для работы с контрагентами:

• AcquireCounteragent (V3) — отправляет контрагенту приглашение к партнерским отношениям

• AcquireCounteragentResult (V2) — возвращает результат приглашения контрагента к партнерским отношениям

• BreakWithCounteragent (V2) — разрывает партнерские отношения с контрагентом

• GetCounteragent (V3) — возвращает данные контрагента по указанному идентификатору

• GetCounteragentCertificates (V2) — возвращает список сертификатов контрагента

• GetCounteragents (V3) — выполняет поиск контрагентов по указанным параметрам

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

• GetCounteragents

• GetCounteragents (V2)