> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API реестра KYB: поиск и выбор компании

> Didit: поиск по реестрам компаний и получение данных нужного уровня: Lite (select), акционеры или бенефициарные владельцы. Цена зависит от страны.

## Endpoints и биллинг

Успешные автономные поиски с использованием платного источника данных о компаниях стоят **\$0.50 за запрос**, независимо от количества кандидатов. Пустые результаты, неуспешные поиски и результаты, полученные только из других источников, не тарифицируются. Последующее получение профиля оплачивается отдельно.

Получение данных продаётся в трёх уровнях детализации, по одному эндпоинту на каждый, с ценами по странам ([цены по странам](https://docs.didit.me/ru/getting-started/kyb-registry-pricing.md)):

| Эндпоинт | Что вы получаете | Цена |
| - | - | - |
| [`POST /v3/kyb/search/`](https://docs.didit.me/ru/standalone-apis/kyb-registry-search) | Компании-кандидаты: название, регистрационный номер, статус, тип | \$0.50, если возвращены результаты платного источника |
| [`POST /v3/kyb/select/`](https://docs.didit.me/ru/standalone-apis/kyb-registry-select) | **Lite**: профиль компании (идентификаторы, статус, организационно-правовая форма, дата регистрации, зарегистрированный адрес, вид деятельности, контактные данные) и должностные лица | Цена Lite: \$2.00-\$3.00 в зависимости от страны |
| [`POST /v3/kyb/shareholders/`](https://docs.didit.me/ru/standalone-apis/kyb-registry-shareholders) | Lite плюс прямые акционеры с диапазонами их долей | Цена Shareholders: \$5.00-\$22.00 в зависимости от страны |
| [`POST /v3/kyb/ubo/`](https://docs.didit.me/ru/standalone-apis/kyb-registry-ubo) | Shareholders плюс конечные бенефициарные владельцы, установленные по цепочке владения | Цена UBO: \$9.00-\$96.00 в зависимости от страны |

`select` относится к уровню Lite: именно его размещённый сценарий KYB оплачивает при проверке по реестру на уровне Lite, и он сохраняет действовавший ранее контракт. Под Европой понимаются ЕЭЗ, Соединённое Королевство и Швейцария.

Поиск Shareholders или UBO запрашивает источник данных о владении, который обслуживает этот уровень. Если этот источник сообщает, что не располагает данными о компании, поиск дополнительно запрашивает другие реестровые источники страны, поэтому компания, которой нет в источнике данных о владении, всё равно предлагается как кандидат, а не завершается ручным вводом. Кандидаты, найденные таким образом, сохраняют запрошенный вами уровень: при их получении повторно проверяется источник данных о владении, и если он по-прежнему не располагает данными о компании, доставляется и оплачивается профиль Lite с `registry_ownership_status: "not_held"`.

> [!NOTE]
>
> **Вы платите за доставленный уровень.** Каждый ответ содержит `registry_tier_requested` и `registry_tier_delivered`. Если реестры страны не содержат данных о владении или в реестре нет записи о владении для выбранной компании, результат запроса данных о владении предоставляется и оплачивается по самому высокому доступному уровню (обычно Lite), а `registry_ownership_status` указывает причину. Запрос UBO, в результате которого отчёт не называет ни одного физического лица как бенефициарного владельца, доставляется и оплачивается как Shareholders.

> [!NOTE]
>
> **Версии.** Эндпоинты Shareholders и UBO существуют только в `/v3/`. Плата за автономный поиск также применяется к `/v2/kyb/search/`; получение профиля оплачивается отдельно.

## Статус владения

`registry_ownership_status` показывает, что произошло с разделом о владении в запросе Shareholders или UBO:

| Значение | Описание |
| - | - |
| `not_requested` | Вызов был запросом на получение Lite-профиля, поэтому данные о владении не запрашивались. |
| `delivered` | Реестр предоставил данные о владении, и уровень из `registry_tier_delivered` и есть тот, за который вы платите. |
| `not_held` | Реестр владения ответил, но не содержит сведений об этой компании, поэтому записи о владении для выдачи нет: компания найдена другим реестровым источником страны. Вместо этого доставляется и оплачивается профиль Lite, с `registry_data.ownership_error: "company_not_found"`. |
| `unavailable` | Данные о владении не были предоставлены по любой другой причине: запись в реестре не называет ни одного владельца, либо реестр вообще не вернул раздел владения, либо к нему не удалось обратиться. `registry_data.ownership_error` указывает, какая именно. Вместо этого доставляется и оплачивается профиль Lite. |
| `pending` | Раздел владения ещё не получен из реестра. Ничего не списывается, а `registry_tier_delivered` равен `null`, пока раздел не получен. |

`not_held` и `unavailable` доставляются и оплачиваются как Lite, но это разные результаты: `not_held` означает, что источник данных о владении не охватывает компанию, то есть пробел в покрытии, тогда как `unavailable` означает, что данные не были предоставлены, из-за сбоя или потому что раздел в реестре остался пустым. Причину называет `registry_data.ownership_error`. Запросы, которые раньше возвращали `unavailable`, потому что реестр владения не находил компанию, теперь возвращают `not_held`; если вы реализуете ветвление по статусу, обрабатывайте оба значения одинаково как доставку Lite. Два её значения означают разное и не должны читаться как один и тот же результат:

| `ownership_error` | Описание |
| - | - |
| `no_owners_on_record` | Реестр ответил по разделу владения, и в нём не указано ни одного владельца. У этого реестра на компанию нет таблицы капитализации. |
| `ownership_section_unavailable` | Реестр не вернул раздел владения, поэтому для него ничего не было предоставлено. Список отсутствует, а не пуст: это ничего не говорит о том, кто владеет компанией. |

Раздел, который реестр не вернул, также фиксируется структурно в `registry_data.section_errors` с ключами разделов (`officers`, `shareholders`, `group_structure`) и соответствующими им статусами, которые вернул реестр:

```json theme={null}
{
  "section_errors": {
    "shareholders": {
      "status_code": 404
    }
  }
}
```

`section_errors` описывает ответ, который вы получили, а не историю, которая к нему привела. Раздел, не возвращённый при первом запросе и предоставленный при последующем проходе (см. асинхронное получение ниже), теряет свою запись, поэтому `registry_ownership_status`, `ownership_error` и `section_errors` всегда согласованы: у раздела со статусом `delivered` никогда не бывает записи, а у `no_owners_on_record` никогда не бывает записи для `shareholders`. Раздел также никогда не предоставляется частично: если реестр отдаёт первую страницу списка, а затем не отдаёт более позднюю, получение на этой попытке не завершается. Получение со статусом `pending` повторяется при следующем проходе, а новый запрос получает ответ с ошибкой недоступности реестра. Поэтому предоставленный список `officers` или акционеров всегда является полным списком, который хранит реестр. Раздел, перечисленный в `section_errors`, нужно считать данными, которые так и не были предоставлены, а не пустым результатом: пустой список `officers` или акционеров рядом с записью в `section_errors` для того же раздела ничего не говорит о компании.

### Асинхронное получение данных о владении

Некоторые реестры запрашиваются по требованию: первый запрос по компании, по поводу которой к источнику ещё не обращались, возвращается без раздела владения, пока данные получаются, и они появляются в течение пары минут. Считать это «нет данных о владении» означало бы занизить оценку компании, у которой действительно есть акционеры, поэтому запрос возвращается со статусом `pending`.

Пока получение находится в статусе `pending`, `fetch_status` тоже равен `pending`, а статус ответа равен `202 Accepted`. Didit сам повторяет запрос к разделу и завершает получение без дополнительных вызовов с вашей стороны:

* когда данные о владении поступят, акционеры и бенефициарные владельцы появятся в сохранённой проверке, `registry_tier_delivered` станет уровнем, который был предоставлен, и списание произойдёт по этому уровню;
* если раздел всё ещё пуст, когда закрывается окно повторных попыток, статус становится `unavailable`, а запрос доставляется и оплачивается как Lite.

Сохраните `request_id` и опрашивайте `GET /v3/session/{request_id}/decision/`, пока `registry_checks[0].company.fetch_status` не станет `resolved`. Не повторяйте запрос на получение, пока статус `pending`: каждый новый `POST` является отдельным запросом, который тарифицируется отдельно.

Используйте `POST /v3/kyb/search/`, чтобы найти подходящие компании. Поиск не создаёт сохранённой проверки. Параметр `tier` при поиске задаёт цепочку, по которой выполняется поиск: см. [уровень поиска](https://docs.didit.me/ru/standalone-apis/kyb-registry-search.md#уровень-поиска).

Поиск по реестрам может занимать около 90 секунд. Передайте `webhook_url`, если хотите, чтобы Didit сразу вернул ответ и уведомил ваш URL, когда кандидаты будут готовы. Обратный вызов поиска намеренно не подписывается, поэтому для этого облегчённого уведомления не нужно настраивать общий секрет.

Используйте `POST /v3/kyb/select/`, `POST /v3/kyb/shareholders/` или `POST /v3/kyb/ubo/` с возвращённым `kyb_response_id`, чтобы получить профиль на нужном уровне. Получение тарифицируется и сохраняет результат как Manual Check в Business Console.

## Типичный сценарий

1. Ищите по названию компании, регистрационному номеру и стране на том `tier`, который вы собираетесь купить (по умолчанию используется цепочка Lite `basic`; `shareholders` и `ubo` ищут по цепочке этого уровня).
2. Если `search_resolved=false`, дождитесь необязательного обратного вызова по `webhook_url` вместо опроса.
3. Покажите найденных кандидатов вашему оператору или клиенту.
4. Получите соответствующий `kyb_response_id` на нужном уровне (select для Lite, shareholders или ubo).
5. Сохраните возвращённый `request_id` и используйте его, чтобы получить сохранённый результат верификации бизнеса.

## Обратный вызов после поиска

Когда провайдер сообщает Didit, что поиск завершён, Didit отправляет один `POST` на ваш `webhook_url`:

```json theme={null}
{
  "event_id": "7f5a1c93-6a44-4f0e-9f2b-3d8a1c6f2e91",
  "event_type": "kyb.registry_search.resolved",
  "request_id": "b5ef9df5-bd9e-4d61-bbe5-5eb7a8fb6f85",
  "vendor_data": "business-123",
  "metadata": {
    "source": "onboarding"
  },
  "search_status": "resolved",
  "search_resolved": true,
  "kyb_registry": {
    "companies": [
      {
        "kyb_response_id": "kyb_resp_123",
        "name": "TESCO PLC",
        "registration_number": "00445790",
        "status": "active",
        "type": "Public Limited Company",
        "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA",
        "risk_level": null,
        "fetch_status": "pending"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "per_page": 25
    },
    "search_status": "resolved",
    "search_resolved": true
  },
  "timestamp": 1767225600,
  "created_at": 1767225600
}
```

Относитесь к обратному вызову как к уведомлению о доставке. Используйте возвращённый `kyb_response_id` в запросах `POST /v3/kyb/select/`, `POST /v3/kyb/shareholders/` или `POST /v3/kyb/ubo/`, чтобы получить профиль из реестра. Этот запрос тарифицируется.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.