added method findAffiliatedParty, update phpDoc (#3)

* added new fields in PartyResponse (okato, oktmo, okogu, okfs)

* added new method findAffiliatedParty

* fix geolocate models

* remove IplocateRequest, update AddressRequest

* update phpdoc

README.md

@@ -150,4 +150,15 @@ $city = $response->value;
 ```php
 $response = $dadataSuggest->findAddress('77000000000268400');
 $address = $response[0]->value;
-```
+```
+
+### [Поиск аффилированных компаний](https://dadata.ru/api/find-affiliated/)
+
+```php
+$response = $dadataSuggest->findAffiliatedParty('7736207543');
+$value = $response[0]->value;
+```
+
+## Лицензия
+
+[MIT License](https://opensource.org/licenses/mit-license) © Velhron

src/Model/Request/Find/AffiliatedPartyRequest.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Velhron\DadataBundle\Model\Request\Find;
+
+use Velhron\DadataBundle\Model\Request\Suggest\SuggestRequest;
+
+class AffiliatedPartyRequest extends SuggestRequest
+{
+    /**
+     * @var string[] Ограничение области поиска (FOUNDERS / MANAGERS)
+     */
+    protected $scope;
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getBaseUrl(): string
+    {
+        return 'https://suggestions.dadata.ru/suggestions/api/4_1/rs/findAffiliated/';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function getMethodUrl(): string
+    {
+        return 'party';
+    }
+}

src/Model/Request/Geolocate/AddressRequest.php

@@ -6,11 +6,6 @@
 
 class AddressRequest extends GeolocateRequest
 {
-    /**
-     * @var int Радиус поиска в метрах (максимум – 1000)
-     */
-    protected $radius_meters;
-
     /**
      * @var string На каком языке вернуть результат (ru / en)
      */

src/Model/Request/Geolocate/GeolocateRequest.php

@@ -18,6 +18,11 @@ abstract class GeolocateRequest extends SuggestRequest
      */
     protected $lon;
 
+    /**
+     * @var int Радиус поиска в метрах
+     */
+    protected $radius_meters;
+
     /**
      * {@inheritdoc}
      */

src/Model/Request/Geolocate/PostalUnitRequest.php

@@ -6,11 +6,6 @@
 
 class PostalUnitRequest extends GeolocateRequest
 {
-    /**
-     * @var int Радиус поиска в метрах (максимум – 1000)
-     */
-    protected $radius_meters;
-
     /**
      * {@inheritdoc}
      */

src/Model/Request/Iplocate/AddressRequest.php

@@ -4,8 +4,18 @@
 
 namespace Velhron\DadataBundle\Model\Request\Iplocate;
 
-class AddressRequest extends IplocateRequest
+use Velhron\DadataBundle\Model\Request\Suggest\SuggestRequest;
+
+class AddressRequest extends SuggestRequest
 {
+    /**
+     * {@inheritdoc}
+     */
+    public function getBaseUrl(): string
+    {
+        return 'https://suggestions.dadata.ru/suggestions/api/4_1/rs/iplocate/';
+    }
+
     /**
      * {@inheritdoc}
      */

src/Model/Response/Find/AffiliatedPartyResponse.php

@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Velhron\DadataBundle\Model\Response\Find;
+
+use Velhron\DadataBundle\Model\Response\Suggest\AddressResponse;
+use Velhron\DadataBundle\Model\Response\Suggest\SuggestResponse;
+
+class AffiliatedPartyResponse extends SuggestResponse
+{
+    /**
+     * @var string ИНН
+     */
+    public $inn;
+
+    /**
+     * @var string КПП
+     */
+    public $kpp;
+
+    /**
+     * @var string ОГРН
+     */
+    public $ogrn;
+
+    /**
+     * @var string Уникальный идентификатор в Дадате
+     */
+    public $hid;
+
+    /**
+     * @var string Тип организации (LEGAL — юридическое лицо, INDIVIDUAL — индивидуальный предприниматель)
+     */
+    public $type;
+
+    /**
+     * @var string Код ОКАТО
+     */
+    public $okato;
+
+    /**
+     * @var string Код ОКТМО
+     */
+    public $oktmo;
+
+    /**
+     * @var string Код ОКПО
+     */
+    public $okpo;
+
+    /**
+     * @var string Код ОКОГУ
+     */
+    public $okogu;
+
+    /**
+     * @var string Код ОКФС
+     */
+    public $okfs;
+
+    /**
+     * @var string Код ОКВЭД
+     */
+    public $okved;
+
+    /**
+     * @var string Версия справочника ОКВЭД (2001 или 2014)
+     */
+    public $okvedType;
+
+    /**
+     * @var string Количество филиалов
+     */
+    public $branchCount;
+
+    /**
+     * @var string Тип подразделения (MAIN — головная организация, BRANCH — филиал)
+     */
+    public $branchType;
+
+    /**
+     * @var AddressResponse Адрес одной строкой
+     */
+    public $address;
+
+    /**
+     * @var array Состояние
+     */
+    public $state;
+
+    public function __construct(array $data)
+    {
+        parent::__construct($data);
+
+        if (isset($data['data']['address'])) {
+            $this->address = new AddressResponse($data['data']['address']);
+        }
+    }
+}

src/Model/Response/Suggest/PartyResponse.php

@@ -41,11 +41,31 @@ class PartyResponse extends SuggestResponse
      */
     public $name;
 
+    /**
+     * @var string Код ОКАТО
+     */
+    public $okato;
+
+    /**
+     * @var string Код ОКТМО
+     */
+    public $oktmo;
+
     /**
      * @var string Код ОКПО
      */
     public $okpo;
 
+    /**
+     * @var string Код ОКОГУ
+     */
+    public $okogu;
+
+    /**
+     * @var string Код ОКФС
+     */
+    public $okfs;
+
     /**
      * @var string Код ОКВЭД
      */

src/Resources/config/services.yaml

@@ -114,6 +114,10 @@ services:
           request: Velhron\DadataBundle\Model\Request\Find\FiasRequest
           response: Velhron\DadataBundle\Model\Response\Suggest\AddressResponse
 
+        - name: 'findAffiliatedParty'
+          request: Velhron\DadataBundle\Model\Request\Find\AffiliatedPartyRequest
+          response: Velhron\DadataBundle\Model\Response\Find\AffiliatedPartyResponse
+
         - name: 'geolocateAddress'
           request: Velhron\DadataBundle\Model\Request\Geolocate\AddressRequest
           response: Velhron\DadataBundle\Model\Response\Suggest\AddressResponse

src/Service/DadataClean.php

@@ -68,6 +68,10 @@ protected function query(AbstractRequest $request): array
      * - Определяет округ и район города, геокоординаты, метро, площадь и стоимость квартиры.
      * - Достает коды КЛАДР, ФИАС, ОКАТО, ОКТМО и ИФНС.
      *
+     * @param string $query Текст запроса
+     *
+     * @return AddressResponse Стандартизованный объект
+     *
      * @throws DadataException
      */
     public function cleanAddress(string $query): AddressResponse
@@ -78,6 +82,13 @@ public function cleanAddress(string $query): AddressResponse
     /**
      * Стандартизация телефона.
      *
+     * Проверяет телефон по справочнику Россвязи.
+     * Определяет оператора с учётом переноса номеров, заполняет страну, город и часовой пояс.
+     *
+     * @param string $query Текст запроса
+     *
+     * @return PhoneResponse Стандартизованный объект
+     *
      * @throws DadataException
      */
     public function cleanPhone(string $query): PhoneResponse
@@ -88,6 +99,12 @@ public function cleanPhone(string $query): PhoneResponse
     /**
      * Стандартизация паспорта.
      *
+     * Проверяет паспорт по справочнику недействительных паспортов МВД.
+     *
+     * @param string $query Текст запроса
+     *
+     * @return PassportResponse Стандартизованный объект
+     *
      * @throws DadataException
      */
     public function cleanPassport(string $query): PassportResponse
@@ -98,6 +115,10 @@ public function cleanPassport(string $query): PassportResponse
     /**
      * Стандартизация даты рождения.
      *
+     * @param string $query Текст запроса
+     *
+     * @return BirthdateResponse Стандартизованный объект
+     *
      * @throws DadataException
      */
     public function cleanBirthdate(string $query): BirthdateResponse
@@ -108,6 +129,10 @@ public function cleanBirthdate(string $query): BirthdateResponse
     /**
      * Стандартизация автомобиля.
      *
+     * @param string $query Текст запроса
+     *
+     * @return VehicleResponse Стандартизованный объект
+     *
      * @throws DadataException
      */
     public function cleanVehicle(string $query): VehicleResponse
@@ -118,6 +143,12 @@ public function cleanVehicle(string $query): VehicleResponse
     /**
      * Стандартизация ФИО.
      *
+     * Разбивает ФИО из строки по отдельным полям (фамилия, имя, отчество). Определяет пол и склоняет по падежам.
+     *
+     * @param string $query Текст запроса
+     *
+     * @return NameResponse Стандартизованный объект
+     *
      * @throws DadataException
      */
     public function cleanName(string $query): NameResponse
@@ -128,6 +159,13 @@ public function cleanName(string $query): NameResponse
     /**
      * Стандартизация e-mail.
      *
+     * Исправляет опечатки и проверяет на одноразовый адрес.
+     * Классифицирует адреса на личные, корпоративные и «ролевые».
+     *
+     * @param string $query Текст запроса
+     *
+     * @return EmailResponse Стандартизованный объект
+     *
      * @throws DadataException
      */
     public function cleanEmail(string $query): EmailResponse

src/Service/DadataGeneral.php

@@ -39,6 +39,8 @@ protected function query(AbstractRequest $request): array
      *
      * Возвращает сумму в рублях с точностью до копеек, десятичный разделитель — точка.
      *
+     * @return float Текущий баланс счета
+     *
      * @throws DadataException
      */
     public function balance(): float
@@ -53,9 +55,13 @@ public function balance(): float
      *
      * Дата должна быть задана в формате YYYY-MM-DD. По умолчанию, сегодня.
      *
+     * @param string|null $date Дата в формате YYYY-MM-DD
+     *
+     * @return StatResponse Статистика
+     *
      * @throws DadataException
      */
-    public function stat(string $date = ''): StatResponse
+    public function stat(string $date = null): StatResponse
     {
         $request = new StatRequest();
         $request->date = $date;
@@ -67,6 +73,8 @@ public function stat(string $date = ''): StatResponse
     /**
      * Возвращает даты актуальности справочников (ФИАС, ЕГРЮЛ, банки и другие).
      *
+     * @return array Информация по датам актуальности справочников
+     *
      * @throws DadataException
      */
     public function version(): array