API проверки контрагентов

На входе ИНН, на выходе — весь отчёт в JSON: реквизиты, финансовая отчётность по годам, арбитраж, ФССП, лицензии, госконтракты, блокировки счетов, банкротные сигналы, связанные лица и компании, риск-балл с разбором и заключение. Оплата по факту с предоплаченного баланса.

• 1. Быстрый старт
• 2. Ключ и аутентификация
• 3. Цены и режимы
• 4. Методы
• 5. Что в ответе
• 6. Блоки: есть данные или не собирали
• 7. Справочник полей
• 8. Ошибки
• 9. Лимиты и хранение

1. Быстрый старт

Проверка асинхронная: заказали — получили идентификатор — забрали результат. Полная проверка идёт минуты, синхронного ответа не бывает.

# 1. заказать
curl -X POST https://xn--d1ac0am9c.xn--80asehdb/v1/checks \
  -H "Authorization: Bearer $DOSSIER_KEY" \
  -H "Idempotency-Key: order-4471" \
  -H "Content-Type: application/json" \
  -d '{"inn": "7707083893", "mode": "basic"}'

{"id":"9f1c…","inn":"7707083893","mode":"basic","status":"queued","price_rub":20}

# 2. забрать (поллинг раз в 20 секунд)
curl https://xn--d1ac0am9c.xn--80asehdb/v1/checks/9f1c… \
  -H "Authorization: Bearer $DOSSIER_KEY"

2. Ключ и аутентификация

Ключ выпускается в кабинете и показывается один раз — сохраните его сразу, повторно мы его не покажем (в базе лежит только хеш). Активных ключей может быть до 5: чтобы сменить ключ без простоя, выпустите новый, переключите интеграцию и лишь потом отзовите старый.

Authorization: Bearer dsr_live_…

Принимается и заголовок X-Api-Key. Отзыв ключа действует немедленно, со следующего же запроса.

3. Цены и режимы

Режим по умолчанию — basic. Статус, баланс и /ping бесплатны. Упавшая проверка не тарифицируется: деньги возвращаются на баланс.

4. Методы

POST /v1/checks

Тело: {"inn": "…", "mode": "basic|full"}. Заголовок Idempotency-Key обязателен — он гарантирует, что повтор запроса (ваш таймаут, сбой прокси, перезапуск воркера) не запустит вторую проверку и не спишет деньги дважды. Повтор с тем же ключом вернёт ту же проверку и поле "idempotent_replay": true.

Ответ 202: id, status, mode, price_rub. Статусы: queued → running → done либо error.

GET /v1/checks/{id}

Пока проверка не готова, в ответе только статус и retry_after — секунды до следующей попытки. Готовая отдаёт отчёт целиком (см. ниже). Проверка, завершившаяся ошибкой, приходит с блоком error и пометкой refunded.

5. Что в ответе

{
  "id": "9f1c…", "inn": "7707083893", "mode": "basic",
  "status": "done", "price_rub": 20,
  "created_at": "2026-08-23 09:14:02", "finished_at": "2026-08-23 09:15:40",
  "schema_version": "1.0",
  "report": {
    "inn": "…", "name": "…",
    "score":  { "score": 42, "level": "средний", "subindices": [ … ] },
    "flags":  { "red_flags": [ … ], "green_flags": [ … ] },
    "target": {
      "extras":            { "address": "…", "okved": "…", "age_years": 12, … },
      "financial_history": { "series": { "revenue": { "2024": … } }, … },
      "legal_cases":       { "as_defendant": { … }, "dynamics": [ … ] },
      "enforcements":      { … }, "licenses": [ … ], "contracts": { … },
      …
    },
    "affiliates": [ … ], "persons": [ … ], "coverage": { … }
  },
  "blocks": { "licenses": "empty", "legal_cases": "ok", "media_coverage": "off" }
}

Размер готового отчёта — 90–130 КБ (20–30 КБ с gzip).

6. Блоки: есть данные или не собирали

Каждый документированный ключ присутствует в ответе всегда — если данных нет, там пустой список или пустой объект. Что именно означает пустота, говорит объект blocks:

7. Справочник полей

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

Верхний уровень

report.target — данные проверенной компании

8. Ошибки

Формат один: {"code": "…", "detail": "…"}. Ориентируйтесь на code — текст может меняться.

Повторять запрос имеет смысл на 429, 502 и 503. С тем же Idempotency-Key повтор безопасен всегда.

9. Лимиты и хранение

• до 120 запросов в минуту на ключ;
• до 4 проверок в работе одновременно;
• готовый отчёт хранится 90 дней и всё это время доступен по идентификатору; дальше остаётся только запись в истории списаний, а запрос отчёта возвращает body_expired;
• отчёты содержат персональные данные (ФИО руководителей, учредителей и бенефициаров) — обрабатывайте их на своей стороне соответственно.