Feature/590 add catalog.vat

.php-cs-fixer.php

@@ -38,6 +38,7 @@
     ->in(__DIR__ . '/src/Services/Sign/')
     ->in(__DIR__ . '/src/Services/Messageservice/')
     ->in(__DIR__ . '/src/Services/MailService/')
+    ->in(__DIR__ . '/src/Services/Catalog/')
     ->name('*.php')
     ->exclude(['vendor', 'storage', 'docker', 'docs']) // Exclude directories
     ->ignoreDotFiles(true)

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+### Added
+
+- Added service `Services\Catalog\Vat\Service\Vat` with support methods,
+  see [catalog.vat.* methods](https://apidocs.bitrix24.com/api-reference/catalog/vat/index.html) ([#590](https://github.com/bitrix24/b24phpsdk/issues/590)):
+    - `add` creates a new VAT rate, with batch calls support
+    - `update` updates an existing VAT rate by its identifier, with batch calls support
+    - `get` returns VAT rate information by identifier
+    - `list` returns a list of VAT rates by filter
+    - `delete` deletes a VAT rate by identifier, with batch calls support
+    - `getFields` returns the description of VAT rate fields
+
 ## 1.11.0 - 2026.08.31
 
 ### Added

Makefile

@@ -807,6 +807,10 @@ test-integration-biconnector-source:
 test-integration-biconnector-dataset:
 	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_biconnector_dataset
 
+.PHONY: test-integration-catalog-vat
+test-integration-catalog-vat:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_catalog_vat
+
 # work dev environment
 .PHONY: php-dev-server-up
 php-dev-server-up:

phpunit.xml.dist

@@ -498,6 +498,9 @@
             <directory>./tests/Integration/Services/Biconnector/Dataset/Service/</directory>
             <directory>./tests/Integration/Services/Biconnector/Dataset/Result/</directory>
         </testsuite>
+        <testsuite name="integration_tests_catalog_vat">
+            <directory>./tests/Integration/Services/Catalog/Vat/</directory>
+        </testsuite>
     </testsuites>
     <source>
         <include>

src/Services/Catalog/CatalogServiceBuilder.php

@@ -266,4 +266,20 @@ public function productPropertyFeature(): Catalog\ProductPropertyFeature\Service
 
         return $this->serviceCache[__METHOD__];
     }
+
+    public function vat(): Catalog\Vat\Service\Vat
+    {
+        if (!isset($this->serviceCache[__METHOD__])) {
+            $this->serviceCache[__METHOD__] = new Catalog\Vat\Service\Vat(
+                new Catalog\Vat\Service\Batch(
+                    new Catalog\Vat\Batch($this->core, $this->log),
+                    $this->log
+                ),
+                $this->core,
+                $this->log
+            );
+        }
+
+        return $this->serviceCache[__METHOD__];
+    }
 }

src/Services/Catalog/Vat/Batch.php

@@ -0,0 +1,108 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@gmail.com>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Catalog\Vat;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Exceptions\InvalidArgumentException;
+use Bitrix24\SDK\Core\Response\DTO\ResponseData;
+use Generator;
+
+/**
+ * Class Batch
+ *
+ * Overrides base Batch to handle parameter naming differences in catalog.vat.* REST methods:
+ * - delete uses lowercase 'id' instead of 'ID'
+ *
+ * @see https://apidocs.bitrix24.com/api-reference/catalog/vat/catalog-vat-delete.html
+ * @see https://apidocs.bitrix24.com/api-reference/catalog/vat/catalog-vat-list.html
+ */
+class Batch extends \Bitrix24\SDK\Core\Batch
+{
+    /**
+     * Determines the ID key — lowercase 'id' for catalog VAT rate
+     */
+    #[\Override]
+    protected function determineKeyId(string $apiMethod, ?array $additionalParameters): string
+    {
+        return 'id';
+    }
+
+    /**
+     * Delete entity items with batch call using lowercase 'id' parameter
+     *
+     * @param int[]             $entityItemId
+     * @param array<mixed>|null $additionalParameters
+     *
+     * @return Generator<int, ResponseData>|ResponseData[]
+     * @throws BaseException
+     */
+    #[\Override]
+    public function deleteEntityItems(
+        string $apiMethod,
+        array $entityItemId,
+        ?array $additionalParameters = null
+    ): Generator {
+        $this->logger->debug(
+            'deleteEntityItems.start',
+            [
+                'apiMethod' => $apiMethod,
+                'entityItems' => $entityItemId,
+                'additionalParameters' => $additionalParameters,
+            ]
+        );
+
+        try {
+            $this->clearCommands();
+            foreach ($entityItemId as $cnt => $itemId) {
+                if (!is_int($itemId)) {
+                    throw new InvalidArgumentException(
+                        sprintf(
+                            'invalid type «%s» of VAT rate id «%s» at position %s, VAT rate id must be integer type',
+                            gettype($itemId),
+                            $itemId,
+                            $cnt
+                        )
+                    );
+                }
+
+                $this->registerCommand($apiMethod, ['id' => $itemId]);
+            }
+
+            foreach ($this->getTraversable(true) as $cnt => $deletedItemResult) {
+                yield $cnt => $deletedItemResult;
+            }
+        } catch (InvalidArgumentException $exception) {
+            $errorMessage = sprintf('batch delete VAT rate items: %s', $exception->getMessage());
+            $this->logger->error(
+                $errorMessage,
+                [
+                    'trace' => $exception->getTrace(),
+                ]
+            );
+            throw $exception;
+        } catch (\Throwable $exception) {
+            $errorMessage = sprintf('batch delete VAT rate items: %s', $exception->getMessage());
+            $this->logger->error(
+                $errorMessage,
+                [
+                    'trace' => $exception->getTrace(),
+                ]
+            );
+
+            throw new BaseException($errorMessage, $exception->getCode(), $exception);
+        }
+
+        $this->logger->debug('deleteEntityItems.finish');
+    }
+}

src/Services/Catalog/Vat/Result/VatAddedBatchResult.php

@@ -0,0 +1,33 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@gmail.com>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Catalog\Vat\Result;
+
+use Bitrix24\SDK\Core\Response\DTO\ResponseData;
+
+class VatAddedBatchResult
+{
+    public function __construct(private readonly ResponseData $responseData)
+    {
+    }
+
+    public function getResponseData(): ResponseData
+    {
+        return $this->responseData;
+    }
+
+    public function vat(): VatItemResult
+    {
+        return new VatItemResult($this->responseData->getResult()['vat']);
+    }
+}

src/Services/Catalog/Vat/Result/VatFieldsResult.php

@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@gmail.com>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Catalog\Vat\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class VatFieldsResult extends AbstractResult
+{
+    /**
+     * @return array<string, array<string, mixed>>
+     * @throws BaseException
+     */
+    public function getFieldsDescription(): array
+    {
+        return $this->getCoreResponse()->getResponseData()->getResult()['vat'];
+    }
+}

src/Services/Catalog/Vat/Result/VatItemResult.php

@@ -0,0 +1,45 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@gmail.com>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Catalog\Vat\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractItem;
+use Carbon\CarbonImmutable;
+
+/**
+ * @property-read int                  $id
+ * @property-read string               $name
+ * @property-read bool                 $active
+ * @property-read float                $rate
+ * @property-read int                  $sort
+ * @property-read CarbonImmutable|null $timestampX
+ */
+class VatItemResult extends AbstractItem
+{
+    /**
+     * @param int|string $offset
+     *
+     * @return bool|CarbonImmutable|float|mixed|null
+     */
+    public function __get($offset)
+    {
+        return match ($offset) {
+            'active' => $this->data[$offset] === 'Y',
+            'rate' => (float)$this->data[$offset],
+            'timestampX' => $this->data[$offset] !== null && $this->data[$offset] !== ''
+                ? CarbonImmutable::createFromFormat(DATE_ATOM, $this->data[$offset])
+                : null,
+            default => $this->data[$offset] ?? null,
+        };
+    }
+}

src/Services/Catalog/Vat/Result/VatResult.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@gmail.com>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Catalog\Vat\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class VatResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function vat(): VatItemResult
+    {
+        return new VatItemResult($this->getCoreResponse()->getResponseData()->getResult()['vat']);
+    }
+}

src/Services/Catalog/Vat/Result/VatUpdatedBatchResult.php

@@ -0,0 +1,33 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@gmail.com>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Catalog\Vat\Result;
+
+use Bitrix24\SDK\Core\Response\DTO\ResponseData;
+
+class VatUpdatedBatchResult
+{
+    public function __construct(private readonly ResponseData $responseData)
+    {
+    }
+
+    public function getResponseData(): ResponseData
+    {
+        return $this->responseData;
+    }
+
+    public function vat(): VatItemResult
+    {
+        return new VatItemResult($this->responseData->getResult()['vat']);
+    }
+}

src/Services/Catalog/Vat/Result/VatsResult.php

@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * This file is part of the bitrix24-php-sdk package.
+ *
+ * © Dmitriy Ignatenko <algonexys@gmail.com>
+ *
+ * For the full copyright and license information, please view the MIT-LICENSE.txt
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Services\Catalog\Vat\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class VatsResult extends AbstractResult
+{
+    /**
+     * @return VatItemResult[]
+     * @throws BaseException
+     */
+    public function getVats(): array
+    {
+        $result = $this->getCoreResponse()->getResponseData()->getResult();
+
+        return array_map(
+            static fn (array $item): VatItemResult => new VatItemResult($item),
+            $result['vats'] ?? []
+        );
+    }
+}