> For the complete documentation index, see [llms.txt](https://docs.fstrk.io/knowledge_base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fstrk.io/knowledge_base/instructions/operacii-mindbox.md).

# Операции Mindbox

Раздел описывает операции интеграции **Mindbox** в платформе Fasttrack: какие операции доступны, в какой момент они вызываются, какие параметры принимают и как обрабатывать результат в конструкторе.

{% hint style="info" %}
В описании параметров символом `*` обозначены **обязательные** поля. Остальные поля передаются по необходимости — в зависимости от настроек проекта и сценария бота.
{% endhint %}

## Как вызвать операцию

Любая операция Mindbox вызывается в конструкторе тегом `{% mindbox.operation %}`. Тело запроса формируется заранее объектом через `{% createobj %} … {% endcreateobj %}`, а результат выполнения сохраняется в переменную для дальнейшего использования.

Общая схема состоит из трёх шагов:

{% stepper %}
{% step %}

## Сформировать тело запроса

Объект с параметрами операции через `{% createobj %}`.
{% endstep %}

{% step %}

## Вызвать операцию

Тег `{% mindbox.operation %}` с именем операции и телом запроса.
{% endstep %}

{% step %}

## Сохранить результат

Тег `{% save_variable %}`, чтобы обратиться к ответу дальше по сценарию.
{% endstep %}
{% endstepper %}

Аргументы тега `{% mindbox.operation %}`:

| Аргумент          | Описание                                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------- |
| `name`            | Имя операции в Mindbox (например, `ft.GetCustomer`). Должно совпадать с именем, заведённым в админке Mindbox. |
| `custom_fields`   | Объект с телом запроса, созданный через `{% createobj %}`.                                                    |
| `as <переменная>` | Имя переменной, в которую помещается результат выполнения операции.                                           |

Пример полного вызова — проверка наличия контакта в Mindbox по номеру телефона:

```django
{# вызываем операцию ft.GetCustomer для проверки наличия контакта в MindBox #}
{% createobj get_contact %}
{
    "page": {
        "pageNumber": "1",
        "itemsPerPage": "10"
    },
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.GetCustomer" custom_fields=get_contact as operation_ft_GetCustomer %}
{# сохраним результат выполнения операции в переменнную operation_ft_GetCustomer #}
{% save_variable "operation_ft_GetCustomer" operation_ft_GetCustomer %}
```

{% hint style="warning" %}
Каждая операция (`name`) должна быть предварительно заведена в админке Mindbox. Если операция не настроена на стороне Mindbox, вызов вернёт ошибку.
{% endhint %}

## Основные методы

### ft.BotStart — Старт бота

Вызывается в момент **первого запуска бота** пользователем. Передаёт в Mindbox факт входа в бота, идентификатор пользователя в боте и, при наличии, данные из диплинка (магазин, акция, платформа).

<details>

<summary>Параметры</summary>

| Параметр                                  | Тип    | Описание                                          |
| ----------------------------------------- | ------ | ------------------------------------------------- |
| `pointOfContact`                          | string | Идентификатор магазина (если передан в диплинке). |
| `customer.ids.tGID` \*                    | string | Идентификатор пользователя в боте.                |
| `customer.customFields.inbotTG`           | string | Признак присутствия клиента в боте (`True`).      |
| `customerAction.customFields.advertID`    | string | Идентификатор акции (если передан в диплинке).    |
| `customerAction.customFields.botPlatform` | string | Платформа бота: `tg` / `vk` / `max` / `wa`.       |

</details>

**Пример вызова:**

```django
{# фиксируем старт бота в Mindbox #}
{% createobj bot_start %}
{
    "pointOfContact": "{{shop_id}}",
    "customer": {
        "customFields": {
            "inbotTG": "True"
        },
        "ids": {
            "tGID": "{{bot_user_id}}"
        }
    },
    "customerAction": {
        "customFields": {
            "advertID": "{{advert_id}}",
            "botPlatform": "tg"
        }
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.BotStart" custom_fields=bot_start as operation_ft_BotStart %}
{% save_variable "operation_ft_BotStart" operation_ft_BotStart %}
```

**Структура ответа (схематично):**

```json
{
    "status": "Success",
    "customer": {
        "ids": { "mindboxId": "..." }
    }
}
```

### ft.CreateCustomer — Создание клиента

Создаёт клиента в Mindbox. Вызывается, когда пользователь оставил номер телефона и его нужно завести как контакт. Здесь же фиксируется согласие на рассылки.

<details>

<summary>Параметры</summary>

| Параметр                         | Тип    | Описание                                                                                                                                         |
| -------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `customer.mobilePhone` \*        | string | Мобильный телефон клиента.                                                                                                                       |
| `customer.ids.tGID`              | string | Идентификатор пользователя в боте.                                                                                                               |
| `customer.customFields.subTG`    | string | Признак согласия на рассылки в боте (`True`).                                                                                                    |
| `customer.subscriptions[].brand` | string | Передаётся, если согласие на рассылки в боте должно распространяться на все рассылки бренда. В этом случае передаётся весь блок `subscriptions`. |

</details>

**Пример вызова:**

```django
{# создаём клиента в Mindbox #}
{% createobj create_customer %}
{
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}",
        "ids": {
            "tGID": "{{bot_user_id}}"
        },
        "customFields": {
            "subTG": "True"
        },
        "subscriptions": [
            {
                "brand": "{{brand}}"
            }
        ]
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.CreateCustomer" custom_fields=create_customer as operation_ft_CreateCustomer %}
{% save_variable "operation_ft_CreateCustomer" operation_ft_CreateCustomer %}
```

**Структура ответа (схематично):**

```json
{
    "status": "Success",
    "customer": {
        "ids": { "mindboxId": "..." }
    }
}
```

### ft.FillUpCustomer — Дополнить клиента

Дозаполняет профиль уже существующего клиента: ФИО, дата рождения, пол, контакты, часовой пояс. Вызывается, когда пользователь постепенно сообщает дополнительные данные о себе.

<details>

<summary>Параметры</summary>

| Параметр                  | Тип    | Описание                                   |
| ------------------------- | ------ | ------------------------------------------ |
| `customer.mobilePhone` \* | string | Мобильный телефон клиента (идентификация). |
| `customer.firstName`      | string | Имя.                                       |
| `customer.lastName`       | string | Фамилия.                                   |
| `customer.middleName`     | string | Отчество.                                  |
| `customer.fullName`       | string | ФИО одной строкой.                         |
| `customer.birthDate`      | string | Дата рождения.                             |
| `customer.sex`            | string | Пол.                                       |
| `customer.email`          | string | Email.                                     |
| `customer.timeZone`       | string | Часовой пояс.                              |

</details>

**Пример вызова:**

```django
{# дополняем профиль клиента #}
{% createobj fill_up_customer %}
{
    "customer": {
        "birthDate": "{{birth_date}}",
        "sex": "{{sex}}",
        "timeZone": "{{time_zone}}",
        "lastName": "{{last_name}}",
        "firstName": "{{first_name}}",
        "middleName": "{{middle_name}}",
        "fullName": "{{full_name}}",
        "email": "{{email}}",
        "mobilePhone": "{{attributes.profile_phone_number}}"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.FillUpCustomer" custom_fields=fill_up_customer as operation_ft_FillUpCustomer %}
{% save_variable "operation_ft_FillUpCustomer" operation_ft_FillUpCustomer %}
```

**Структура ответа (схематично):**

```json
{
    "status": "Success"
}
```

### ft.GetCustomer — Получить информацию о клиенте

Возвращает данные клиента из Mindbox по номеру телефона. Используется для проверки наличия контакта и получения его профиля.

<details>

<summary>Параметры</summary>

| Параметр                  | Тип    | Описание                              |
| ------------------------- | ------ | ------------------------------------- |
| `customer.mobilePhone` \* | string | Мобильный телефон клиента для поиска. |
| `page.pageNumber`         | string | Номер страницы выборки.               |
| `page.itemsPerPage`       | string | Количество записей на странице.       |

</details>

**Пример вызова:**

```django
{# вызываем операцию ft.GetCustomer для проверки наличия контакта в MindBox #}
{% createobj get_contact %}
{
    "page": {
        "pageNumber": "1",
        "itemsPerPage": "10"
    },
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.GetCustomer" custom_fields=get_contact as operation_ft_GetCustomer %}
{# сохраним результат выполнения операции в переменнную operation_ft_GetCustomer #}
{% save_variable "operation_ft_GetCustomer" operation_ft_GetCustomer %}
```

**Структура ответа (схематично):**

```json
{
    "status": "Success",
    "customer": {
        "ids": { "mindboxId": "..." },
        "firstName": "...",
        "lastName": "...",
        "mobilePhone": "...",
        "email": "..."
    }
}
```

## Бот лояльности

### ft.ConfirmPhone — Подтвердить телефон

Подтверждает номер телефона клиента. Используется, **если на проекте предусмотрено подтверждение номера** (например, через код из SMS).

<details>

<summary>Параметры</summary>

| Параметр                    | Тип    | Описание                         |
| --------------------------- | ------ | -------------------------------- |
| `customer.mobilePhone` \*   | string | Мобильный телефон клиента.       |
| `customer.ids.mindboxId` \* | string | Идентификатор клиента в Mindbox. |

</details>

**Пример вызова:**

```django
{# подтверждаем номер телефона клиента #}
{% createobj confirm_phone %}
{
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}",
        "ids": {
            "mindboxId": "{{mindbox_id}}"
        }
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.ConfirmPhone" custom_fields=confirm_phone as operation_ft_ConfirmPhone %}
{% save_variable "operation_ft_ConfirmPhone" operation_ft_ConfirmPhone %}
```

**Структура ответа (схематично):**

```json
{
    "status": "Success"
}
```

### ft.GenerateLoyaltyCode — Генерация QR-кода авторизации

Генерирует код авторизации в программе лояльности. Используется, **если на проекте применяется динамический QR-код**.

<details>

<summary>Параметры</summary>

| Параметр                  | Тип    | Описание                   |
| ------------------------- | ------ | -------------------------- |
| `customer.mobilePhone` \* | string | Мобильный телефон клиента. |

</details>

**Пример вызова:**

```django
{# генерируем динамический QR-код авторизации #}
{% createobj loyalty_code %}
{
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.GenerateLoyaltyCode" custom_fields=loyalty_code as operation_ft_GenerateLoyaltyCode %}
{% save_variable "operation_ft_GenerateLoyaltyCode" operation_ft_GenerateLoyaltyCode %}
```

**Структура ответа (схематично):**

```json
{
    "status": "Success",
    "loyaltyCode": "..."
}
```

### ft.GetCustomerOrders — Список заказов по номеру телефона

Возвращает список заказов клиента по номеру телефона с постраничной выборкой.

<details>

<summary>Параметры</summary>

| Параметр                  | Тип    | Описание                        |
| ------------------------- | ------ | ------------------------------- |
| `customer.mobilePhone` \* | string | Мобильный телефон клиента.      |
| `page.pageNumber`         | string | Номер страницы выборки.         |
| `page.itemsPerPage`       | string | Количество записей на странице. |

</details>

**Пример вызова:**

```django
{# получаем список заказов клиента #}
{% createobj customer_orders %}
{
    "page": {
        "pageNumber": "1",
        "itemsPerPage": "10"
    },
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.GetCustomerOrders" custom_fields=customer_orders as operation_ft_GetCustomerOrders %}
{% save_variable "operation_ft_GetCustomerOrders" operation_ft_GetCustomerOrders %}
```

**Структура ответа (схематично):**

```json
{
    "status": "Success",
    "orders": [
        {
            "ids": { "mindboxId": "..." },
            "totalPrice": "...",
            "processingStatus": "..."
        }
    ]
}
```

## Дополнительные методы

### ft.EditCustomer — Редактировать клиента

Обновляет данные существующего клиента. В отличие от `ft.FillUpCustomer`, используется для прямого редактирования полей профиля.

<details>

<summary>Параметры</summary>

| Параметр                  | Тип    | Описание                                   |
| ------------------------- | ------ | ------------------------------------------ |
| `customer.mobilePhone` \* | string | Мобильный телефон клиента (идентификация). |
| `customer.firstName`      | string | Имя.                                       |
| `customer.lastName`       | string | Фамилия.                                   |
| `customer.middleName`     | string | Отчество.                                  |
| `customer.fullName`       | string | ФИО одной строкой.                         |
| `customer.birthDate`      | string | Дата рождения.                             |
| `customer.sex`            | string | Пол.                                       |
| `customer.email`          | string | Email.                                     |
| `customer.timeZone`       | string | Часовой пояс.                              |

</details>

**Пример вызова:**

```django
{# редактируем данные клиента #}
{% createobj edit_customer %}
{
    "customer": {
        "birthDate": "{{birth_date}}",
        "sex": "{{sex}}",
        "timeZone": "{{time_zone}}",
        "lastName": "{{last_name}}",
        "firstName": "{{first_name}}",
        "middleName": "{{middle_name}}",
        "fullName": "{{full_name}}",
        "email": "{{email}}",
        "mobilePhone": "{{attributes.profile_phone_number}}"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.EditCustomer" custom_fields=edit_customer as operation_ft_EditCustomer %}
{% save_variable "operation_ft_EditCustomer" operation_ft_EditCustomer %}
```

**Структура ответа (схематично):**

```json
{
    "status": "Success"
}
```

### ft.GetTicket — Получить тикет по клиенту

Возвращает тикет (обращение / купон / запись) клиента по номеру телефона.

<details>

<summary>Параметры</summary>

| Параметр                  | Тип    | Описание                   |
| ------------------------- | ------ | -------------------------- |
| `customer.mobilePhone` \* | string | Мобильный телефон клиента. |

</details>

**Пример вызова:**

```django
{# получаем тикет клиента #}
{% createobj get_ticket %}
{
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.GetTicket" custom_fields=get_ticket as operation_ft_GetTicket %}
{% save_variable "operation_ft_GetTicket" operation_ft_GetTicket %}
```

**Структура ответа (схематично):**

```json
{
    "status": "Success",
    "ticket": {
        "ids": { "mindboxId": "..." }
    }
}
```

### ft.ChatBotEvent — Событие в боте

Передаёт в Mindbox информацию о произошедшем событии в боте. Список идентификаторов (типов) событий определяет клиент.

<details>

<summary>Параметры</summary>

| Параметр                                          | Тип    | Описание                                                           |
| ------------------------------------------------- | ------ | ------------------------------------------------------------------ |
| `customer.mobilePhone` \*                         | string | Мобильный телефон клиента.                                         |
| `customerAction.customFields.chatBotEventType` \* | string | Тип события в боте (значение из согласованного с клиентом списка). |

</details>

**Пример вызова:**

```django
{# фиксируем событие в боте #}
{% createobj chatbot_event %}
{
    "customer": {
        "mobilePhone": "{{attributes.profile_phone_number}}"
    },
    "customerAction": {
        "customFields": {
            "chatBotEventType": "{{event_type}}"
        }
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.ChatBotEvent" custom_fields=chatbot_event as operation_ft_ChatBotEvent %}
{% save_variable "operation_ft_ChatBotEvent" operation_ft_ChatBotEvent %}
```

**Структура ответа (схематично):**

```json
{
    "status": "Success"
}
```

### ft.GetCustomerRecommendations — Получить рекомендации

Возвращает персональные товарные рекомендации для клиента по номеру телефона.

<details>

<summary>Параметры</summary>

| Параметр                  | Тип    | Описание                                       |
| ------------------------- | ------ | ---------------------------------------------- |
| `customer.mobilePhone` \* | string | Мобильный телефон клиента.                     |
| `recommendation.limit`    | string | Максимальное количество рекомендаций в ответе. |

</details>

**Пример вызова:**

```django
{# получаем персональные рекомендации для клиента #}
{% createobj recommendations %}
{
    "customer": {
        "mobilePhone": "{{phone_number}}"
    },
    "recommendation": {
        "limit": "10"
    }
}
{% endcreateobj %}
{% mindbox.operation name="ft.GetCustomerRecommendations" custom_fields=recommendations as operation_ft_GetCustomerRecommendations %}
{% save_variable "operation_ft_GetCustomerRecommendations" operation_ft_GetCustomerRecommendations %}
```

**Структура ответа (схематично):**

```json
{
    "status": "Success",
    "recommendations": [
        {
            "ids": { "mindboxId": "..." },
            "name": "...",
            "price": "..."
        }
    ]
}
```