GetCounteragents (V3)
Выполняет поиск контрагентов по указанным параметрам.
GET /V3/GetCounteragents
Параметры запроса
myBoxId— идентификатор ящика организации, для которой осуществляется поиск контрагентов, в формате GUID.counteragentStatus— статус контрагента, используется для фильтрации результатов поиска. Необязательный параметр.afterIndexKey— ключ для постраничного получения списка найденных контрагентов, указывающий на начало очередной страницы. Ключ может содержать недопустимые символы, поэтому должен быть закодирован в URL-формат. Необязательный параметр.query— текстовая строка для поиска организации по краткому или полному наименованию ящика контрагента или ИНН. Нельзя указывать одновременно сafterIndexKey.pageSize— максимальное количество контрагентов в ответе. Принимает значения от 1 до 100, по умолчанию равен 100. Необязательный параметр.
Заголовки запроса
Authorization— данные, необходимые для авторизации.
Коды ответа
200— операция успешно завершена.400— данные в запросе имеют неверный формат или отсутствуют обязательные параметры.401— в запросе отсутствует HTTP-заголовокAuthorizationили в этом заголовке содержатся некорректные авторизационные данные.402— у указанного ящика закончилась подписка на API.403— доступ к списку контрагентов указанной организации с предоставленным авторизационным токеном запрещен.405— используется неподходящий HTTP-метод.429— превышено ограничение на количество запросов в единицу времени.500— при обработке запроса возникла непредвиденная ошибка.
Тело ответа
Тело ответа содержит список контрагентов организации 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
Пример тела ответа:
{
"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,
"OrganizationType": "Juridical",
"IsOwner": false,
"Comment": ""
},
"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 (V3) — возвращает результат приглашения контрагента к партнерским отношениям
- BreakWithCounteragent (V2) — разрывает партнерские отношения с контрагентом
- GetCounteragents (V3) — выполняет поиск контрагентов по указанным параметрам