OpenRegister Документация
⌘ K
Проверяем API v1
Developer APIStable v1

Одна схема для реестров разных стран.

Ищите компании через нормализованный JSON и при необходимости возвращайтесь к национальным полям, файлу и хешу первоисточника.

Получить API-ключ Отправить первый запрос ↓
PROVENANCE TRACE
  1. 01
    SOURCE FILEregistry.csv
  2. 02
    INTEGRITYsha256 verified
  3. 03
    NORMALIZElegal_entity
  4. 04
    RESPONSEGET /entities/{id}
BASE URLhttps://md.hanta.io/api/v1

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

От ключа до данных за три шага

Все методы данных используют единый контракт авторизации. SDK не обязателен: достаточно обычного HTTP-клиента.

  1. 1

    Создайте ключ

    Откройте API-кабинет, задайте название окружения и сразу сохраните секрет — повторно он не показывается.

    Открыть API-кабинет →
  2. 2

    Передайте ключ в заголовке

    Используйте X-API-Key или Bearer. В консоли API уже указаны правильный URL и параметры.

  3. 3

    Сохраните идентификатор запроса

    Ответ содержит X-Request-ID. Передавайте его поддержке при разборе конкретного запроса.

Авторизация

API-ключ принадлежит окружению

Создавайте отдельный ключ для production, staging и аналитики. Ключ действует от имени аккаунта и расходует его общую месячную квоту.

Рекомендуется

X-API-Key

X-API-Key: or_live_…
Совместимый вариант

Bearer token

Authorization: Bearer or_live_…
Ключ хранится только у вас.

OpenRegister сохраняет только SHA-256-хеш. Не помещайте секрет в строку запроса, клиентский пакет, логи или публичный репозиторий.

Registry APIX-API-Key

Серверные интеграции и запросы данных.

Account APIClerk session

Кабинет, ключи и управление подпиской.

Stripe webhookStripe-Signature

Только подписанные события от Stripe.

Пагинация

Страницы с предсказуемым размером

Поиск сортируется по названию и стабильному ID. Используйте значения из meta, а не вычисляйте число страниц на клиенте.

page1…N

Номер запрашиваемой страницы.

pageSize1…100

По умолчанию возвращается 25 записей.

meta.totalinteger

Количество записей по текущему фильтру.

meta.pageCountinteger

Число доступных страниц.

Лимиты и квоты

Два счётчика на каждый запрос

Минутный лимит защищает API от всплесков, месячная квота ограничивает объём тарифа. Оба счётчика возвращаются после каждого успешного запроса данных.

HeaderЗначение
X-RateLimit-LimitЛимит запросов в минуту.
X-RateLimit-RemainingОстаток в текущем окне.
X-RateLimit-ResetUnix timestamp сброса окна.
X-Monthly-Quota-LimitКвота расчётного периода.
X-Monthly-Quota-RemainingОстаток запросов в периоде.
X-Monthly-Quota-ResetДата нового периода в формате ISO 8601.
Получили 429?Прочитайте Retry-After, добавьте случайную задержку и повторите запрос.

Ошибки

Одинаковая форма для всех методов

Обрабатывайте error.code программно, а message показывайте в логах. requestId связывает ошибку с серверным запросом.

ERROR · 401 
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid or revoked",
    "requestId": "69a27c71-44ab-4c0c-a95d-1a1ea8da24cc",
    "docs": "https://md.hanta.io/docs/api"
  }
}
400invalid_request

Параметр или UUID имеет неверный формат.

401api_key_required

Заголовок с API-ключом отсутствует.

401invalid_api_key

Ключ неизвестен, отозван или повреждён.

404entity_not_found

Запись с таким OpenRegister ID не найдена.

429rate_limit_exceeded

Исчерпан минутный лимит ключа.

429monthly_quota_exceeded

Исчерпана квота расчётного периода.

Версионирование

Версия закреплена в URL

Текущий стабильный контракт — /api/v1. В рамках v1 мы можем добавлять новые nullable-поля и методы, но не удаляем поля и не меняем их тип без новой версии.

Машиночитаемый контрактOpenAPI 3.1 JSON
Скачать ↗

Справочник API

Методы Registry API

Все три метода требуют API-ключ и возвращают заголовки лимитов. Нажмите «Показать пример», чтобы открыть готовый запрос в консоли.

GET/countries

Список стран

Доступные сейчас и запланированные реестры.

API key application/json

Параметры не требуются.

GET/entities

Поиск компаний

Поиск по названию или IDNO с фильтрами и стабильной пагинацией.

API key application/json

Параметры

qstring

Фрагмент названия или регистрационного номера без учёта регистра.

countrystring

Двухбуквенный код страны ISO 3166-1.

legalFormstring

Точное национальное значение организационно-правовой формы.

activitystring

Точное значение или код вида деятельности.

activityTypeunlicensed | licensed

Тип списка деятельности: unlicensed или licensed.

pageinteger

Номер страницы. По умолчанию — 1.

pageSizeinteger

Размер страницы от 1 до 100. По умолчанию — 25.

GET/entities/{id}

Полная запись компании

Нормализованные поля, национальная запись и происхождение источника.

API key application/json

Параметры

iduuidобязательно

OpenRegister ID из результата поиска.

Справочник API

Объект Entity

Нормализованные поля одинаковы для всех стран. Национальная структура остаётся в registry и sourceData, поэтому новые страны не ломают общий контракт.

iduuid

Стабильный идентификатор OpenRegister.

countryCodestring

Код юрисдикции ISO 3166-1 alpha-2.

canonicalNamestring

Название для поиска и отображения.

statusstring

Нормализованный статус записи.

legalFormstring | null

Национальная организационно-правовая форма.

registryobject

Типизированные и расшифрованные национальные поля.

sourceDataobject

Исходные поля без потерь и переименований.

registrationsarray

Регистрационные номера и локальные статусы.

provenanceobject | null

Файл, хеш, дата импорта и URL первоисточника.

Тарифы API

Фиксированная цена без доплат

При исчерпании квоты API останавливает запросы с 429 — неожиданный счёт не появится.

GET/api/v1/plansпубличный

Free

€0/ мес.

Для прототипов и оценки API

  • 1 000 запросов / период
  • 60 запросов / минуту
  • 1 активных API-ключей

Pro

Популярный
€29/ мес.

Для продуктовых интеграций

  • 100 000 запросов / период
  • 600 запросов / минуту
  • 5 активных API-ключей

Business

€99/ мес.

Для больших объёмов и нескольких окружений

  • 1 000 000 запросов / период
  • 3 000 запросов / минуту
  • 20 активных API-ключей

Методы аккаунта

Аккаунт, использование и API-ключи

Эти методы обслуживают API-кабинет и используют токен сеанса Clerk или cookie сеанса. Ключ Registry API для них не подходит.

GET /api/v1/account

Тариф, использование, статус оплаты и активные ключи.

GET /api/v1/auth/me

Профиль текущего пользователя Clerk.

GET /api/v1/api-keys

Список активных ключей без секретов.

POST /api/v1/api-keys

Создать ключ и один раз вернуть полный секрет.

DELETE /api/v1/api-keys/{id}

Отозвать ключ текущего аккаунта.

Состояние сервиса

GET/api/v1/health/live

Процесс запущен и принимает HTTP-запросы.

GET/api/v1/health/ready

Приложение и PostgreSQL готовы принимать трафик.

Оплата через Stripe

Checkout и подписка

Платные планы оформляются в Stripe Checkout. Счета, способ оплаты, смена тарифа и отмена доступны через Stripe Customer Portal из API-кабинета.

1CheckoutСоздание подписки
→
2WebhookПроверка статуса
→
3EntitlementsНовые лимиты API

Доступ меняется только после подписанного webhook-события Stripe, а не после перенаправления из Checkout.

Методы оплаты

GET /api/v1/plans

Публичный каталог тарифов и доступных возможностей.

POST /api/v1/billing/checkout

Создать сеанс Stripe Checkout.

POST /api/v1/billing/portal

Создать сеанс Stripe Customer Portal.

POST /api/v1/billing/webhook

Внутренний метод с заголовком Stripe-Signature.

Поддерживаемые события
checkout.session.completedcustomer.subscription.createdcustomer.subscription.updatedcustomer.subscription.deletedcustomer.subscription.pausedcustomer.subscription.resumed

ID события сохраняется до обработки, поэтому повторная доставка безопасна. Более старое событие не перезаписывает новое состояние подписки.

Авторизация…