Download the PHP package ex3mm/kontur-focus without Composer
On this page you can find all versions of the php package ex3mm/kontur-focus. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download ex3mm/kontur-focus
More information about ex3mm/kontur-focus
Files in ex3mm/kontur-focus
Package kontur-focus
Short Description Laravel/PHP package for Kontur.Focus API integration
License MIT
Informations about the package kontur-focus
kontur-focus
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
Установка
Быстрый старт (standalone)
Быстрый старт (Laravel)
Provider и Facade подключаются через auto-discovery.
Публикация конфига:
Конфигурация
Файл: config/kontur-focus.php
Пример полного конфига:
Параметры конфигурации
| Ключ | По умолчанию | Описание |
|---|---|---|
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
Упрощённые методы фассада
Доступные методы:
| Метод | Параметры | Возвращает |
|---|---|---|
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 |
Ближайшие связи компаний
Endpoint /api3/companyAffiliationsTypes возвращает связанные с проверяемой компанией организации и причины установленных связей. Параметры skip и take управляют постраничной выдачей, а affiliationType позволяет выбрать тип связи согласно справочнику Контур.Фокуса.
Связи могут содержать информацию о юридическом или физическом лице, через которое построена связь, роли в связанной и проверяемой компаниях, актуальность роли, доли учредителя и доли акционера.
Исполнительные производства
Endpoint /api3/fssp возвращает актуальность данных (updateDate) и список исполнительных производств в поле fssp. Для постраничного получения списка используется skip с шагом 1000.
Каждое производство содержит номер, сводный номер, даты, сумму, предмет и исполнительный документ, данные должника, признаки возврата взыскателю/окончания по банкротству или ликвидации, дату окончания и данные отдела судебных приставов.
Закупки участника
Endpoint /api3/purchasesOfParticipant возвращает закупки, в которых участвовала организация. Параметры skip и take управляют постраничной выдачей.
Закупка содержит сведения о способе и статусе закупки, ценах, заказчиках, участниках, контракте и объектах закупки с кодами ОКДП, ОКПД, ОКПД2 и КТРУ.
Истцы в арбитражных делах
Endpoint /api3/petitionersOfArbitration возвращает статистику по организациям, выступавшим истцами в арбитражных делах за последние три года. Параметры skip и take управляют постраничной выдачей.
Для каждого истца доступны ИНН, ОГРН, наименование, основной вид деятельности, оценка количества дел и исковой суммы за три года, а также дата последнего дела.
Банкротство физического лица
Endpoint /api3/personBankruptcy принимает ИНН физического лица или ФИО; birthDate можно передать дополнительно для уточнения поиска. В публичном convenience-методе используется параметр inn, который внутри преобразуется в API-параметр innfl.
Для сообщений доступны messageId, decision и annulment. В decision также возвращается terminationType, если Контур.Фокус передал причину прекращения производства.
Режим asArray()
Режим asDto()
Выброс исключения при пустом результате
Кастомный endpoint
Валидация параметров
Для стандартных endpoint-ов запрос должен содержать хотя бы один параметр: inn или ogrn.
Если оба пустые, выбрасывается RequestValidationException.
DTO и маппинг
ResponseMapper строит DTO через Reflection-конструктор и имена параметров.
- скалярные поля валидируются по типу
- вложенные DTO создаются рекурсивно
- массивы DTO/скаляров требуют
#[ArrayOf(...)] - все DTO-ответы оборачиваются в
CollectionResponseс полямиitems,raw,total
CollectionResponse
Все запросы в режиме asDto() возвращают CollectionResponse:
Пример DTO с массивом вложенных объектов:
Ошибки и исключения
HTTP ошибки
| Статус | Исключение |
|---|---|
400, 422 |
ValidationException |
401 |
AuthenticationException |
403 |
AuthorizationException |
404 |
NotFoundException |
409 |
ConflictException |
429 |
RateLimitException (retryAfterSeconds заполнен при наличии Retry-After) |
5xx |
ServerException |
другое 4xx/5xx |
HttpException |
Прочие ошибки
NetworkException— сетевые/транспортные проблемы GuzzleInvalidResponseException— пустой2xxbody, не-JSONContent-Type, невалидный JSONDtoMappingException— 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
All versions of kontur-focus with dependencies
guzzlehttp/guzzle Version ^7.9
kevinrob/guzzle-cache-middleware Version ^8.0
psr/cache Version ^3.0
psr/clock Version ^1.0
psr/log Version ^3.0
symfony/cache Version ^7.3