Перейти к основному содержимому

GetCounteragents (V3)

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

GET /V3/GetCounteragents

Параметры запроса

  • myBoxId — идентификатор ящика организации, для которой осуществляется поиск контрагентов, в формате GUID.
  • counteragentStatus — статус контрагента, используется для фильтрации результатов поиска. Необязательный параметр.
  • afterIndexKey — ключ для постраничного получения списка найденных контрагентов, указывающий на начало очередной страницы. Ключ может содержать недопустимые символы, поэтому должен быть закодирован в URL-формат. Необязательный параметр.
  • query — текстовая строка для поиска организации по краткому или полному наименованию ящика контрагента или ИНН. Нельзя указывать одновременно с afterIndexKey.
  • pageSize — максимальное количество контрагентов в ответе. Принимает значения от 1 до 100, по умолчанию равен 100. Необязательный параметр.

Заголовки запроса

Коды ответа

  • 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) — выполняет поиск контрагентов по указанным параметрам

Оцените материал страницы

Нашли ошибку или столкнулись с проблемой?

СКБ Контурс 1988 года