# API Statsnet — данные компаний по REST

REST API Statsnet даёт программный доступ к тем же данным, что и сайт: карточки компаний Казахстана, Кыргызстана и Узбекистана, контакты, госконтракты, связи и риски. База API — `https://statsnet.co/api/v1`, формат ответов — JSON.

## Быстрый старт

Публичные эндпоинты работают без ключа. Получите карточку компании по БИН одним запросом:

```bash
curl "https://statsnet.co/api/v1/companies/kz/000740000728/meta/beta"
```

Для платных данных создайте API-ключ в [личном кабинете](/me) и передавайте его в заголовке `x-api-key`:

```bash
curl "https://statsnet.co/api/v1/companies/123/contacts" \
  -H "x-api-key: sk_live_YOUR_KEY"
```

## Аутентификация и ключи

Запросы подписываются заголовком `x-api-key` со значением вида `sk_live_...`. Ключи создаются в [личном кабинете](/me) — до 10 ключей на аккаунт.

Ключ наследует подписку владельца: без активного платного тарифа ключ даёт доступ только к публичным эндпоинтам. Платные эндпоинты расходуют квоту отчётов вашего тарифа — так же, как просмотр карточек на сайте. Храните ключ на сервере и не публикуйте его в клиентском коде или общих репозиториях.

## Публичные эндпоинты

Доступны без ключа и без подписки:

| Метод и путь | Описание |
| --- | --- |
| `GET /companies/{id}/meta/beta` | Карточка компании по внутреннему ID (JSON) |
| `GET /companies/{jurisdiction}/{identifier}/meta/beta` | Карточка по БИН/ИИН; юрисдикции: `kz`, `uz`, `kg` |
| `GET /companies/{jurisdiction}/{identifier}/md` | Карточка компании в формате Markdown — удобно для ИИ-агентов |
| `GET /companies/states/{jurisdiction}` | Список регионов юрисдикции |

## Платные эндпоинты

Требуют ключ с активной подпиской. Запрос полной карточки списывает один отчёт; повторные запросы той же компании в течение 2 недель бесплатны.

| Метод и путь | Описание |
| --- | --- |
| `GET /companies/{id}/paid` | Полная карточка компании |
| `GET /companies/{id}/contacts` | Контакты (телефоны, email, сайты) |
| `GET /companies/{id}/gov-contracts` | Госконтракты |
| `GET /companies/{id}/quasi_contracts` | Контракты квазигосударственного сектора |
| `GET /companies/{id}/relations` | Граф связей: учредители, руководители, аффилированные компании |
| `GET /individuals/{identifier}` | Карточка физического лица по ИИН |
| `POST /export` | Массовые выгрузки компаний по фильтрам (Excel) |

Поиск компаний по названию и фильтрам доступен через `POST /business/search` (параметры `query`, `jurisdiction`, `limit` — от 1 до 500).

## Учёт запросов и лимиты

- Один платный запрос по компании = один отчёт из квоты тарифа.
- Повторный запрос той же компании в течение 14 дней не расходует квоту.
- Количество отчётов зависит от тарифа — смотрите [тарифы](/plans).
- Публичные эндпоинты не расходуют квоту, но ограничены по частоте запросов.

## Коды ответов

| Код | Значение |
| --- | --- |
| `200` | Успешный запрос |
| `401` | Ключ не передан или недействителен |
| `402` | Подписка неактивна — платный эндпоинт недоступен |
| `403` | Нет доступа к ресурсу на текущем тарифе |
| `404` | Компания или ресурс не найдены |
| `429` | Квота периода исчерпана или превышена частота запросов |

## SDK и библиотеки

Официальные SDK покрывают основные эндпоинты и избавляют от ручной работы с HTTP:

- [Python SDK](https://github.com/statsnet/python-sdk) — `pip install statsnet-python-sdk`
- [JavaScript SDK](https://github.com/statsnet/js-sdk)
- [Go SDK](https://github.com/statsnet/gosdk)

Пример на Python:

```python
from statsnet_python_sdk import Client

client = Client("sk_live_YOUR_KEY")
companies = client.search(query="казпочта", jurisdiction="kz", limit=5)
company = client.get_company("kz", companies[0]["id"])
```

## Спецификация и ИИ-интеграции

- Интерактивная спецификация Swagger: [statsnet.co/api/v1/swagger/index.html](https://statsnet.co/api/v1/swagger/index.html).
- Машиночитаемая версия этой страницы: [statsnet.co/api.md](https://statsnet.co/api.md).
- Для ИИ-ассистентов (Claude, Cursor, ChatGPT) удобнее [MCP-сервер Statsnet](/integrations/mcp) — те же данные через Model Context Protocol с тем же API-ключом.

### Сколько стоит доступ к API?

Отдельного тарифа для API нет: ключ наследует вашу подписку Statsnet. Публичные эндпоинты бесплатны, платные расходуют отчёты тарифа — цены и лимиты на странице [тарифов](/plans). Для банков, финтеха и компаний с большими объёмами — bulk-выгрузки и индивидуальные лимиты, напишите нам через [форму контактов](/contact).

### Как получить API-ключ?

Зарегистрируйтесь на Statsnet, откройте [личный кабинет](/me) и создайте ключ в разделе API. На один аккаунт можно создать до 10 ключей — например, отдельные ключи для тестовой и боевой сред.

### Какие юрисдикции доступны через API?

Казахстан (`kz`), Узбекистан (`uz`) и Кыргызстан (`kg`). Набор данных по компании зависит от юрисдикции: максимально полные данные — по Казахстану (финансы, госконтракты, риски, связи).

### Чем API отличается от MCP-сервера?

API — классический REST для интеграций по заранее определённому сценарию: ваша система сама решает, какие эндпоинты и когда вызывать. [MCP-сервер](/integrations/mcp) отдаёт те же данные ИИ-ассистентам, которые сами выбирают инструменты под вопрос пользователя. Ключ и учёт запросов — общие.