Download the PHP package sushi-market/laravel-dadata without Composer

DaData Laravel Package - PHP SDK Laravel пакет для взаимодействия с API DaData.ru от sushi-market

Requirements

• PHP >= 7.4 , 8.0, 8.1
• Laravel 8.75.0 - 10.0
• guzzlehttp/guzzle 7

Установка

Вы можете установить пакет через composer:

Публикация конфигурационного файла. Выполните artisan команду

Настройка проекта осществляется через .env вашего проекта. Вам необходимо указать три параметра

• DADATA_TOKEN - token для раоты с API DaData
• DADATA_SECRET - secret для работы с API DaData
• DADATA_TIMEOUT - максимальное время ожидания ответа от API сервисов DaData в секундах. По умолчанию это значение равно 10 секунд.

Пример .env

Методы

• Работа с адресами
  • Стандартизация адреса
  • Подсказки по адресам
  • Определение адреса по координатам
  • Определение адреса по IP
  • Определение адреса по КЛАДР или ФИАС коду
  • Определение ближайшего отделения Почты России по адресу
  • Определение отделения Почты России почтовому индексу
  • Определение отделения Почты России по координатам
  • Определение идентификатора города в СДЭК, Boxberry и DPD
  • Адрес в ФИАС по идентификатору
• Работа с именами
  • ФИО
  • Автодополнение при вводе («подсказки»)
• Работа с электорнными (email) адресами
  • Email
  • Подсказки по email
• Работа с телефонными номерами
  • Проверить телефон
• Работа с компаниями
  • Организация по ИНН
  • Автодополнение при вводе («подсказки»)
  • Поиск аффилированных компаний
• Работа с банками
  • Банк по БИК, SWIFT, ИНН или регистрационному номеру
  • API подсказок по банкам
• Работа с паспортами
  • Проверка по реестру МВД
  • Кем выдан паспорт

Работа с адресами

Стандартизация адреса

DaDataAddress::standardization(string $address) - разбивает адрес из строки по отдельным полям (регион, город, улица, дом, квартира) согласно КЛАДР/ФИАС. Определяет почтовый индекс, часовой пояс, ближайшее метро, координаты, стоимость квартиры и другую информацию об адресе.

Основные кейсы:

• Разбивает адрес по отдельным полям (регион, город, улица, дом, квартира).
• Рассчитывает корректный индекс по данным Почты России.
• Определяет координаты.
• Показывает округ и район города, ближайшее метро, площадь и стоимость квартиры.
• Достает коды КЛАДР, ФИАС, ОКАТО, ОКТМО и ИФНС.

Пример вызова

Пример ответа

Описани ответа

Координаты есть у 97% домов в Москве, 91% в Санкт-Петербурге, 69% в других городах-миллиониках и 47% по остальной России. Площадь и стоимость есть у 70% квартир в России.

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Подсказки по адресам

DaDataAddress::prompt(string $query, int $count, int $language, array $locations, array $locations_geo, array $locations_boost, array $from_bound, array $to_bound) Ищет адреса по любой части адреса от региона до дома («тверская нижний 12» → «Нижегородская обл, г Нижний Новгород, ул Тверская, д 12»). Также ищет почтовому индексу («105568» → «г Москва, ул Магнитогорская»).

Основные кейсы:

• Работает по всем странам мира (по России до дома, по остальным странам — до города). Ищет и показывает результаты как на русском языке («Самара, пр-кт Металлургов»), так и на английском («Russia, gorod Samara, prospekt Metallurgov»).
• Находит актуальные адреса по историческим названиям (Свердловск → Екатеринбург) и синонимам (Питер → Санкт-Петербург).
• Ищет по частичному совпадению («москва болот» → «г Москва, Болотная наб»), но только в последнем слове запроса («мос болот» не найдет).
• Исправляет опечатки («самара авиционная») и запросы в неправильной раскладке («vjcrdf» → «москва»). -️ Раскладывает выбранный адрес на гранулярные части (от региона до квартиры). -️ Поддерживает гранулярные подсказки по отдельным частям адреса (регионы, города, улицы, дома). -️ Подсказывает адреса в конкретных регионах, районах, городах и населенных пунктах. Понимает названия («Петергоф»), коды КЛАДР («7800000800000») и ФИАС («8f238984-812b-4bb1-850b-49749fb5c56d»). -️ Учитывает, где вы находитесь (в связке с методом город по IP-адресу).

Важно знать, что использовать данный метод не рекомендуется если вы

• Хотите автоматически, без участия человека, обработать адреса из базы или файла.
• Транслитерировать строки, например moskva suhonskaja 11 → 127642 в г Москва, ул Сухонская, д 11.

Подсказки не подходят для автоматической обработки адресов. Они предлагают варианты, но не гарантируют, что угадали правильно. Поэтому окончательное решение всегда должен принимать человек.

Для автоматической обработки и транслитерации используйте DaDataAddress::standardization(string $address) метод.

Параметры вызова

Пример вызова

Пример ответа

Описание ответа

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Определение адреса по координатам

DaDataAddress::geolocate(float $lat, float $lon, int $count, int $radius_meters, int $language) Находит ближайшие адреса (дома, улицы, города) по географическим координатам. Только для России.

Параметры вызова

Пример вызова

Пример ответа

Описание ответа

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Определение адреса по IP

DaDataAddress::iplocate(string $ip, int $count, int $language) определяет город по IP адресу.

Основные кейсы:

• Поддерживает как IPv4, так и IPv6 адреса
• Возвращает детальную информацию о городе, в том числе почтовый индекс.
• "Я тебя по айпи вычислю!"

Параметры вызова

Пример вызова

Пример ответа

Описание ответа

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Определение адреса по КЛАДР или ФИАС коду

DaDataAddress::id(string $ip, int $count, int $language) определяет адреса по КЛАДР или ФИАС коду.

Основные кейсы:

• Поиск по КЛАДР-код, только для России;
• ФИАС-код, только для России;
• Идентификатор OpenStreetMap, только для Белоруссии;
• Идентификатор GeoNames, для всех остальных стран.

Параметры вызова

Пример вызова

Пример ответа

Описание ответа

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Определение ближайшего отделения Почты России по адресу

DaDataAddress::postalUnitByAddress(string $address, int $count, int $language) определяет ближайшее почтовые отделения по адресу

Если интернет-магазин доставляет покупки почтой по России, хорошо бы подсказать человеку, где и когда он может забрать посылку. В этом поможет справочник почтовых отделений — в нём есть точный адрес, координаты и часы работы отделения, а ещё отметка, если оно временно закрыто.

Параметры вызова

Пример вызова

Пример ответа

Описание ответа

Описание вложенного массива data

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Определение отделения Почты России почтовому индексу

DaDataAddress::postalUnitById(int $code, int $count, int $language) определяет адреса почтовых отделений почтовому коду

Параметры вызова

Пример вызова

Пример ответа

Описание ответа

Описание вложенного массива data

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Определение отделения Почты России по координатам

DaDataAddress::postalUnitByGeoLocate(float $lat, float $lon, int $radius_meters, int $count, int $language) определяет адреса почтовых отделений по координатам

Параметры вызова

Пример вызова

Пример ответа

Описание ответа

Описание вложенного массива data

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Определение идентификатора города в СДЭК, Boxberry и DPD

DaDataAddress::delivery(string $code) помогает решить сзадачу определения идентификатора города в СДЭК, Boxberry и DPD

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

Метод DaDataAddress::delivery(string $code) определяет идентификатор города в службе доставке на основании КЛАДР-кода города.

Параметры вызова

Пример вызова

Пример ответа

Описание ответа

Описание вложенного массива data

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Адрес в ФИАС по идентификатору

DaDataAddress::fias(string $code) Находит адрес в справочнике ФИАС по коду КЛАДР или ФИАС.

ФИАС-коды домов иногда меняются, а метод ищет только по актуальным кодам. Поэтому рекомендуем помимо ФИАС-кода дома сохранять адрес одной строкой — иначе не получится восстановить адрес, когда ФИАС-код изменится.

По КЛАДР-коду метод ищет только до улицы, потому что в ФИАС нет КЛАДР-кодов домов.

Параметры вызова

Пример вызова

Пример ответа

Описание ответа

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Работа с именами

ФИО

DaDataName::fias(string $name) Разбивает ФИО из строки по отдельным полям (фамилия, имя, отчество). Определяет пол и склоняет по падежам.

Основные кейсы

• Исправляет опечатки и транслитерирует.
• Проставляет пол.
• Склоняет по падежам (кого? кому? кем?).

Параметры вызова

Пример вызова

Пример ответа

Описание ответа

Коды проверки (параметр ответа qc)

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Автодополнение при вводе («подсказки»)

DaDataName::prompt(string $name, int $count, int $gender, array $parts) Помогает человеку быстро ввести ФИО на веб-форме или в приложении.

Основные кейсы

• Подсказывает ФИО одной строкой или отдельно фамилию, имя, отчество.
• Исправляет клавиатурную раскладку («fynjy» → «Антон»).
• Определяет пол.

Метод не предназначен для выполнения следующих задач

• Автоматически (без участия человека) обработать ФИО из базы или файла.
• Транслитерировать (Juliia Somova → Юлия Сомова).
• Склонять по падежам (кого? кому? кем?).

Подсказки не подходят для автоматической обработки ФИО. Они предлагают варианты, но не гарантируют, что угадали правильно. Поэтому окончательное решение всегда должен принимать человек.

Для автоматической обработки, транслитерации и склонения по падежам используйте DaDataName::fias(string $name) метод ФИО, описание которого вы найдете выше.

Параметры вызова

Формирования массива подсказок по фасти ФИО parts Для формирования, воспользуйтесь набором констант классаа Parts.

Только имена:

Имена и отчества:

Имена и фамилии:

Пример вызова

Пример ответа

Описание ответа

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Работа с электронными (email) адресами

Email

DaDataName::email(string $email) Исправляет опечатки и проверяет на одноразовый адрес. Классифицирует адреса на личные, корпоративные и «ролевые».

Основные кейсы

• Проверяет формат адреса.
• Исправляет распространённые опечатки.
• Проверяет, не «одноразовый» ли адрес.
• Классифицирует адреса на личные (@mail.ru, @yandex.ru), корпоративные (@myshop.ru) и «ролевые» (info@, support@).

Параметры вызова

Пример вызова

Пример ответа

Описание ответа

Коды проверки (параметр ответа qc)

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Подсказки по email

DaDataEmail::prompt(string $email, int $count) Помогает человеку быстро ввести адрес электоронной почты на веб-форме или в приложении.

Основные кейсы

• Подсказывает локальную (до «собачки») и доменную (после «собачки») части эл. почты.
• Исправляет опечатки (yadex.ru → yandex.ru).

Метод не предназначен для выполнения следующих задач

• Автоматически (без участия человека) проверить адреса из базы или файла.
• Классифицировать адреса на личные (@mail.ru, @yandex.ru), корпоративные (@myshop.ru) и «ролевые» (info@, support@).
• Склонять по падежам (кого? кому? кем?).

Подсказки не подходят для автоматической обработки email. Они предлагают варианты, но не гарантируют, что угадали правильно. Поэтому окончательное решение всегда должен принимать человек.

Для автоматической обработки и классификации адресов используйте DaDataName::email(string $email)

Параметры вызова

Пример вызова

Пример ответа

Описание ответа

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Работа с телефонными номерами

Проверить телефон

DaDataPhone::standardization(string $phone); Проверяет телефон по справочнику Россвязи, определяет оператора с учётом переноса номеров, заполняет страну, город и часовой пояс.

Основные кейсы

• Проверяет телефон.
• Проставляет актуальный код города / DEF-код.
• Восстанавливает оператора. Учитывает переносы номера между операторами.
• Определяет страну, регион, город и часовой пояс.

Параметры вызова

Пример вызова

Пример ответа

Описание ответа

Коды проверки qc

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Работа с компаниями

Организация по ИНН

DaDataCompany::id(string $id', int $count, string $kpp, int $branch_type, int $type) - Находит компанию или индивидуального предпринимателя по ИНН, КПП, ОГРН. Возвращает реквизиты компании, учредителей, руководителей, сведения о налоговой, ПФР и ФСС, финансы, лицензии, реестр МСП и другую информацию о компании.

Находит компанию или ИП по ИНН или ОГРН. Возвращает все доступные сведения о компании, в отличие от метода suggest, который возвращает только базовые поля.

Пример вызова

Параметры вызова

Пример ответа

Описание ответа

Таблицу описания полного ответа вы можете получить на старнице Организация по ИНН или ОГРН в разделе "Что в ответе".

Описани ответа data['address']

Координаты есть у 97% домов в Москве, 91% в Санкт-Петербурге, 69% в других городах-миллиониках и 47% по остальной России. Площадь и стоимость есть у 70% квартир в России.

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Автодополнение при вводе («подсказки»)

DaDataCompany::prompt(string $company, int $count, array $status, int $type, string $locations, string $locations_boost); Помогает человеку быстро ввести реквизиты организации на веб-форме или в приложении.

Ищет компании и индивидуальных предпринимателей:

• По ИНН, ОГРН и КПП;
• Названию (полному и краткому);
• ФИО (для индивидуальных предпринимателей);
• ФИО руководителя компании;
• Адресу до улицы;

Основные кейсы:

• Ищет по комбинации ИНН, названия и адреса в одном запросе («7736050003 Газ» → «ПАО Газпром», «вавилова сбер» → «ПАО Сбербанк»).
• Находит конкретный филиал, если указать в запросе КПП («сбербанк 540602001» → «Сибирский банк ПАО Сбербанк»).
• Понимает слитное и раздельное написание («альфабанк» = «Альфа-Банк»).
• Ищет по частичному совпадению в ИНН / ОГРН («77094209» → «ООО Акварель») и названиях («росне» → «ПАО «НК «Роснефть»).
• Подсказывает только организации или только ИП, или и тех и других. Умеет искать только в действующих или ликвидированных компаниях. Может ограничить подсказки конкретным регионом России.
• Учитывает, где вы находитесь (в связке с методом Определение адреса по IP).
• Возвращает основные реквизиты компании из ЕГРЮЛ: краткое и полное название, ОПФ, адрес, ОГРН, ИНН, КПП, ОКВЭД, статус организации, ФИО и должность руководителя.
• В связке с методом Организация по ИНН возвращает вагон дополнительной информации: количество сотрудников, все коды ОКВЭД, сведения о налоговой, ПФР и ФСС, документы и лицензии, учредители и руководители, финансовые показатели, реестр малого и среднего бизнеса.

Данный метод не прдназначен:

• ля 50% компаний налоговая служба пока не сообщает КПП филиалов. Такие филиалы можно найти по ИНН, городу и улице филиала. Например, «7724261610 москва мясницкая» → «Филиал ФГУП "Почта России" (г Москва)».

Пример вызова

Параметры вызова

Формирование status - ограничение по статусу организации Чтобы искать только действующие компании, сформироуйте массив status как

Поиск только среди ликвидируемых и ликвидированных компаний:

Формирование type - Ограничение по типу организации.

Тип поиска только по юридическим лицам

Тип поиска только по индивидуальным предпринимателям

Пример ответа

Описание ответа

Таблицу описания полного ответа вы можете получить на старнице API подсказок по организациям в разделе "Что в ответе".

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Поиск аффилированных компаний

DaDataCompany::affiliated(string $code, int $count, array $scope) Находит организации по ИНН учредителей и руководителей. Работает для физлиц и юрлиц.

Часто учредитель или директор не ограничивается участием в одном юрлице, а фигурирует в нескольких. Порой — в десятках разных компаний. Знать об этом полезно как для оценки надёжности контрагента, так и для более эффективного маркетинга и продаж. Чтобы облегчить поиск аффилированных компаний, «Дадата» находит организации по ИНН учредителей и руководителей.

Ищет по ИНН физлиц и юрлиц.

Данный метод не удается протестировать из-за того, что все получаем 403, Operation party/findAffiliated is not permitted

Пример вызова

Параметры вызова

Формирование scope -

Описание ответа

Таблицу описания полного ответа вы можете получить на старнице Поиск аффилированных компаний в разделе "Что в ответе".

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Работа с банками

Банк по БИК, SWIFT, ИНН или регистрационному номеру

DaDataBank::id(string $bank); Находит банк по любому из идентификаторов: БИК, SWIFT, ИНН, ИНН + КПП (для филиалов), рег. номеру, присвоенному Банком России. Возвращает реквизиты банка, корр. счёт, адрес и статус (действующий / на ликвидации).

Ищет кредитные организации по:

• БИК;
• SWIFT;
• ИНН;
• ИНН плюс КПП;
• Названию;

Ищет только по точному совпадению, для частичного совпадения используйте метод DaDataBank::prompt(string $bank, int $count, array $status, array $type, string $locations, string $locations_boost)

Пример вызова

Параметры вызова

Пример ответа

Описание ответа

Таблицу описания полного ответа вы можете получить на старнице Банк по БИК, SWIFT, ИНН или регистрационному номеру в разделе "Что в ответе".

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

API подсказок по банкам

DaDataBank::prompt(string $bank, int $count, array $status, array $type, string $locations, string $locations_boost) Помогает человеку быстро ввести реквизиты банка на веб-форме или в приложении.

Ищет кредитные организации по:

• БИК;
• SWIFT;
• ИНН;
• ИНН плюс КПП;
• Названию;

Основные кейсы:

• Фильтрует по типу: банки, НКО и филиалы, а также РКЦ и другие организации;
• Умеет искать как действующие банки, так и банки на ликвидации;
• Учитывает, где вы находитесь (геолокация до города);

Пример вызова

Параметры вызова

Формирование status - ограничение по статусу организации Чтобы искать только действующие банки, сформироуйте массив status как

Поиск только среди ликвидируемых и ликвидированных банков:

Формирование type - Ограничение по типу банка. Доступные типы организаций в классе SushiMarket\DaData\Enums\BankType

Тип поиска только по банкам и филиалам банков

Тип поиска только по РКЦ/ГРКЦ

Пример ответа

Описание ответа

Таблицу описания полного ответа вы можете получить на старнице API подсказок по банкамм в разделе "Что в ответе".

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Работа с паспортами

Проверка по реестру МВД

DaDataPassport::standardization(string $id) Проверяет паспорт по справочнику недействительных паспортов МВД.

Основные кейсы:

• Проверяет формат серии и номера;
• Проверяет паспорт по справочнику недействительных паспортов МВД;

Пример вызова

Параметры вызова

Пример ответа

Описание ответа

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения

Кем выдан паспорт

DaDataPassport::fns(string $passport, int $count) Моментально заполняет организацию, выдавшую паспорт, по коду подразделения

Самое утомительное поле при вводе паспорта — «Кем выдан». Писать какое-нибудь «Отделом внутренних дел Медведевского района республики Марий Эл» муторно. Поэтому мы сделали подсказки по полю «Паспорт выдан...».

Пример вызова

Параметры вызова

Пример ответа

Описание ответа

Exceptions

При вызове методов, вы можете обрабатывать коды исключений и их сообщения

Более детальную информацию вы можете получить из сообщения исключения.

Пример получения сообщения исключения