README

PHP пакет для работы с API DaData с поддержкой Laravel и чистого PHP.

Возможности

Подсказки: адреса, компании
Стандартизация: адреса
Поиск по ID: ФИАС, ГАР, КЛАДР, ИНН, ОГРН, кадастровый номер
Аффилированные компании через учредителей и руководителей
Упрощенные методы с предустановленными параметрами
Автоматическое кеширование и логирование
Обработка Rate Limiting
PHP 8.1+

Установка

composer require ex3mm/dadata-api

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

Настройка .env

DADATA_API_KEY=your-api-key
DADATA_SECRET_KEY=your-secret-key
DADATA_CACHE_ENABLED=true
DADATA_LOGGING_ENABLED=true
DADATA_LOG_RESPONSE_BODY=false  # Включить для отладки (создает большие логи)

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

php artisan vendor:publish --tag=dadata-config

Методы фасада

Адреса

use Ex3mm\DaDataApi\Laravel\Facades\DaData;

// Подсказки
DaData::suggestAddress('москва тверская');
DaData::suggestAddress('ленина', 5, 'Москва');

// Поиск по ID (ФИАС, ГАР, КЛАДР, кадастровый номер)
DaData::findAddressById('7700000000000');

// Стандартизация
DaData::cleanAddress('мск сухонская 11');

Компании

Подсказки - упрощенные методы

// По статусу (принимают только query и count)
DaData::suggestCompanyActive('сбербанк');           // ACTIVE
DaData::suggestCompanyLiquidating('сбербанк');      // LIQUIDATING
DaData::suggestCompanyLiquidated('сбербанк');       // LIQUIDATED

// Юридические лица по статусу
DaData::suggestCompanyLegal('сбербанк');            // LEGAL + ACTIVE
DaData::suggestCompanyLegalLiquidating('сбербанк'); // LEGAL + LIQUIDATING
DaData::suggestCompanyLegalLiquidated('сбербанк');  // LEGAL + LIQUIDATED

// ИП по статусу
DaData::suggestCompanyIndividual('иванов');            // INDIVIDUAL + ACTIVE
DaData::suggestCompanyIndividualLiquidating('иванов'); // INDIVIDUAL + LIQUIDATING
DaData::suggestCompanyIndividualLiquidated('иванов');  // INDIVIDUAL + LIQUIDATED

// С фильтром по ОКВЭД
DaData::suggestCompanyByOkved('сбербанк', '64.19');
DaData::suggestCompanyByOkved('банк', '64.19', 10);

// Базовый метод (если нужны кастомные параметры)
DaData::suggestCompany('сбербанк', 10, 'ACTIVE', 'LEGAL');

Поиск по ИНН/ОГРН

// Базовый поиск
DaData::findCompany('7707083893');                    // По ИНН
DaData::findCompany('1027700132195');                 // По ОГРН
DaData::findCompanyByKpp('7707083893', '770701001'); // По ИНН и КПП

// По типу организации
DaData::findCompanyLegal('7707083893');               // Юрлицо
DaData::findCompanyIndividual('773301001');           // ИП

// По типу подразделения
DaData::findCompanyMain('7707083893');                // Головная организация
DaData::findCompanyBranch('7707083893');              // Филиал
DaData::findCompanyLegal('7707083893', 'MAIN');       // Юрлицо + головная
DaData::findCompanyLegal('7707083893', 'BRANCH');     // Юрлицо + филиал

Аффилированные компании

DaData::findCompanyAffiliated('7707083893');              // Все
DaData::findCompanyAffiliatedByFounders('7707083893');    // Через учредителей
DaData::findCompanyAffiliatedByManagers('7707083893');    // Через руководителей

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

Для более гибкой настройки параметров используйте билдеры напрямую:

// Suggest билдер
DaData::suggest()->address('москва', ['count' => 5])->toArray();
DaData::suggest()->party('сбербанк', ['okved' => ['64.19']])->toArray();
DaData::suggest()->country('росс', ['count' => 5])->toArray();
DaData::suggest()->bank('сбербанк', ['status' => ['ACTIVE']])->toArray();
DaData::suggest()->fio('иванов', ['gender' => 'MALE'])->toArray();
DaData::suggest()->fnsUnit('нижнего', ['filters' => [['region_code' => '52']]])->toArray();
DaData::suggest()->court('нижний', ['filters' => [['court_type' => 'MS']]])->toArray();
DaData::suggest()->findById('party', '7707083893', ['kpp' => '770701001'])->toArray();
DaData::suggest()->findAffiliated('7707083893', ['scope' => ['FOUNDERS']])->toArray();

// Clean билдер
DaData::clean()->address(['мск сухонская 11'])->toArray();
DaData::clean()->fio(['Иванов Иван Иванович'])->toArray();
DaData::clean()->phone(['+79991234567'])->toArray();
DaData::clean()->email(['test@example.com'])->toArray();
DaData::clean()->passport(['4509 235857'])->toArray();

// Произвольные запросы для других справочников
DaData::suggestRaw('suggest/email', ['query' => 'test@']);
DaData::cleanRaw('clean/vehicle', ['АА1234567']);

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

Laravel (.env)

DADATA_API_KEY=your-api-key
DADATA_SECRET_KEY=your-secret-key
DADATA_TIMEOUT=30
DADATA_RETRY_ATTEMPTS=3
DADATA_CACHE_ENABLED=true
DADATA_CACHE_TTL=3600
DADATA_LOGGING_ENABLED=true
DADATA_LOG_CHANNEL=stack
DADATA_LOG_RESPONSE_BODY=false
DADATA_RATE_LIMIT_BEHAVIOR=wait

Чистый PHP

use Ex3mm\DaDataApi\Client;
use Ex3mm\DaDataApi\Config\Configuration;

$config = new Configuration([
    'api_key' => 'your-api-key',
    'secret_key' => 'your-secret-key',
    'timeout' => 30,
    'retry_attempts' => 3,
    'cache_enabled' => true,
    'cache_ttl' => 3600,
    'logging_enabled' => true,
    'log_response_body' => false,
    'rate_limit_behavior' => 'wait',
]);

$client = new Client($config);

// Использование
$companies = $client->suggestCompanyLegal('сбербанк');
$company = $client->findCompany('7707083893');

Обработка ошибок

use Ex3mm\DaDataApi\Exceptions\{
    RateLimitException,
    ApiException,
    AuthenticationException,
    NetworkException
};

try {
    $result = DaData::suggestCompany('сбербанк');
} catch (RateLimitException $e) {
    echo "Retry after " . $e->getRetryAfter() . " seconds";
} catch (AuthenticationException $e) {
    echo "Ошибка аутентификации: " . $e->getMessage();
} catch (NetworkException $e) {
    echo "Ошибка сети: " . $e->getMessage();
} catch (ApiException $e) {
    echo "Ошибка API: " . $e->getMessage();
}

Кеширование и логирование

Laravel

Кеш и логгер подключаются автоматически. Для логирования в отдельный канал:

// config/logging.php
'channels' => [
    'dadata' => [
        'driver' => 'single',
        'path' => storage_path('logs/dadata.log'),
        'level' => 'debug',
    ],
],

// .env
DADATA_LOG_CHANNEL=dadata
DADATA_LOGGING_ENABLED=true
DADATA_LOG_RESPONSE_BODY=false  # true для отладки (создает большие логи)

Опции логирования:

DADATA_LOGGING_ENABLED - включить/выключить логирование
DADATA_LOG_CHANNEL - канал логирования Laravel
DADATA_LOG_RESPONSE_BODY - логировать полное тело ответа API (по умолчанию false)

⚠️ Внимание: Включение DADATA_LOG_RESPONSE_BODY=true создаст большие файлы логов, так как будет записывать полный JSON ответ от API. Используйте только для отладки.

Чистый PHP

use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$cache = new Psr16Cache(new FilesystemAdapter());
$logger = new Logger('dadata');
$logger->pushHandler(new StreamHandler('dadata.log'));

$client = new Client($config, $cache, $logger);

Примеры

Смотрите директорию examples/ для полных примеров использования.

Документация

Официальная документация DaData

Требования

PHP 8.1+
Guzzle HTTP Client 7.0+

Лицензия

MIT License

ex3mm / dadata-api

Maintainers

Details

README

Возможности

Установка

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

Настройка .env

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

Методы фасада

Адреса

Компании

Подсказки - упрощенные методы

Поиск по ИНН/ОГРН

Аффилированные компании

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

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

Laravel (.env)

Чистый PHP

Обработка ошибок

Кеширование и логирование

Laravel

Чистый PHP

Примеры

Документация

Требования

Лицензия