Feature/504 add sign.b2e

.php-cs-fixer.php

@@ -29,6 +29,7 @@
     ->in(__DIR__ . '/src/Services/SonetGroup/')
     ->in(__DIR__ . '/src/Services/IMOpenLines/')
     ->in(__DIR__ . '/src/Services/Landing/')
+    ->in(__DIR__ . '/src/Services/Sign/')
     ->name('*.php')
     ->exclude(['vendor', 'storage', 'docker', 'docs']) // Exclude directories
     ->ignoreDotFiles(true)

CHANGELOG.md

@@ -4,6 +4,16 @@
 
 ### Added
 
+- Added `Services\Sign\SignServiceBuilder` with support for `sign.b2e.*` methods and events,
+  see [sign.b2e.* methods](https://apidocs.bitrix24.com/api-reference/sign/index.html) ([#504](https://github.com/bitrix24/b24phpsdk/issues/504)):
+    - `document()->send()` — sends a document for company-side signing (КЭДО), application context only
+    - `document()->get()` — returns information about a document and its signing members
+    - `companyProvider()->list()` — returns the list of signature providers for a selected company
+    - `personalTail()->tail()` — returns the list of signed documents for the current user (КЭДО section), application context only
+    - `mySafeTail()->tail()` — returns the list of signed documents in the company safe, application context only
+- Added events support for `sign.b2e` scope via `SignB2eEventsFactory` ([#504](https://github.com/bitrix24/b24phpsdk/issues/504)):
+    - `OnSignB2eDocumentStatusChanged` — fires when document status changes
+    - `OnSignB2eMemberStatusChanged` — fires when member status changes
 - Added service `Services\Landing\Site\Service\Site` with support methods,
   see [landing.site.* methods](https://github.com/bitrix24/b24phpsdk/issues/267):
     - `add` adds a site

Makefile

@@ -69,7 +69,11 @@ help:
 	@echo "test-integration-landing-role - run Landing Role integration tests"
 	@echo "test-integration-landing-repowidget - run Landing RepoWidget integration tests"
 	@echo "test-integration-scope-landing-template - run Landing Template integration tests"
-
+	@echo "test-integration-scope-sign - run Sign B2e integration tests"
+	@echo "test-integration-sign-document - run Sign Document integration tests"
+	@echo "test-integration-sign-company-provider - run Sign CompanyProvider integration tests"
+	@echo "test-integration-sign-personal-tail - run Sign PersonalTail integration tests"
+	@echo "test-integration-sign-mysafe-tail - run Sign MySafeTail integration tests"
 
 .PHONY: docker-init
 docker-init:
@@ -492,6 +496,26 @@ test-integration-landing-role:
 test-integration-landing-repowidget:
 	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_landing_repowidget
 
+.PHONY: test-integration-scope-sign
+test-integration-scope-sign:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_scope_sign
+
+.PHONY: test-integration-sign-document
+test-integration-sign-document:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_sign_document
+
+.PHONY: test-integration-sign-company-provider
+test-integration-sign-company-provider:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_sign_company_provider
+
+.PHONY: test-integration-sign-personal-tail
+test-integration-sign-personal-tail:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_sign_personal_tail
+
+.PHONY: test-integration-sign-mysafe-tail
+test-integration-sign-mysafe-tail:
+	docker compose run --rm php-cli vendor/bin/phpunit --testsuite integration_tests_sign_mysafe_tail
+
 # work dev environment
 .PHONY: php-dev-server-up
 php-dev-server-up:

phpstan.neon.dist

@@ -37,6 +37,7 @@ parameters:
     - tests/Integration/Services/CRM/Documentgenerator/Document
     - tests/Integration/Services/CRM/Documentgenerator/Template
     - tests/Integration/Services/Landing
+    - tests/Integration/Services/Sign
   excludePaths:
     - tests/Integration/Services/CRM/Requisites/Service/RequisiteUserfieldUseCaseTest.php
     - tests/Integration/Services/CRM/Status

phpunit.xml.dist

@@ -262,6 +262,25 @@
         <testsuite name="integration_tests_landing_repowidget">
             <directory>./tests/Integration/Services/Landing/RepoWidget/</directory>
         </testsuite>
+        <testsuite name="integration_tests_scope_sign">
+            <directory>./tests/Integration/Services/Sign/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_sign_document">
+            <directory>./tests/Integration/Services/Sign/B2e/Document/Service/</directory>
+            <directory>./tests/Integration/Services/Sign/B2e/Document/Result/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_sign_company_provider">
+            <directory>./tests/Integration/Services/Sign/B2e/CompanyProvider/Service/</directory>
+            <directory>./tests/Integration/Services/Sign/B2e/CompanyProvider/Result/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_sign_personal_tail">
+            <directory>./tests/Integration/Services/Sign/B2e/PersonalTail/Service/</directory>
+            <directory>./tests/Integration/Services/Sign/B2e/PersonalTail/Result/</directory>
+        </testsuite>
+        <testsuite name="integration_tests_sign_mysafe_tail">
+            <directory>./tests/Integration/Services/Sign/B2e/MySafeTail/Service/</directory>
+            <directory>./tests/Integration/Services/Sign/B2e/MySafeTail/Result/</directory>
+        </testsuite>
     </testsuites>
     <source>
         <include>

rector.php

@@ -78,6 +78,8 @@
         __DIR__ . '/tests/Integration/Services/CRM/Documentgenerator/Template',
         __DIR__ . '/src/Services/Landing',
         __DIR__ . '/tests/Integration/Services/Landing',
+        __DIR__ . '/src/Services/Sign',
+        __DIR__ . '/tests/Integration/Services/Sign',
         __DIR__ . '/tests/Unit/',
     ])
     ->withCache(cacheDirectory: __DIR__ . '/var/.cache/rector')

src/Services/RemoteEventsFactory.php

@@ -30,6 +30,7 @@
 use Bitrix24\SDK\Services\IMOpenLines\Connector\Events\ImConnectorEventsFactory;
 use Bitrix24\SDK\Services\Task\Events\TaskEventsFactory;
 use Bitrix24\SDK\Services\Sale\Events\SaleEventsFactory;
+use Bitrix24\SDK\Services\Sign\Events\SignB2eEventsFactory;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\HttpFoundation\Request;
 
@@ -159,6 +160,7 @@ public function createEvent(Request $request, ?string $applicationToken): EventI
             ]);
             throw new InvalidArgumentException('key «event» not found in request payload');
         }
+
         if ($applicationToken !== null && trim($applicationToken) === '') {
             throw new InvalidArgumentException('application token cannot be empty');
         }
@@ -230,8 +232,9 @@ public static function init(LoggerInterface $logger): self
                 new SaleEventsFactory(),
                 new ImConnectorEventsFactory(),
                 new TaskEventsFactory(),
+                new SignB2eEventsFactory(),
             ],
             $logger
         );
     }
-}
+}

src/Services/ServiceBuilder.php

@@ -37,6 +37,7 @@
 use Bitrix24\SDK\Services\Paysystem\PaysystemServiceBuilder;
 use Bitrix24\SDK\Services\SonetGroup\SonetGroupServiceBuilder;
 use Bitrix24\SDK\Services\Landing\LandingServiceBuilder;
+use Bitrix24\SDK\Services\Sign\SignServiceBuilder;
 use Psr\Log\LoggerInterface;
 
 class ServiceBuilder extends AbstractServiceBuilder
@@ -349,4 +350,18 @@ public function getLandingScope(): LandingServiceBuilder
 
         return $this->serviceCache[__METHOD__];
     }
+
+    public function getSignScope(): SignServiceBuilder
+    {
+        if (!isset($this->serviceCache[__METHOD__])) {
+            $this->serviceCache[__METHOD__] = new SignServiceBuilder(
+                $this->core,
+                $this->batch,
+                $this->bulkItemsReader,
+                $this->log
+            );
+        }
+
+        return $this->serviceCache[__METHOD__];
+    }
 }

src/Services/Sign/B2e/CompanyProvider/Result/CompanyProviderItemResult.php

@@ -0,0 +1,37 @@
+<?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\Sign\B2e\CompanyProvider\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractItem;
+use Carbon\CarbonImmutable;
+
+/**
+ * @property-read string|null $code Signature provider code
+ * @property-read string|null $uid Unique identifier of the provider
+ * @property-read string|null $name Provider display name
+ * @property-read CarbonImmutable|null $date Provider activation date
+ * @property-read CarbonImmutable|null $expires Provider expiration date
+ */
+class CompanyProviderItemResult extends AbstractItem
+{
+    public function __get($offset)
+    {
+        return match ($offset) {
+            'date', 'expires' => empty($this->data[$offset])
+                ? null
+                : CarbonImmutable::parse($this->data[$offset]),
+            default => $this->data[$offset] ?? null,
+        };
+    }
+}

src/Services/Sign/B2e/CompanyProvider/Result/CompanyProvidersResult.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\Sign\B2e\CompanyProvider\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class CompanyProvidersResult extends AbstractResult
+{
+    /**
+     * @return CompanyProviderItemResult[]
+     * @throws BaseException
+     */
+    public function getProviders(): array
+    {
+        $items = [];
+        foreach ($this->getCoreResponse()->getResponseData()->getResult() as $item) {
+            $items[] = new CompanyProviderItemResult($item);
+        }
+
+        return $items;
+    }
+}

src/Services/Sign/B2e/CompanyProvider/Service/CompanyProvider.php

@@ -0,0 +1,78 @@
+<?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\Sign\B2e\CompanyProvider\Service;
+
+use Bitrix24\SDK\Attributes\ApiEndpointMetadata;
+use Bitrix24\SDK\Attributes\ApiServiceMetadata;
+use Bitrix24\SDK\Core\Contracts\CoreInterface;
+use Bitrix24\SDK\Core\Credentials\Scope;
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Exceptions\TransportException;
+use Bitrix24\SDK\Services\AbstractService;
+use Bitrix24\SDK\Services\Sign\B2e\CompanyProvider\Result\CompanyProvidersResult;
+use Psr\Log\LoggerInterface;
+
+#[ApiServiceMetadata(new Scope(['sign.b2e']))]
+class CompanyProvider extends AbstractService
+{
+    public function __construct(CoreInterface $core, LoggerInterface $logger)
+    {
+        parent::__construct($core, $logger);
+    }
+
+    /**
+     * Returns the list of signature providers for a selected company.
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/sign/sign-b2e-company-provider-list.html
+     *
+     * @param string|null $companyUuid Company UUID in HCM Link (required if companyCrmId is not provided)
+     * @param int|null $companyCrmId Company CRM identifier (required if companyUuid is not provided)
+     * @param string|null $language Language for provider name localisation (default: en)
+     * @param int $limit Number of records per page (1–1000, default: 100)
+     * @param int $offset Pagination offset (default: 0)
+     *
+     * @throws BaseException
+     * @throws TransportException
+     */
+    #[ApiEndpointMetadata(
+        'sign.b2e.company.provider.list',
+        'https://apidocs.bitrix24.com/api-reference/sign/sign-b2e-company-provider-list.html',
+        'Returns the list of signature providers for a selected company.'
+    )]
+    public function list(
+        ?string $companyUuid = null,
+        ?int $companyCrmId = null,
+        ?string $language = null,
+        int $limit = 100,
+        int $offset = 0
+    ): CompanyProvidersResult {
+        $params = [
+            'limit' => $limit,
+            'offset' => $offset,
+        ];
+        if ($companyUuid !== null) {
+            $params['companyUuid'] = $companyUuid;
+        }
+
+        if ($companyCrmId !== null) {
+            $params['companyCrmId'] = $companyCrmId;
+        }
+
+        if ($language !== null) {
+            $params['language'] = $language;
+        }
+
+        return new CompanyProvidersResult($this->core->call('sign.b2e.company.provider.list', $params));
+    }
+}

src/Services/Sign/B2e/Document/Result/DocumentItemResult.php

@@ -0,0 +1,25 @@
+<?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\Sign\B2e\Document\Result;
+
+use Bitrix24\SDK\Core\Result\AbstractItem;
+
+/**
+ * @property-read string|null $uid Unique identifier of the document
+ * @property-read array<string, string>|null $state Document status with 'code' and 'name' keys
+ * @property-read array<int, array<string, mixed>>|null $members List of signing members
+ */
+class DocumentItemResult extends AbstractItem
+{
+}

src/Services/Sign/B2e/Document/Result/DocumentResult.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\Sign\B2e\Document\Result;
+
+use Bitrix24\SDK\Core\Exceptions\BaseException;
+use Bitrix24\SDK\Core\Result\AbstractResult;
+
+class DocumentResult extends AbstractResult
+{
+    /**
+     * @throws BaseException
+     */
+    public function getDocument(): DocumentItemResult
+    {
+        return new DocumentItemResult($this->getCoreResponse()->getResponseData()->getResult());
+    }
+}