Support for working with customer subscriptions

src/Model/Entity/Customers/Subscription.php

@@ -0,0 +1,45 @@
+<?php
+
+/**
+ * PHP version 7.3
+ *
+ * @category Subscription
+ * @package  RetailCrm\Api\Model\Entity\Customers
+ */
+
+namespace RetailCrm\Api\Model\Entity\Customers;
+
+use RetailCrm\Api\Component\Serializer\Annotation as JMS;
+
+/**
+ * Class Subscription
+ *
+ * @category Subscription
+ * @package  RetailCrm\Api\Model\Entity\Customers
+ */
+class Subscription
+{
+    /**
+     * @var string
+     *
+     * @JMS\Type("string")
+     * @JMS\SerializedName("channel")
+     */
+    public $channel;
+
+    /**
+     * @var bool
+     *
+     * @JMS\Type("bool")
+     * @JMS\SerializedName("active")
+     */
+    public $active;
+
+    /**
+     * @var int
+     *
+     * @JMS\Type("int")
+     * @JMS\SerializedName("unsubscribeMessageId")
+     */
+    public $unsubscribeMessageId;
+}

src/Model/Request/Customers/CustomersSubscriptionsRequest.php

@@ -0,0 +1,47 @@
+<?php
+
+/**
+ * PHP version 7.3
+ *
+ * @category CustomersSubscriptionsRequest
+ * @package  RetailCrm\Api\Model\Request\Customers
+ */
+
+namespace RetailCrm\Api\Model\Request\Customers;
+
+use RetailCrm\Api\Component\FormData\Mapping as Form;
+use RetailCrm\Api\Interfaces\RequestInterface;
+
+/**
+ * Class CustomersSubscriptionsRequest
+ *
+ * @category CustomersSubscriptionsRequest
+ * @package  RetailCrm\Api\Model\Request\Customers
+ */
+class CustomersSubscriptionsRequest implements RequestInterface
+{
+    /**
+     * @var string
+     *
+     * @Form\Type("string")
+     * @Form\SerializedName("by")
+     */
+    public $by;
+
+    /**
+     * @var string
+     *
+     * @Form\Type("string")
+     * @Form\SerializedName("site")
+     */
+    public $site;
+
+    /**
+     * @var \RetailCrm\Api\Model\Entity\Customers\Subscription[]
+     *
+     * @Form\Type("RetailCrm\Api\Model\Entity\Customers\Subscription[]")
+     * @Form\SerializedName("subscriptions")
+     * @Form\JsonField()
+     */
+    public $subscriptions;
+}

src/ResourceGroup/Customers.php

@@ -19,6 +19,7 @@ use RetailCrm\Api\Model\Request\Customers\CustomersHistoryRequest;
 use RetailCrm\Api\Model\Request\Customers\CustomersNotesCreateRequest;
 use RetailCrm\Api\Model\Request\Customers\CustomersNotesRequest;
 use RetailCrm\Api\Model\Request\Customers\CustomersRequest;
+use RetailCrm\Api\Model\Request\Customers\CustomersSubscriptionsRequest;
 use RetailCrm\Api\Model\Request\Customers\CustomersUploadRequest;
 use RetailCrm\Api\Model\Response\Customers\CustomerNotesResponse;
 use RetailCrm\Api\Model\Response\Customers\CustomersEditResponse;
@@ -782,4 +783,69 @@ class Customers extends AbstractApiResourceGroup
         );
         return $response;
     }
+
+    /**
+     * Makes POST "/api/v5/customers/{externalId}/subscriptions" request.
+     *
+     * Example:
+     * ```php
+     * use RetailCrm\Api\Enum\ByIdentifier;
+     * use RetailCrm\Api\Factory\SimpleClientFactory;
+     * use RetailCrm\Api\Interfaces\ApiExceptionInterface;
+     * use RetailCrm\Api\Model\Entity\Customers\Subscription;
+     * use RetailCrm\Api\Model\Request\Customers\CustomersSubscriptionsRequest;
+     *
+     * $client = SimpleClientFactory::createClient('https://test.retailcrm.pro', 'apiKey');
+     *
+     * $subscription                       = new Subscription();
+     * $subscription->channel              = 'waba';
+     * $subscription->active               = false;
+     * $subscription->unsubscribeMessageId = 123;
+     * $request                            = new CustomersSubscriptionsRequest();
+     * $request->by                        = ByIdentifier::ID;
+     * $request->site                      = 'aliexpress';
+     * $request->subscriptions             = [$subscription];
+     *
+     * try {
+     *     $response = $client->customers->subscriptions(4770, $request);
+     * } catch (ApiExceptionInterface $exception) {
+     *     echo sprintf(
+     *         'Error from RetailCRM API (status code: %d): %s',
+     *         $exception->getStatusCode(),
+     *         $exception->getMessage()
+     *     );
+     *
+     *     if (count($exception->getErrorResponse()->errors) > 0) {
+     *         echo PHP_EOL . 'Errors: ' . implode(', ', $exception->getErrorResponse()->errors);
+     *     }
+     *
+     *     return;
+     * }
+     * ```
+     *
+     * @param int|string                                                           $identifier
+     * @param \RetailCrm\Api\Model\Request\Customers\CustomersSubscriptionsRequest $request
+     *
+     * @return \RetailCrm\Api\Model\Response\SuccessResponse
+     * @throws \RetailCrm\Api\Interfaces\ApiExceptionInterface
+     * @throws \RetailCrm\Api\Interfaces\ClientExceptionInterface
+     * @throws \RetailCrm\Api\Exception\Api\AccountDoesNotExistException
+     * @throws \RetailCrm\Api\Exception\Api\ApiErrorException
+     * @throws \RetailCrm\Api\Exception\Api\MissingCredentialsException
+     * @throws \RetailCrm\Api\Exception\Api\MissingParameterException
+     * @throws \RetailCrm\Api\Exception\Api\ValidationException
+     * @throws \RetailCrm\Api\Exception\Client\HandlerException
+     * @throws \RetailCrm\Api\Exception\Client\HttpClientException
+     */
+    public function subscriptions($identifier, CustomersSubscriptionsRequest $request): SuccessResponse
+    {
+        /** @var SuccessResponse $response */
+        $response = $this->sendRequest(
+            RequestMethod::POST,
+            'customers/' . $identifier . '/subscriptions',
+            $request,
+            SuccessResponse::class
+        );
+        return $response;
+    }
 }

tests/src/ResourceGroup/CustomersTest.php

@@ -22,6 +22,7 @@ use RetailCrm\Api\Model\Entity\Customers\CustomerNote;
 use RetailCrm\Api\Model\Entity\Customers\CustomerPhone;
 use RetailCrm\Api\Model\Entity\Customers\CustomerTag;
 use RetailCrm\Api\Model\Entity\Customers\SerializedCustomerReference;
+use RetailCrm\Api\Model\Entity\Customers\Subscription;
 use RetailCrm\Api\Model\Entity\FixExternalRow;
 use RetailCrm\Api\Model\Filter\Customers\CustomerFilter;
 use RetailCrm\Api\Model\Filter\Customers\CustomerHistoryFilter;
@@ -35,6 +36,7 @@ use RetailCrm\Api\Model\Request\Customers\CustomersHistoryRequest;
 use RetailCrm\Api\Model\Request\Customers\CustomersNotesCreateRequest;
 use RetailCrm\Api\Model\Request\Customers\CustomersNotesRequest;
 use RetailCrm\Api\Model\Request\Customers\CustomersRequest;
+use RetailCrm\Api\Model\Request\Customers\CustomersSubscriptionsRequest;
 use RetailCrm\Api\Model\Request\Customers\CustomersUploadRequest;
 use RetailCrm\TestUtils\Factory\TestClientFactory;
 use RetailCrm\TestUtils\TestCase\AbstractApiResourceGroupTestCase;
@@ -2773,4 +2775,34 @@ EOF;
 
         self::assertModelEqualsToResponse($json, $response);
     }
+
+    public function testCustomersSubscriptions(): void
+    {
+        $json = <<<'EOF'
+{
+  "success": true
+}
+EOF;
+
+        $subscription = new Subscription();
+        $subscription->channel = 'waba';
+        $subscription->active = false;
+        $subscription->unsubscribeMessageId = 123;
+
+        $request = new CustomersSubscriptionsRequest();
+        $request->by = ByIdentifier::ID;
+        $request->site = 'aliexpress';
+        $request->subscriptions = [$subscription];
+
+        $mock = static::createApiMockBuilder('customers/4770/subscriptions');
+        $mock->matchMethod(RequestMethod::POST)
+            ->matchBody(static::encodeForm($request))
+            ->reply(200)
+            ->withBody($json);
+
+        $client = TestClientFactory::createClient($mock->getClient());
+        $response = $client->customers->subscriptions(4770, $request);
+
+        self::assertModelEqualsToResponse($json, $response);
+    }
 }