mindbox-cloud · callmemars1 · Apr 13, 2026 · Apr 13, 2026
diff --git a/docs/README.md b/docs/README.md
@@ -3,36 +3,39 @@
 Mindbox PHP SDK - это библиотека инкапсулирующая детали сетевого взаимодействия и нюансы реализации API Mindbox от конечного разработчика.
 
 Ключевые возможности библиотеки:
-* Поддержка двух версий API: v2.1, v3;
-* Отправка произвольных запросов к API Mindbox (POST и GET запросы);
-* Удобные обёртки для наиболее часто используемых операций Mindbox;
-* Логирование запросов и ответов API;
-* Синхронные и асинхронные вызовы операций для API v3;
-* Возможность подключить собственный логгер (реализующий \Psr\Log\LoggerInterface);
-* Возможность выбора HTTP клиента: [PHP cURL](http://php.net/manual/ru/book.curl.php), [PHP Stream](http://php.net/manual/ru/book.stream.php).
+
+- Поддержка двух версий API: v2.1, v3;
+- Отправка произвольных запросов к API Mindbox (POST и GET запросы);
+- Удобные обёртки для наиболее часто используемых операций Mindbox;
+- Логирование запросов и ответов API;
+- Синхронные и асинхронные вызовы операций для API v3;
+- Возможность подключить собственный логгер (реализующий \Psr\Log\LoggerInterface);
+- Возможность выбора HTTP клиента: [PHP cURL](http://php.net/manual/ru/book.curl.php), [PHP Stream](http://php.net/manual/ru/book.stream.php).
 
 С полной документацией API Mindbox можно ознакомиться [здесь](https://developers.mindbox.ru/docs/v3).
 
 Для начала работы с Mindbox SDK ознакомтесь с [Гайдом по установке и настройке Mindbox PHP SDK](./getting_started.md), а также с примерами использования SDK, приведёнными ниже.
 
+Интеграция с **1С-Битрикс** (настройка SDK, клиент, списки, заказ) описана в отдельном разделе: **[документация по Битрикс](./bitrix/README.md)**.
+
 ---
 
 ## Примеры использования SDK
 
 - **Формирование тела запроса**
-    - [Установка тела запроса через конструктор DTO](./examples/dto_constructor.md)
-    - [Установка тела запроса через сеттеры DTO](./examples/dto_setters.md)
-    - [Формирование тела запроса без использования DTO](./examples/send_prepared_request.md)
+  - [Установка тела запроса через конструктор DTO](./examples/dto_constructor.md)
+  - [Установка тела запроса через сеттеры DTO](./examples/dto_setters.md)
+  - [Формирование тела запроса без использования DTO](./examples/send_prepared_request.md)
 - **Универсальные методы отправки запросов**
-    - [Отправка запросов на Mindbox API v2.1](./examples/send_request_to_v2.md)
-    - [Отправка запросов на Mindbox API v3](./examples/send_request_to_v3.md)
+  - [Отправка запросов на Mindbox API v2.1](./examples/send_request_to_v2.md)
+  - [Отправка запросов на Mindbox API v3](./examples/send_request_to_v3.md)
 - **Хелперы для стандартных операций Mindbox**
-    - [Операции над потребителем](./examples/customer_helper.md)
-    - [Операции связанные с процессингом заказов](./examples/order_helper.md)
-    - [Операции связанные с обновлением списка продуктов в корзине](./examples/product_list_helper.md)
+  - [Операции над потребителем](./examples/customer_helper.md)
+  - [Операции связанные с процессингом заказов](./examples/order_helper.md)
+  - [Операции связанные с обновлением списка продуктов в корзине](./examples/product_list_helper.md)
 - **Работа с ответом от Mindbox**
-    - [Доступные методы для работы с ответом](./examples/response.md)
-    - [Список возможных исключений при отправке запроса](./examples/exceptions.md)
+  - [Доступные методы для работы с ответом](./examples/response.md)
+  - [Список возможных исключений при отправке запроса](./examples/exceptions.md)
 
 ## Справочник API SDK
 

diff --git a/docs/bitrix/README.md b/docs/bitrix/README.md
@@ -0,0 +1,173 @@
+# Интеграция Mindbox PHP SDK с Битрикс
+
+Краткая последовательность: установка SDK → конфиг в `.settings.php` → один файл с клиентом Mindbox и регистрацией событий. Дальше — сценарии по операциям в отдельных страницах ниже.
+
+---
+
+## 1. Установить SDK
+
+```sh
+composer require mindbox/sdk
+```
+
+При необходимости SDK можно скопировать в каталог проекта (в т.ч. в `local`) и подключать тот же `vendor/autoload.php`.
+
+В `local/php_interface/init.php` (или другой общей точке входа) подключите автозагрузчик:
+
+```php
+require_once $_SERVER['DOCUMENT_ROOT'] . '/vendor/autoload.php';
+```
+
+Требования к PHP и расширениям — в [общем гайде по установке](../getting_started.md#системные-зависимости).
+
+---
+
+## 2. Заполнить конфиг
+
+В **`local/.settings.php`** добавьте секцию **`mindbox`** (остальные ключи `return` не удаляйте). Значения `endpointId`, `secretKey` и `domain` выдайте у менеджера Mindbox; `api.s.mindbox` в примере — только иллюстрация.
+
+```php
+<?php
+
+return [
+    // … другие настройки Битрикс …
+
+    'mindbox' => [
+        'value' => [
+            'endpointId' => '…',
+            'secretKey'  => '…',
+            'domain'     => 'api.s.mindbox',
+            'domainZone' => 'ru',
+        ],
+        'readonly' => true,
+    ],
+];
+```
+
+---
+
+## 3. Файл с клиентом и обработчиками событий
+
+Создайте, например, **`local/php_interface/include/mindbox.php`**. В нём — фабрика клиента и ниже пример регистрации в Mindbox при `OnAfterUserRegister` (подробнее и варианты — [регистрация клиента](./customer-register.md)). Второй аргумент `Mindbox` — любой PSR-3-логгер; ниже для простоты используется `MindboxFileLogger` (лог: `/upload/logs/mindbox.log`).
+
+Подключите файл в **`init.php`** после автозагрузчика:
+
+```php
+require_once $_SERVER['DOCUMENT_ROOT'] . '/local/php_interface/include/mindbox.php';
+```
+
+Пример содержимого `mindbox.php`:
+
+```php
+<?php
+
+use Bitrix\Main\Config\Configuration;
+use Bitrix\Main\EventManager;
+use Mindbox\DTO\V3\Requests\CustomerRequestDTO;
+use Mindbox\Exceptions\MindboxClientException;
+use Mindbox\Mindbox;
+use Mindbox\Loggers\MindboxFileLogger;
+
+function getMindboxClient(): Mindbox
+{
+    static $client = null;
+
+    if ($client === null) {
+        $cfg = Configuration::getValue('mindbox');
+
+        $logger = new MindboxFileLogger($_SERVER['DOCUMENT_ROOT'] . '/upload/logs');
+
+        $client = new Mindbox([
+            'endpointId' => $cfg['endpointId'],
+            'secretKey'  => $cfg['secretKey'],
+            'domain'     => $cfg['domain'],
+            'domainZone' => $cfg['domainZone'] ?? 'ru',
+        ], $logger);
+    }
+
+    return $client;
+}
+
+EventManager::getInstance()->addEventHandler(
+    'main',
+    'OnAfterUserRegister',
+    static function (&$arFields) {
+        $userId = (int)($arFields['USER_ID'] ?? 0);
+        if ($userId <= 0) {
+            return;
+        }
+
+        $rsUser = \CUser::GetByID($userId);
+        $arUser = $rsUser->Fetch();
+        if (!$arUser) {
+            return;
+        }
+
+        $customer = new CustomerRequestDTO();
+
+        if (!empty($arUser['EMAIL'])) {
+            $customer->setEmail($arUser['EMAIL']);
+        }
+
+        if (!empty($arUser['PERSONAL_PHONE'])) {
+            $phone = preg_replace('/\D+/', '', $arUser['PERSONAL_PHONE']);
+            if ($phone !== '') {
+                $customer->setMobilePhone($phone);
+            }
+        }
+
+        if (!empty($arUser['NAME'])) {
+            $customer->setFirstName($arUser['NAME']);
+        }
+
+        if (!empty($arUser['LAST_NAME'])) {
+            $customer->setLastName($arUser['LAST_NAME']);
+        }
+
+        $customer->setId('bitrixId', (string)$arUser['ID']);
+
+        try {
+            getMindboxClient()
+                ->customer()
+                ->register($customer, 'Website.RegisterCustomer', true, false)
+                ->sendRequest();
+        } catch (MindboxClientException $e) {
+            // Логирование: $e->getMessage(), контекст user id
+        }
+    }
+);
+```
+
+---
+
+## Оглавление
+
+### Операции с клиентом
+
+
+| Документ                                      | Описание                                 |
+| --------------------------------------------- | ---------------------------------------- |
+| [Регистрация клиента](./customer-register.md) | Создание нового клиента в Mindbox        |
+| [Редактирование клиента](./customer-edit.md)  | Обновление данных существующего клиента  |
+| [Авторизация клиента](./customer-auth.md)     | Вход и привязка сессии к клиенту Mindbox |
+| [Подписка на рассылки](./customer-subscribe.md) | Подписка через форму (SubscribeCustomer) |
+
+
+### Списки продуктов
+
+
+| Документ                                  | Описание                             |
+| ----------------------------------------- | ------------------------------------ |
+| [Список «Корзина»](./list-cart.md)        | Установка и синхронизация корзины    |
+| [Список «Избранное»](./list-favorites.md) | Установка и синхронизация избранного |
+
+
+### Заказ
+
+
+| Документ                             | Описание                        |
+| ------------------------------------ | ------------------------------- |
+| [Создание заказа](./order-create.md) | Оформление заказа через Mindbox |
+
+
+Точные имена операций Mindbox и поля запросов — у менеджера и в [документации API](https://developers.mindbox.ru/docs/v3).
diff --git a/docs/bitrix/customer-auth.md b/docs/bitrix/customer-auth.md
@@ -0,0 +1,112 @@
+# Авторизация клиента (Битрикс + Mindbox)
+
+После успешного входа пользователя в Битрикс вызывается операция **AuthorizeCustomer** в Mindbox (имя операции в проекте — **уточните у менеджера**).
+
+Событие авторизации позволяет Mindbox **склеить анонимный профиль (DeviceUUID)** с известным клиентом и далее персонализировать коммуникации.
+
+**Предусловия:** выполнен [быстрый старт](./README.md) (SDK, конфиг, `getMindboxClient()`).
+
+---
+
+## Параметры интеграции
+
+
+| Параметр                 | Значение                                  |
+| ------------------------ | ----------------------------------------- |
+| Операция Mindbox         | `Website.AuthorizeCustomer`               |
+| DeviceUUID               | Да (`addDeviceUUID: true`)                |
+| Синхронность             | Асинхронно (`isSync: false`)              |
+| Точка интеграции Битрикс | Обработчик события `OnAfterUserAuthorize` |
+| Хелпер SDK               | `$mindbox->customer()->authorize(...)`    |
+
+
+---
+
+## Событие
+
+Используют **`main:OnAfterUserAuthorize`**. В обработчик передаётся массив полей пользователя `$arUser`; для идентификации используйте `ID` (при необходимости дозагрузите профиль через `CUser::GetByID`).
+
+---
+
+## Полный пример
+
+Ниже — регистрация обработчика (вставьте в `local/php_interface/include/mindbox.php` после блока регистрации или в отдельный подключаемый файл).
+
+Имя операции `Website.AuthorizeCustomer`, вызов `authorize(..., true, false)` — DeviceUUID в запросе, **асинхронный** вызов v3; подставьте значения из вашей интеграции.
+
+```php
+<?php
+
+use Bitrix\Main\EventManager;
+use Mindbox\DTO\V3\Requests\CustomerRequestDTO;
+use Mindbox\Exceptions\MindboxClientException;
+
+EventManager::getInstance()->addEventHandler(
+    'main',
+    'OnAfterUserAuthorize',
+    static function ($arUser) {
+        $userId = (int)($arUser['ID'] ?? 0);
+        if ($userId <= 0) {
+            return;
+        }
+
+        $rsUser = \CUser::GetByID($userId);
+        $userData = $rsUser->Fetch();
+        if (!$userData) {
+            return;
+        }
+
+        $customer = new CustomerRequestDTO();
+
+        if (!empty($userData['EMAIL'])) {
+            $customer->setEmail($userData['EMAIL']);
+        }
+
+        $customer->setId('bitrixId', (string)$userData['ID']);
+
+        try {
+            getMindboxClient()
+                ->customer()
+                ->authorize($customer, 'Website.AuthorizeCustomer', true, false)
+                ->sendRequest();
+        } catch (MindboxClientException $e) {
+            // Логирование: $e->getMessage(), контекст user id
+        }
+    }
+);
+```
+
+Краткий фрагмент только вызова Mindbox (без события Битрикс):
+
+```php
+$customer = new \Mindbox\DTO\V3\Requests\CustomerRequestDTO();
+$customer->setEmail($arUser['EMAIL']);
+$customer->setId('bitrixId', (string)$arUser['ID']);
+
+try {
+    $response = getMindboxClient()
+        ->customer()
+        ->authorize($customer, 'Website.AuthorizeCustomer', true, false)
+        ->sendRequest();
+} catch (\Mindbox\Exceptions\MindboxClientException $e) {
+    // Логирование ошибки
+}
+```
+
+---
+
+## Параметры `authorize()`
+
+Сигнатура хелпера: `authorize(CustomerRequestDTO $customer, $operationName, $addDeviceUUID = true, $isSync = false)`.
+
+- **`$addDeviceUUID`** — передавать ли DeviceUUID в запросе (для склейки с анонимным профилем обычно `true`).
+- **`$isSync`** — `false` (по умолчанию): асинхронный запрос к API v3, `true`: синхронный.
+
+---
+
+## Ошибки и отладка
+
+- Ошибка Mindbox при авторизации **не обязана** блокировать вход в Битрикс — правило логирования и влияния на UX задайте в проекте.
+- Перехват `MindboxClientException` и запись в лог (без утечки ПДн).
+- См. [исключения SDK](../examples/exceptions.md), [CustomerHelper в общих примерах](../examples/customer_helper.md).
+