Search by

ex3mm / kontur-focus

Ex3mm

Laravel/PHP package for Kontur.Focus API integration

Package info

github.com/ex3mm/kontur-focus

pkg:composer/ex3mm/kontur-focus

Statistics

Installs: 321

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

1.8.0 2026-10-30 09:35 UTC

This package is auto-updated.

Last update: 2026-10-30 09:39:17 UTC


README

PHP 8.5+ пакет для интеграции с API Контур.Фокус.

Возможности

  • standalone режим (чистый PHP, без фреймворка)
  • Laravel интеграция (ServiceProvider, Facade, публикация конфига)
  • fluent API для запросов (inn(), ogrn(), param(), asDto(), asArray())
  • строгий маппинг ответа в readonly DTO через Reflection
  • retry middleware (сетевые ошибки, 5xx, 429)
  • cache middleware с кешированием только успешных 2xx ответов
  • logging middleware с маскированием API ключа в query-параметре key

Требования

  • PHP ^8.5
  • расширение ext-json

Установка

composer require ex3mm/kontur-focus

Быстрый старт (standalone)

<?php

declare(strict_types=1);

use Ex3mm\KonturFocus\Config\KonturFocusConfig;
use Ex3mm\KonturFocus\KonturFocusManager;

$config = KonturFocusConfig::fromArray(
    require __DIR__ . '/config/kontur-focus.standalone.php'
);

$focus = new KonturFocusManager($config);

$result = $focus->req()
    ->inn('7707083893')
    ->asDto()
    ->get();

Быстрый старт (Laravel)

Provider и Facade подключаются через auto-discovery.

use Ex3mm\KonturFocus\Laravel\Facades\KonturFocus;

// Вариант 1: Упрощённый синтаксис (рекомендуется)
$result = KonturFocus::getReq(inn: '7707083893');

// Вариант 2: Fluent API для гибкой настройки
$result = KonturFocus::req()
    ->inn('7707083893')
    ->asArray()
    ->get();

Публикация конфига:

php artisan vendor:publish --tag=kontur-focus-config

Конфигурация

Файл: config/kontur-focus.php

Пример полного конфига:

return [
    'key' => env('KONTUR_FOCUS_API_KEY', ''),
    'base_url' => env('KONTUR_FOCUS_BASE_URL', 'https://focus-api.kontur.ru'),

    'http' => [
        'timeout' => (float) env('KONTUR_FOCUS_TIMEOUT', 30),
        'connect_timeout' => (float) env('KONTUR_FOCUS_CONNECT_TIMEOUT', 10),
        'verify_ssl' => (bool) env('KONTUR_FOCUS_VERIFY_SSL', true),
    ],

    'retry' => [
        'enabled' => (bool) env('KONTUR_FOCUS_RETRY_ENABLED', true),
        'max_attempts' => (int) env('KONTUR_FOCUS_RETRY_ATTEMPTS', 3),
        'delay_ms' => (int) env('KONTUR_FOCUS_RETRY_DELAY', 500),
        'multiplier' => (float) env('KONTUR_FOCUS_RETRY_MULTIPLIER', 2),
        'max_delay_ms' => (int) env('KONTUR_FOCUS_RETRY_MAX_DELAY', 30000),
    ],

    'cache' => [
        'enabled' => (bool) env('KONTUR_FOCUS_CACHE_ENABLED', true),
        'ttl' => (int) env('KONTUR_FOCUS_CACHE_TTL', 3600),
        'store' => env('KONTUR_FOCUS_CACHE_STORE', 'default'),
        'namespace' => env('KONTUR_FOCUS_CACHE_NAMESPACE', 'kontur-focus'),
    ],

    'logging' => [
        'enabled' => (bool) env('KONTUR_FOCUS_LOG_ENABLED', true),
        'level' => env('KONTUR_FOCUS_LOG_LEVEL', 'basic'),
        'channel' => env('KONTUR_FOCUS_LOG_CHANNEL', 'default'),
        'max_body_size' => (int) env('KONTUR_FOCUS_LOG_MAX_BODY_SIZE', 10000),
    ],
];

Параметры конфигурации

Ключ По умолчанию Описание
key '' API ключ Контур.Фокус
base_url https://focus-api.kontur.ru Базовый URL API
http.timeout 30 Таймаут запроса в секундах
http.connect_timeout 10 Таймаут соединения в секундах
http.verify_ssl true Проверка SSL сертификата
retry.enabled true Включить retry middleware
retry.max_attempts 3 Максимум попыток (включая первую)
retry.delay_ms 500 Начальная задержка между попытками
retry.multiplier 2 Множитель backoff
retry.max_delay_ms 30000 Верхний лимит задержки
cache.enabled true Включить cache middleware
cache.ttl 3600 TTL кеша в секундах
cache.store default Имя store (оставлено для совместимости конфига)
cache.namespace kontur-focus Префикс namespace кеша
logging.enabled true Включить логирование
logging.level basic Уровень детализации контекста
logging.channel default Логический канал в конфиге пакета
logging.max_body_size 10000 Максимальный размер body в логах

Endpoint-ы

Метод менеджера URI DTO по умолчанию Требует inn/ogrn
req() /api3/req ReqResponseDto Да
egrDetails() /api3/egrDetails EgrDetailsResponseDto Да
legalAnalytics() /api3/legalAnalytics LegalAnalyticsResponseDto Да
bankruptcyAnalytics() /api3/bankruptcyAnalytics BankruptcyAnalyticsResponseDto Да
courtAnalytics() /api3/courtAnalytics CourtAnalyticsResponseDto Да
companyAffiliationsTypes() /api3/companyAffiliationsTypes CompanyAffiliationsTypesResponseDto Да
financeAnalytics() /api3/financeAnalytics FinanceAnalyticsResponseDto Да
fsspAnalytics() /api3/fsspAnalytics FsspAnalyticsResponseDto Да
fssp() /api3/fssp FsspResponseDto Да
linkAnalytics() /api3/linkAnalytics LinkAnalyticsResponseDto Да
purchasesAnalytics() /api3/purchasesAnalytics PurchasesAnalyticsResponseDto Да
purchasesOfParticipant() /api3/purchasesOfParticipant PurchasesOfParticipantResponseDto Да
petitionersOfArbitration() /api3/petitionersOfArbitration PetitionersOfArbitrationResponseDto Да
personBankruptcy() /api3/personBankruptcy PersonBankruptcyResponseDto Нет: innfl или fio
licenses() /api3/licences LicensesResponseDto Да
beneficiary() /api3/beneficialOwners BeneficiaryResponseDTO Да
accountingReports() /api3/accountingReports AccountingReportsResponseDto Да
custom('/api3/...') произвольный нет Нет

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

Упрощённые методы фассада

use Ex3mm\KonturFocus\Laravel\Facades\KonturFocus;

// Получить данные по ИНН
$result = KonturFocus::getReq(inn: '7707083893');

// Получить данные по ОГРН
$result = KonturFocus::getEgrDetails(ogrn: '1027700132195');

// Можно передать оба параметра
$result = KonturFocus::getLegalAnalytics(
    inn: '7707083893',
    ogrn: '1027700132195'
);

Доступные методы:

Метод Параметры Возвращает
getReq() ?string $inn = null, ?string $ogrn = null CollectionResponse
getEgrDetails() ?string $inn = null, ?string $ogrn = null CollectionResponse
getLegalAnalytics() ?string $inn = null, ?string $ogrn = null CollectionResponse
getBankruptcyAnalytics() ?string $inn = null, ?string $ogrn = null CollectionResponse
getCourtAnalytics() ?string $inn = null, ?string $ogrn = null CollectionResponse
getCompanyAffiliationsTypes() ?string $inn = null, ?string $ogrn = null, ?int $skip = null, ?int $take = null, ?int $affiliationType = null CollectionResponse
getFinanceAnalytics() ?string $inn = null, ?string $ogrn = null CollectionResponse
getFsspAnalytics() ?string $inn = null, ?string $ogrn = null CollectionResponse
getFssp() ?string $inn = null, ?string $ogrn = null, ?int $skip = null CollectionResponse
getLinkAnalytics() ?string $inn = null, ?string $ogrn = null CollectionResponse
getPurchasesAnalytics() ?string $inn = null, ?string $ogrn = null CollectionResponse
getPurchasesOfParticipant() ?string $inn = null, ?string $ogrn = null, ?int $skip = null, ?int $take = null CollectionResponse
getPetitionersOfArbitration() ?string $inn = null, ?string $ogrn = null, ?int $skip = null, ?int $take = null CollectionResponse
getPersonBankruptcy() ?string $inn = null, ?string $fio = null, ?string $birthDate = null CollectionResponse
getLicenses() ?string $inn = null, ?string $ogrn = null CollectionResponse
getBeneficiary() ?string $inn = null, ?string $ogrn = null CollectionResponse
getAccountingReports() ?string $inn = null, ?string $ogrn = null CollectionResponse
// Все методы возвращают CollectionResponse
$result->items;      // array<DTO>
$result->first();    // DTO|null
$result->isEmpty();  // bool

Ближайшие связи компаний

Endpoint /api3/companyAffiliationsTypes возвращает связанные с проверяемой компанией организации и причины установленных связей. Параметры skip и take управляют постраничной выдачей, а affiliationType позволяет выбрать тип связи согласно справочнику Контур.Фокуса.

$result = KonturFocus::getCompanyAffiliationsTypes(
    inn: '6663003127',
    skip: 0,
    take: 100,
    affiliationType: 2,
);

$affiliate = $result->first();
$affiliate->inn;         // ИНН связанной организации или ИП
$affiliate->name;       // Наименование организации или ФИО ИП
$affiliate->status;     // Статус организации или ИП
$affiliate->connections; // Типы связей и роли участников

Связи могут содержать информацию о юридическом или физическом лице, через которое построена связь, роли в связанной и проверяемой компаниях, актуальность роли, доли учредителя и доли акционера.

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

Endpoint /api3/fssp возвращает актуальность данных (updateDate) и список исполнительных производств в поле fssp. Для постраничного получения списка используется skip с шагом 1000.

$result = KonturFocus::getFssp(
    inn: '7707083893',
    skip: 1000,
);

$company = $result->first();
$company->updateDate; // Дата актуальности данных
$company->fssp;       // array<FsspDataDto>|null

Каждое производство содержит номер, сводный номер, даты, сумму, предмет и исполнительный документ, данные должника, признаки возврата взыскателю/окончания по банкротству или ликвидации, дату окончания и данные отдела судебных приставов.

Закупки участника

Endpoint /api3/purchasesOfParticipant возвращает закупки, в которых участвовала организация. Параметры skip и take управляют постраничной выдачей.

$result = KonturFocus::getPurchasesOfParticipant(
    inn: '7707083893',
    skip: 0,
    take: 100,
);

$company = $result->first();
$company->purchasesOfParticipant; // array<PurchaseDto>

Закупка содержит сведения о способе и статусе закупки, ценах, заказчиках, участниках, контракте и объектах закупки с кодами ОКДП, ОКПД, ОКПД2 и КТРУ.

Истцы в арбитражных делах

Endpoint /api3/petitionersOfArbitration возвращает статистику по организациям, выступавшим истцами в арбитражных делах за последние три года. Параметры skip и take управляют постраничной выдачей.

$result = KonturFocus::getPetitionersOfArbitration(
    inn: '7707083893',
    skip: 0,
    take: 100,
);

$company = $result->first();
$company->petitioners; // array<PetitionerDto>|null

Для каждого истца доступны ИНН, ОГРН, наименование, основной вид деятельности, оценка количества дел и исковой суммы за три года, а также дата последнего дела.

Банкротство физического лица

Endpoint /api3/personBankruptcy принимает ИНН физического лица или ФИО; birthDate можно передать дополнительно для уточнения поиска. В публичном convenience-методе используется параметр inn, который внутри преобразуется в API-параметр innfl.

// По ИННФЛ
$result = $focus->getPersonBankruptcy(
    inn: '123456789012',
    fio: 'Иванов Иван Иванович',
    birthDate: '1980-01-15',
);

// Fluent API по ФИО
$result = $focus->personBankruptcy()
    ->param('innfl', '123456789012')
    ->param('fio', 'Иванов Иван Иванович')
    ->param('birthDate', '1980-01-15')
    ->asDto()
    ->get();

$person = $result->first();
$person->stage;                    // Текущая стадия банкротства
$person->caseNumber;              // Номер арбитражного дела
$person->extrajudicialBankruptcy; // Внесудебное банкротство
$person->arbitrationManager;      // Арбитражный управляющий
$person->stages;                  // История стадий
$person->messages;                // Сообщения ЕФРСБ

Для сообщений доступны messageId, decision и annulment. В decision также возвращается terminationType, если Контур.Фокус передал причину прекращения производства.

Режим asArray()

$data = $focus->req()
    ->inn('7707083893')
    ->asArray()
    ->get();

Режим asDto()

$result = $focus->req()
    ->inn('7707083893')
    ->asDto()
    ->get();

// $result - это CollectionResponse с полями:
// - items: array<DTO> - массив DTO объектов
// - raw: string - сырой JSON ответ
// - total: int - количество элементов

// Получить первый элемент
$dto = $result->first();

// Проверить пустоту
if ($result->isEmpty()) {
    // нет данных
}

// Получить массив DTO
$items = $result->toArray();

Выброс исключения при пустом результате

use Ex3mm\KonturFocus\Exceptions\EmptyResponseException;

try {
    $result = $focus->req()
        ->inn('7707083893')
        ->asDto()
        ->throwOnEmpty() // выбросит EmptyResponseException если total === 0
        ->get();
} catch (EmptyResponseException $e) {
    // обработка пустого результата
}

Кастомный endpoint

$result = $focus->custom('/api3/someEndpoint')
    ->param('foo', 'bar')
    ->param('limit', 10)
    ->asArray()
    ->get();

Валидация параметров

Для стандартных endpoint-ов запрос должен содержать хотя бы один параметр: inn или ogrn. Если оба пустые, выбрасывается RequestValidationException.

DTO и маппинг

ResponseMapper строит DTO через Reflection-конструктор и имена параметров.

  • скалярные поля валидируются по типу
  • вложенные DTO создаются рекурсивно
  • массивы DTO/скаляров требуют #[ArrayOf(...)]
  • все DTO-ответы оборачиваются в CollectionResponse с полями items, raw, total

CollectionResponse

Все запросы в режиме asDto() возвращают CollectionResponse:

$result = $focus->req()->inn('7707083893')->asDto()->get();

// Доступные методы:
$result->items;      // array<DTO> - массив DTO объектов
$result->raw;        // string - сырой JSON ответ
$result->total;      // int - количество элементов
$result->first();    // DTO|null - первый элемент или null
$result->toArray();  // array<DTO> - массив DTO
$result->count();    // int - количество элементов
$result->isEmpty();  // bool - проверка на пустоту
$result->isNotEmpty(); // bool - проверка на наличие данных

Пример DTO с массивом вложенных объектов:

use Ex3mm\KonturFocus\DTOs\Attributes\ArrayOf;

final readonly class ParentDto
{
    /**
     * @param array<ChildDto> $children
     */
    public function __construct(
        #[ArrayOf(ChildDto::class)]
        public array $children,
    ) {
    }
}

Ошибки и исключения

HTTP ошибки

Статус Исключение
400, 422 ValidationException
401 AuthenticationException
403 AuthorizationException
404 NotFoundException
409 ConflictException
429 RateLimitException (retryAfterSeconds заполнен при наличии Retry-After)
5xx ServerException
другое 4xx/5xx HttpException

Прочие ошибки

  • NetworkException — сетевые/транспортные проблемы Guzzle
  • InvalidResponseException — пустой 2xx body, не-JSON Content-Type, невалидный JSON
  • DtoMappingException — mismatch типов/структуры при маппинге
  • ConfigurationException — неверная конфигурация (key, base_url, logging.level, и т.д.)
  • RequestValidationException — не переданы обязательные query-параметры (inn/ogrn)

Retry / Cache / Logging

Retry middleware

Повтор выполняется если:

  • есть transport-исключение
  • ответ 429
  • ответ >= 500

Задержка рассчитывается из retry.delay_ms + retry.multiplier, с ограничением retry.max_delay_ms. Для 429 при наличии Retry-After используется значение заголовка.

Cache middleware

  • кешируются только ответы со статусом 2xx
  • ключ кеша нормализует query-параметры
  • значение query-параметра key хешируется (sha256) и не попадает в кеш-ключ в открытом виде

Logging middleware

Поддерживаемые уровни: none, error, basic, headers, body, debug.

  • в лог всегда пишется краткая строка запроса (METHOD URL)
  • API ключ в query-параметре key маскируется (***)
  • в зависимости от уровня добавляются заголовки и body