Быстрый старт
Публичные эндпоинты работают без ключа. Получите карточку компании по БИН одним запросом:
curl "https://statsnet.co/api/v1/companies/kz/000740000728/meta/beta"
Для платных данных создайте API-ключ в личном кабинете и передавайте его в заголовке x-api-key:
curl "https://statsnet.co/api/v1/companies/123/contacts" \
-H "x-api-key: sk_live_YOUR_KEY"
Аутентификация и ключи
Запросы подписываются заголовком x-api-key со значением вида sk_live_.... Ключи создаются в личном кабинете — до 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 дней не расходует квоту.
- Количество отчётов зависит от тарифа — смотрите тарифы.
- Публичные эндпоинты не расходуют квоту, но ограничены по частоте запросов.
Коды ответов
| Код | Значение |
|---|---|
200 | Успешный запрос |
401 | Ключ не передан или недействителен |
402 | Подписка неактивна — платный эндпоинт недоступен |
403 | Нет доступа к ресурсу на текущем тарифе |
404 | Компания или ресурс не найдены |
429 | Квота периода исчерпана или превышена частота запросов |
SDK и библиотеки
Официальные SDK покрывают основные эндпоинты и избавляют от ручной работы с HTTP:
- Python SDK —
pip install statsnet-python-sdk - JavaScript SDK
- Go SDK
Пример на 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.
- Машиночитаемая версия этой страницы: statsnet.co/api.md.
- Для ИИ-ассистентов (Claude, Cursor, ChatGPT) удобнее MCP-сервер Statsnet — те же данные через Model Context Protocol с тем же API-ключом.
Сколько стоит доступ к API?
Отдельного тарифа для API нет: ключ наследует вашу подписку Statsnet. Публичные эндпоинты бесплатны, платные расходуют отчёты тарифа — цены и лимиты на странице тарифов. Для банков, финтеха и компаний с большими объёмами — bulk-выгрузки и индивидуальные лимиты, напишите нам через форму контактов.
Как получить API-ключ?
Зарегистрируйтесь на Statsnet, откройте личный кабинет и создайте ключ в разделе API. На один аккаунт можно создать до 10 ключей — например, отдельные ключи для тестовой и боевой сред.
Какие юрисдикции доступны через API?
Казахстан (kz), Узбекистан (uz) и Кыргызстан (kg). Набор данных по компании зависит от юрисдикции: максимально полные данные — по Казахстану (финансы, госконтракты, риски, связи).
Чем API отличается от MCP-сервера?
API — классический REST для интеграций по заранее определённому сценарию: ваша система сама решает, какие эндпоинты и когда вызывать. MCP-сервер отдаёт те же данные ИИ-ассистентам, которые сами выбирают инструменты под вопрос пользователя. Ключ и учёт запросов — общие.