# AI-BELARUS

> Справочник субъектов хозяйствования Беларуси по данным государственных реестров:
> у каждого сведения — держатель, момент снятия и sha256 сырого ответа. Живая проверка
> контрагента по УНП — ответ реестра в момент запроса. Служба не даёт оценок и
> рекомендаций: решение принимает человек или вызывающая машина.

Два режима, и их не надо путать:

1. Собранное (мгновенно, без обращения к реестру): карточка по УНП, поиск по УНП или
   названию, постоянная страница организации. «Нет в нашей базе» значит только это,
   а не «лица не существует».
2. Живая проверка: по девятизначному УНП служба спрашивает Государственный реестр
   плательщиков (МНС) и, если вид субъекта установлен по ЕГР, отдаёт наименование,
   адрес, состояние, дату постановки на учёт и налоговый орган юридического лица.
   У ответа три исхода: да, нет, не_установлено; третий никогда не сводится к первым
   двум. Поле `ответ.закупки` — участие юридического лица в госзакупках по собранным
   пакетам ГИАС (роли заказчика, участника, победителя); `всего_записей = 0` значит «в
   нашей базе нет», а не «не участвовал». Поле `ответ.банкротство` — дела по Единому
   реестру сведений о банкротстве, снятые в момент запроса: исход да | нет |
   не_установлено, стадия словами реестра, номер дела, управляющий; наличие дела не
   есть вывод «не действует». Поле `ответ.недопуск_к_закупкам` — список поставщиков,
   временно не допускаемых к госзакупкам (ГИАС, ведёт МАРТ). Поле
   `ответ.плановые_проверки` — планы выборочных проверок КГК; план — не нарушение и не
   оценка.

Чего служба не делает: об индивидуальных предпринимателях показывает только ФИО и
только тому, кто уже знает УНП (решение оператора OD-IP-NAME-PUBLIC-REGISTRY); по имени
предприниматель не ищется, открытой страницы у него нет, остальные поля закрыты. Не ищет
по названию в государственном реестре — реестр отвечает только по УНП, по названию
служба ищет в своей базе. Не даёт оценок, баллов и рекомендаций.

## Для агентов ИИ

- MCP (streamable HTTP, без ключа): `https://ai-belarus.by/mcp` — инструменты
  `lookup_company` (карточка по УНП из собранного), `search_companies` (поиск юрлица по
  названию или УНП), `check_counterparty` (живой ответ реестра). Реестр MCP:
  `by.ai-belarus/registry`. Те же ворота права, что у открытого API.
- Действия GPT и иные клиенты OpenAPI: [спецификация открытых путей](https://ai-belarus.by/openapi-gpt.json).

## Точки входа

- [Карточка по УНП](https://ai-belarus.by/v1/public/by-unp/{unp}): GET, без ключа.
  Собранное: утверждения с держателем, моментом, sha256 и `attribution`; удержанное
  названо в `withheld` с причиной.
- [Страница организации](https://ai-belarus.by/org/{unp}): постоянный адрес, HTML с
  разметкой schema.org (Organization, WebPage), собран сервером; только юридические лица.
- [Поиск](https://ai-belarus.by/v1/public/search?q=...): по УНП или названию среди
  собранного; по названию находятся только юридические лица.
- [Живая проверка](https://ai-belarus.by/v1/counterparty/{unp}?name=...): GET, без
  ключа для юридических лиц; `name` — наименование из ваших документов для сверки.
  Ответ application/json, ключи русские, словарь ниже.
- [Словарь ответа](https://ai-belarus.by/v1/meta/vocabulary): поля, три исхода,
  измеренные состояния реестра.
- [Охват и права](https://ai-belarus.by/v1/meta/coverage): что в базе, какие источники,
  что показывать вправе, коды отказов.
- [Спецификация OpenAPI](https://ai-belarus.by/openapi.yaml): выгружается из кода.
- [Карта сайта](https://ai-belarus.by/sitemap.xml): все открытые страницы организаций.
- [Открытый ключ подписи пакетов](https://ai-belarus.by/v1/meta/signing-key): Ed25519.
- [Права субъекта персональных данных](https://ai-belarus.by/v1/rights).

## Правила

- Темп: живая проверка — не больше 60 запросов в минуту с адреса, карточки и поиск —
  30; ответ 429 означает «подождите». Повтор того же УНП в течение 10 минут отвечает
  запомненным ответом держателя; момент настоящего получения — в `доказательство.получено`.
- Отказы: application/problem+json (RFC 9457) с полем `code` и `retryable`; любая вина
  клиента остаётся 4xx.
- Список УНП (до 50) — только по ключу клиента: POST /v1/counterparty/batch.
- Сведения, полученные от службы, при дальнейшем распространении обязаны называть
  обладателя (например, МНС — Государственный реестр плательщиков) и распространителя
  (AI-BELARUS): реквизиты приходят в поле `attribution` каждого разрешённого утверждения.
- Поле `доказательство` и `evidence[].content_hash` несут sha256 сырого ответа реестра:
  по нему ответ можно сверить независимо, запросив реестр тем же адресом.

## Подробнее

- [Страница для машин и их авторов](https://ai-belarus.by/agents)
- [Проверка для человека](https://ai-belarus.by/check)