konturfocus

n8n community node для работы с API Контур Фокуса (developer.kontur.ru/doc/focus-v2)

Package Information

Released: 2 mo ago
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.0

Available Nodes

Documentation generating…

Kontur Focus icon
Kontur Focus
Работа с API Контур Фокуса (проверка контрагентов, реквизиты, финансы, аналитика, связи)

Documentation

n8n-nodes-konturfocus

Community-нода для n8n, которая оборачивает API Контур Фокуса v2 — сервис проверки контрагентов от СКБ Контур.

Нода покрывает все 93 метода API (19 разделов: поиск компаний, базовые реквизиты ЕГРЮЛ/ЕГРИП, финансы и налоги, аналитика и скоринг, связи и аффилированность, банкротство, госзакупки и РНП, наблюдение за изменениями, проверка физлиц и т.д.).

Установка

Через интерфейс n8n

Settings → Community Nodes → Install → указать n8n-nodes-konturfocus.

Вручную (self-hosted)

cd ~/.n8n/custom
npm install n8n-nodes-konturfocus

или для локальной разработки — собрать пакет (см. ниже) и подключить его через N8N_CUSTOM_EXTENSIONS.

Настройка Credentials

В n8n создайте креденшл Kontur Focus API:

  • API Key — ключ доступа, который выдаёт компания СКБ Контур (тестовый ключ можно получить через заявку). Ключ хранится только в credentials и никогда не отображается в параметрах ноды — во все запросы он автоматически подставляется как query-параметр key.
  • Base URL — по умолчанию https://focus-api.kontur.ru, менять не требуется.

Кнопка Test в форме credentials обращается к методу /api3/stat и проверяет валидность ключа.

Использование ноды

В ноде Kontur Focus выберите:

  1. Ресурс — раздел API (например, «ФНС. Базовые реквизиты», «Финансы и налоги», «Аналитика и оценка компаний»).
  2. Операция — конкретный метод внутри раздела (например, «Базовые реквизиты», «Скоринговая оценка»).
  3. Заполните появившиеся поля метода (ИНН/ОГРН, диапазоны дат и т.д.) — их состав и подписи взяты из официальной OpenAPI-спецификации Контур Фокуса.

Для методов «Наблюдение» с добавлением/удалением компаний из списка на наблюдении тело запроса передаётся отдельным JSON-полем (массив объектов вида [{"inn":"7707083893"}]).

Ограничения и особенности

  • Параметр Формат XML, присутствующий у части методов, оставлен «как есть» из API, но нода всегда ожидает JSON-ответ — не включайте его, если не уверены, что нужен именно XML.
  • Обязательность параметров у Контур Фокуса часто «условная» (например, нужен ИНН или ОГРН) — нода не блокирует выполнение на уровне UI, а прокидывает ошибку API Фокуса (400/403) как есть, если обязательные данные не переданы.
  • Лимиты на количество запросов и параллельных обращений — на стороне Контур Фокуса, см. технические ограничения.

Разработка

npm install
npm run build       # tsc + копирование иконок в dist
npm run generate     # перегенерировать nodes/KonturFocus/descriptions/* из openapi/focus-v2.trimmed.json

Как устроен код

  • credentials/KonturFocusApi.credentials.ts — креденшл с ключом и авторизацией через query-параметр.
  • nodes/KonturFocus/KonturFocus.node.ts — декларативная нода (routing-style), без ручного execute(): каждая операция и поле сами описывают, в какой query-параметр или тело запроса они превращаются.
  • nodes/KonturFocus/descriptions/*.operations.ts / *.fields.ts — по одному файлу на раздел API, сгенерированы автоматически скриптом scripts/generate-descriptions.js из openapi/focus-v2.trimmed.json.
  • openapi/focus-v2.trimmed.json — облегчённая версия официальной OpenAPI-спецификации Контур Фокуса (только пути, теги, параметры; убраны схемы ответов).

Обновление под новую версию API

  1. Скачать актуальную спецификацию: curl https://developer.kontur.ru/api/documentations/focus-v2 -o /tmp/focus-v2.json.
  2. Обновить openapi/focus-v2.trimmed.json (оставить paths[*].{tag,summary,operationId,parameters,hasBody}).
  3. Запустить npm run generate — файлы в descriptions/ перезапишутся.
  4. npm run build и проверить работу в n8n.

Лицензия

MIT

Discussion