Skip to content

Commit 4096058

Browse files
callmemars1callmemars1
authored
Merge pull request #70 from mindbox-cloud/martynov/bitrix-docs
Документация Битрикс
2 parents daea06f + 1db997f commit 4096058

9 files changed

Lines changed: 1072 additions & 17 deletions

File tree

‎docs/README.md‎

Lines changed: 20 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -3,36 +3,39 @@
33
Mindbox PHP SDK - это библиотека инкапсулирующая детали сетевого взаимодействия и нюансы реализации API Mindbox от конечного разработчика.
44

55
Ключевые возможности библиотеки:
6-
* Поддержка двух версий API: v2.1, v3;
7-
* Отправка произвольных запросов к API Mindbox (POST и GET запросы);
8-
* Удобные обёртки для наиболее часто используемых операций Mindbox;
9-
* Логирование запросов и ответов API;
10-
* Синхронные и асинхронные вызовы операций для API v3;
11-
* Возможность подключить собственный логгер (реализующий \Psr\Log\LoggerInterface);
12-
* Возможность выбора HTTP клиента: [PHP cURL](http://php.net/manual/ru/book.curl.php), [PHP Stream](http://php.net/manual/ru/book.stream.php).
6+
7+
- Поддержка двух версий API: v2.1, v3;
8+
- Отправка произвольных запросов к API Mindbox (POST и GET запросы);
9+
- Удобные обёртки для наиболее часто используемых операций Mindbox;
10+
- Логирование запросов и ответов API;
11+
- Синхронные и асинхронные вызовы операций для API v3;
12+
- Возможность подключить собственный логгер (реализующий \Psr\Log\LoggerInterface);
13+
- Возможность выбора HTTP клиента: [PHP cURL](http://php.net/manual/ru/book.curl.php), [PHP Stream](http://php.net/manual/ru/book.stream.php).
1314

1415
С полной документацией API Mindbox можно ознакомиться [здесь](https://developers.mindbox.ru/docs/v3).
1516

1617
Для начала работы с Mindbox SDK ознакомтесь с [Гайдом по установке и настройке Mindbox PHP SDK](./getting_started.md), а также с примерами использования SDK, приведёнными ниже.
1718

19+
Интеграция с **1С-Битрикс** (настройка SDK, клиент, списки, заказ) описана в отдельном разделе: **[документация по Битрикс](./bitrix/README.md)**.
20+
1821
---
1922

2023
## Примеры использования SDK
2124

2225
- **Формирование тела запроса**
23-
- [Установка тела запроса через конструктор DTO](./examples/dto_constructor.md)
24-
- [Установка тела запроса через сеттеры DTO](./examples/dto_setters.md)
25-
- [Формирование тела запроса без использования DTO](./examples/send_prepared_request.md)
26+
- [Установка тела запроса через конструктор DTO](./examples/dto_constructor.md)
27+
- [Установка тела запроса через сеттеры DTO](./examples/dto_setters.md)
28+
- [Формирование тела запроса без использования DTO](./examples/send_prepared_request.md)
2629
- **Универсальные методы отправки запросов**
27-
- [Отправка запросов на Mindbox API v2.1](./examples/send_request_to_v2.md)
28-
- [Отправка запросов на Mindbox API v3](./examples/send_request_to_v3.md)
30+
- [Отправка запросов на Mindbox API v2.1](./examples/send_request_to_v2.md)
31+
- [Отправка запросов на Mindbox API v3](./examples/send_request_to_v3.md)
2932
- **Хелперы для стандартных операций Mindbox**
30-
- [Операции над потребителем](./examples/customer_helper.md)
31-
- [Операции связанные с процессингом заказов](./examples/order_helper.md)
32-
- [Операции связанные с обновлением списка продуктов в корзине](./examples/product_list_helper.md)
33+
- [Операции над потребителем](./examples/customer_helper.md)
34+
- [Операции связанные с процессингом заказов](./examples/order_helper.md)
35+
- [Операции связанные с обновлением списка продуктов в корзине](./examples/product_list_helper.md)
3336
- **Работа с ответом от Mindbox**
34-
- [Доступные методы для работы с ответом](./examples/response.md)
35-
- [Список возможных исключений при отправке запроса](./examples/exceptions.md)
37+
- [Доступные методы для работы с ответом](./examples/response.md)
38+
- [Список возможных исключений при отправке запроса](./examples/exceptions.md)
3639

3740
## Справочник API SDK
3841

‎docs/bitrix/README.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Интеграция Mindbox PHP SDK с Битрикс
2+
3+
Краткая последовательность: установка SDK → конфиг в `.settings.php` → один файл с клиентом Mindbox и регистрацией событий. Дальше — сценарии по операциям в отдельных страницах ниже.
4+
5+
---
6+
7+
## 1. Установить SDK
8+
9+
```sh
10+
composer require mindbox/sdk
11+
```
12+
13+
При необходимости SDK можно скопировать в каталог проекта (в т.ч. в `local`) и подключать тот же `vendor/autoload.php`.
14+
15+
В `local/php_interface/init.php` (или другой общей точке входа) подключите автозагрузчик:
16+
17+
```php
18+
require_once $_SERVER['DOCUMENT_ROOT'] . '/vendor/autoload.php';
19+
```
20+
21+
Требования к PHP и расширениям — в [общем гайде по установке](../getting_started.md#системные-зависимости).
22+
23+
---
24+
25+
## 2. Заполнить конфиг
26+
27+
В **`local/.settings.php`** добавьте секцию **`mindbox`** (остальные ключи `return` не удаляйте). Значения `endpointId`, `secretKey` и `domain` выдайте у менеджера Mindbox; `api.s.mindbox` в примере — только иллюстрация.
28+
29+
```php
30+
<?php
31+
32+
return [
33+
// … другие настройки Битрикс …
34+
35+
'mindbox' => [
36+
'value' => [
37+
'endpointId' => '…',
38+
'secretKey' => '…',
39+
'domain' => 'api.s.mindbox',
40+
'domainZone' => 'ru',
41+
],
42+
'readonly' => true,
43+
],
44+
];
45+
```
46+
47+
---
48+
49+
## 3. Файл с клиентом и обработчиками событий
50+
51+
Создайте, например, **`local/php_interface/include/mindbox.php`**. В нём — фабрика клиента и ниже пример регистрации в Mindbox при `OnAfterUserRegister` (подробнее и варианты — [регистрация клиента](./customer-register.md)). Второй аргумент `Mindbox` — любой PSR-3-логгер; ниже для простоты используется `MindboxFileLogger` (лог: `/upload/logs/mindbox.log`).
52+
53+
Подключите файл в **`init.php`** после автозагрузчика:
54+
55+
```php
56+
require_once $_SERVER['DOCUMENT_ROOT'] . '/local/php_interface/include/mindbox.php';
57+
```
58+
59+
Пример содержимого `mindbox.php`:
60+
61+
```php
62+
<?php
63+
64+
use Bitrix\Main\Config\Configuration;
65+
use Bitrix\Main\EventManager;
66+
use Mindbox\DTO\V3\Requests\CustomerRequestDTO;
67+
use Mindbox\Exceptions\MindboxClientException;
68+
use Mindbox\Mindbox;
69+
use Mindbox\Loggers\MindboxFileLogger;
70+
71+
function getMindboxClient(): Mindbox
72+
{
73+
static $client = null;
74+
75+
if ($client === null) {
76+
$cfg = Configuration::getValue('mindbox');
77+
78+
$logger = new MindboxFileLogger($_SERVER['DOCUMENT_ROOT'] . '/upload/logs');
79+
80+
$client = new Mindbox([
81+
'endpointId' => $cfg['endpointId'],
82+
'secretKey' => $cfg['secretKey'],
83+
'domain' => $cfg['domain'],
84+
'domainZone' => $cfg['domainZone'] ?? 'ru',
85+
], $logger);
86+
}
87+
88+
return $client;
89+
}
90+
91+
EventManager::getInstance()->addEventHandler(
92+
'main',
93+
'OnAfterUserRegister',
94+
static function (&$arFields) {
95+
$userId = (int)($arFields['USER_ID'] ?? 0);
96+
if ($userId <= 0) {
97+
return;
98+
}
99+
100+
$rsUser = \CUser::GetByID($userId);
101+
$arUser = $rsUser->Fetch();
102+
if (!$arUser) {
103+
return;
104+
}
105+
106+
$customer = new CustomerRequestDTO();
107+
108+
if (!empty($arUser['EMAIL'])) {
109+
$customer->setEmail($arUser['EMAIL']);
110+
}
111+
112+
if (!empty($arUser['PERSONAL_PHONE'])) {
113+
$phone = preg_replace('/\D+/', '', $arUser['PERSONAL_PHONE']);
114+
if ($phone !== '') {
115+
$customer->setMobilePhone($phone);
116+
}
117+
}
118+
119+
if (!empty($arUser['NAME'])) {
120+
$customer->setFirstName($arUser['NAME']);
121+
}
122+
123+
if (!empty($arUser['LAST_NAME'])) {
124+
$customer->setLastName($arUser['LAST_NAME']);
125+
}
126+
127+
$customer->setId('bitrixId', (string)$arUser['ID']);
128+
129+
try {
130+
getMindboxClient()
131+
->customer()
132+
->register($customer, 'Website.RegisterCustomer', true, false)
133+
->sendRequest();
134+
} catch (MindboxClientException $e) {
135+
// Логирование: $e->getMessage(), контекст user id
136+
}
137+
}
138+
);
139+
```
140+
141+
---
142+
143+
## Оглавление
144+
145+
### Операции с клиентом
146+
147+
148+
| Документ | Описание |
149+
| --------------------------------------------- | ---------------------------------------- |
150+
| [Регистрация клиента](./customer-register.md) | Создание нового клиента в Mindbox |
151+
| [Редактирование клиента](./customer-edit.md) | Обновление данных существующего клиента |
152+
| [Авторизация клиента](./customer-auth.md) | Вход и привязка сессии к клиенту Mindbox |
153+
| [Подписка на рассылки](./customer-subscribe.md) | Подписка через форму (SubscribeCustomer) |
154+
155+
156+
### Списки продуктов
157+
158+
159+
| Документ | Описание |
160+
| ----------------------------------------- | ------------------------------------ |
161+
| [Список «Корзина»](./list-cart.md) | Установка и синхронизация корзины |
162+
| [Список «Избранное»](./list-favorites.md) | Установка и синхронизация избранного |
163+
164+
165+
### Заказ
166+
167+
168+
| Документ | Описание |
169+
| ------------------------------------ | ------------------------------- |
170+
| [Создание заказа](./order-create.md) | Оформление заказа через Mindbox |
171+
172+
173+
Точные имена операций Mindbox и поля запросов — у менеджера и в [документации API](https://developers.mindbox.ru/docs/v3).

‎docs/bitrix/customer-auth.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Авторизация клиента (Битрикс + Mindbox)
2+
3+
После успешного входа пользователя в Битрикс вызывается операция **AuthorizeCustomer** в Mindbox (имя операции в проекте — **уточните у менеджера**).
4+
5+
Событие авторизации позволяет Mindbox **склеить анонимный профиль (DeviceUUID)** с известным клиентом и далее персонализировать коммуникации.
6+
7+
**Предусловия:** выполнен [быстрый старт](./README.md) (SDK, конфиг, `getMindboxClient()`).
8+
9+
---
10+
11+
## Параметры интеграции
12+
13+
14+
| Параметр | Значение |
15+
| ------------------------ | ----------------------------------------- |
16+
| Операция Mindbox | `Website.AuthorizeCustomer` |
17+
| DeviceUUID | Да (`addDeviceUUID: true`) |
18+
| Синхронность | Асинхронно (`isSync: false`) |
19+
| Точка интеграции Битрикс | Обработчик события `OnAfterUserAuthorize` |
20+
| Хелпер SDK | `$mindbox->customer()->authorize(...)` |
21+
22+
23+
---
24+
25+
## Событие
26+
27+
Используют **`main:OnAfterUserAuthorize`**. В обработчик передаётся массив полей пользователя `$arUser`; для идентификации используйте `ID` (при необходимости дозагрузите профиль через `CUser::GetByID`).
28+
29+
---
30+
31+
## Полный пример
32+
33+
Ниже — регистрация обработчика (вставьте в `local/php_interface/include/mindbox.php` после блока регистрации или в отдельный подключаемый файл).
34+
35+
Имя операции `Website.AuthorizeCustomer`, вызов `authorize(..., true, false)` — DeviceUUID в запросе, **асинхронный** вызов v3; подставьте значения из вашей интеграции.
36+
37+
```php
38+
<?php
39+
40+
use Bitrix\Main\EventManager;
41+
use Mindbox\DTO\V3\Requests\CustomerRequestDTO;
42+
use Mindbox\Exceptions\MindboxClientException;
43+
44+
EventManager::getInstance()->addEventHandler(
45+
'main',
46+
'OnAfterUserAuthorize',
47+
static function ($arUser) {
48+
$userId = (int)($arUser['ID'] ?? 0);
49+
if ($userId <= 0) {
50+
return;
51+
}
52+
53+
$rsUser = \CUser::GetByID($userId);
54+
$userData = $rsUser->Fetch();
55+
if (!$userData) {
56+
return;
57+
}
58+
59+
$customer = new CustomerRequestDTO();
60+
61+
if (!empty($userData['EMAIL'])) {
62+
$customer->setEmail($userData['EMAIL']);
63+
}
64+
65+
$customer->setId('bitrixId', (string)$userData['ID']);
66+
67+
try {
68+
getMindboxClient()
69+
->customer()
70+
->authorize($customer, 'Website.AuthorizeCustomer', true, false)
71+
->sendRequest();
72+
} catch (MindboxClientException $e) {
73+
// Логирование: $e->getMessage(), контекст user id
74+
}
75+
}
76+
);
77+
```
78+
79+
Краткий фрагмент только вызова Mindbox (без события Битрикс):
80+
81+
```php
82+
$customer = new \Mindbox\DTO\V3\Requests\CustomerRequestDTO();
83+
$customer->setEmail($arUser['EMAIL']);
84+
$customer->setId('bitrixId', (string)$arUser['ID']);
85+
86+
try {
87+
$response = getMindboxClient()
88+
->customer()
89+
->authorize($customer, 'Website.AuthorizeCustomer', true, false)
90+
->sendRequest();
91+
} catch (\Mindbox\Exceptions\MindboxClientException $e) {
92+
// Логирование ошибки
93+
}
94+
```
95+
96+
---
97+
98+
## Параметры `authorize()`
99+
100+
Сигнатура хелпера: `authorize(CustomerRequestDTO $customer, $operationName, $addDeviceUUID = true, $isSync = false)`.
101+
102+
- **`$addDeviceUUID`** — передавать ли DeviceUUID в запросе (для склейки с анонимным профилем обычно `true`).
103+
- **`$isSync`** — `false` (по умолчанию): асинхронный запрос к API v3, `true`: синхронный.
104+
105+
---
106+
107+
## Ошибки и отладка
108+
109+
- Ошибка Mindbox при авторизации **не обязана** блокировать вход в Битрикс — правило логирования и влияния на UX задайте в проекте.
110+
- Перехват `MindboxClientException` и запись в лог (без утечки ПДн).
111+
- См. [исключения SDK](../examples/exceptions.md), [CustomerHelper в общих примерах](../examples/customer_helper.md).
112+

0 commit comments

Comments
 (0)