> 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/intagrations/macrocrm/macrocrm-procedury.md).
# MacroCRM: Процедуры
## MacroCRM: Процедуры для настройки сценариев
***
* [Контакты](#kontakty)
* [Создание контакта](#sozdanie-kontakta)
* [Поиск контакта](#poisk-kontakta)
* [Редактирование контакта](#redaktirovanie-kontakta)
* [Заявки](#zayavki-na-pokupku-nedvizhimosti)
* [Создание заявки](#sozdanie-zayavki)
* [Поиск заявок](#poisk-zayavki)
* [Изменение статуса заявки](#izmenenie-statusa-zayavki)
* [Добавить заметку к заявке](#dobavit-zametku-k-zayavke)
* [Задачи](#zadachi)
* [Создание задачи](#sozdanie-zadachi)
* [Интересы, брони и сделки](#interesy-broni-i-sdelki)
* [Получение списка интересов, броней и сделок](#poluchenie-spiska-interesov-bronei-i-sdelok)
***
{% hint style="warning" %}
Символом \* обозначены обязательные параметры
{% endhint %}
## Контакты
**Контакт** — верхнеуровневая сущность CRM, к которой привязываются заявки на покупку, звонки, заметки и сделки
Процедуры для работы с контактами в MacroCRM:
### Создание контакта
Создаёт контакт (клиента — ФЛ или ЮЛ). Работает как upsert[^1]: если контакт с таким телефоном/email уже существует в текущей или партнёрской компании, возвращается его `id` с флагом `created: false`, новой записи не появляется. Иначе создаётся новый контакт с `created: true`
{% code overflow="wrap" lineNumbers="true" %}
```jinja
{% macro.create_user phone_number="+79998887766" name="Иванов И." _type=0 first_name="Иван" last_name="Иванов" middle_name="Иванович" email="ivan@example.com" as contact %}
```
{% endcode %}
Параметры процедуры:
* `phone_number`\* (str) - номер телефона в международном формате. Может быть как с символом +, так и без него
* `name`\* (str) - краткое имя контакта
* `_type`\* (int) - тип субъекта. Допустимые значения:
* *0* - физическое лицо
* *1* - юридическое лицо
* `first_name` (str) - имя
* `last_name` (str) - фамилия
* `middle_name` (str) - отчество
* `email` (str) - почта
* `birthdate` (datetime) - дата рождения
* `gender` (int) - пол. Допустимые значения:
* *0* - не указан
* *1* - мужской
* *2* - женский
* `fl_inn` (str) - ИНН физического лица
* `snils` (str) - СНИЛС контакта
* `description` (str) - личная информация о клиенте
* `passport_type` (str) - тип документа удостоверяющего личность. Допустимые значения:
* *пустое значение (пустые кавычки "")* - паспорт РФ
* *birth* - свидетельство о рождении
* *foreign* - иностранный паспорт
* *residency* - вид на жительство
* *idcard* - ID-карта
* `passport_number` (str) - номер паспорта
* `passport_date` (datetime) - дата выдачи паспорта
* `passport_organ` (str) - орган, выдавший паспорт
* `passport_organ_code` (str) - код подразделения, выдавшего паспорт
* `passport_birthplace` (str) - место рождения по паспорту
* `passport_address` (str) - адрес регистрации по паспорту
Пример ответа:
{% code overflow="wrap" lineNumbers="true" %}
```json
"contact": {
"uid": 1234567,
"name": "Иван И.",
"type": 0,
"gender": null,
"is_found": true,
"full_name": "",
"last_name": "",
"first_name": "",
"middle_name": "",
"is_black_listed": 0
}
```
{% endcode %}
### Поиск контакта
Ищет контакт в текущей и партнёрских компаниях. Возвращает первый найденный контакт
{% code overflow="wrap" lineNumbers="true" %}
```jinja
{% macro.get_user phone_number="+79998887766" as contact %}
```
{% endcode %}
Параметры процедуры:
* phone\_number\* (str) - номер телефона в международном формате. Может быть как с символом +, так и без него
Пример ответа:
{% code overflow="wrap" lineNumbers="true" %}
```json
"contact": {
"uid": 1234567,
"name": "Иван И.",
"type": 0,
"gender": null,
"is_found": true,
"full_name": "",
"last_name": "",
"first_name": "",
"middle_name": "",
"is_black_listed": 0
}
```
{% endcode %}
### Редактирование контакта
Обновляет поля существующего контакта по `id`, полученного при [создании](#sozdanie-kontakta) или [поиске](#poisk-kontakta) контакта. Передавайте только те поля, которые нужно изменить — остальные остаются как есть.
{% hint style="warning" %}
Телефон и email с помощью данной процедуры изменить нельзя
{% endhint %}
{% code overflow="wrap" lineNumbers="true" %}
```jinja
{% macro.edit_user uid=1234567 first_name="Иван" last_name="Петров" email="new@example.com" as contact %}
```
{% endcode %}
Параметры процедуры:
* `uid`\* (int) - идентификатор контакта для обновления
* `name` (str) - краткое имя контакта
* `first_name` (str) - имя
* `last_name` (str) - фамилия
* `middle_name` (str) - отчество
* `birthdate` (datetime) - дата рождения
* `gender` (int) - пол. Допустимые значения:
* *0* - не указан
* *1* - мужской
* *2* - женский
* `email` (str) - email клиента
* `fl_inn` (str) - ИНН физического лица
* `snils` (str) - СНИЛС контакта
* `description` (str) - личная информация о клиенте
* `passport_type` (str) - тип документа удостоверяющего личность. Допустимые значения:
* *пустое значение (пустые кавычки "")* - паспорт РФ
* *birth* - свидетельство о рождении
* *foreign* - иностранный паспорт
* *residency* - вид на жительство
* *idcard* - ID-карта
* `passport_number` (str) - номер паспорта
* `passport_date` (datetime) - дата выдачи паспорта
* `passport_organ` (str) - орган, выдавший паспорт
* `passport_organ_code` (str) - код подразделения, выдавшего паспорт
* `passport_birthplace` (str) - место рождения по паспорту
* `passport_address` (str) - адрес регистрации по паспорту
Пример ответа:
{% code overflow="wrap" lineNumbers="true" %}
```json
"contact": {
"uid": 1234567,
"name": "Иван И.",
"type": 0,
"gender": null,
"is_found": true,
"full_name": "",
"last_name": "",
"first_name": "",
"middle_name": "",
"is_black_listed": 0
}
```
{% endcode %}
***
## Заявки на покупку недвижимости
### Создание заявки
Создаёт лид (заявку) на покупку недвижимости. Контакт клиента ищется по `phone_number`/`email`; если не найден — создаётся новый (отдельное [создание](#sozdanie-kontakta) контакта перед этим вызовом не нужно). Если у контакта уже есть активная заявка — вернётся её `id` без создания новой, кроме случая `is_force: true`.
Новая заявка попадает в воронку в статус «Неразобранное» и далее движется по этапам (Проверка → Подбор → Резерв → Сделка в работе → Сделка завершена; либо Отказ/Отложено/Нецелевое). Смена статуса происходит с помощью процедуры [изменения статуса заявки](#izmenenie-statusa-zayavki)
{% code overflow="wrap" lineNumbers="true" %}
```jinja
{% macro.create_buy_request phone_number="+79199479156" full_name="Иванов Иван Иванович" action="buy" as result %}
```
{% endcode %}
Параметры процедуры:
* `phone_number`\* (str) - номер телефона в международном формате. Может быть как с символом +, так и без него
* `full_name`\* (str) - имя контакта
* `action`\* (str) - тип действия. Допустимые значения:
* *buy* - заявка на покупку (default)
* *sell* - заявка на продажу
* *callback* - запрос обратного звонка; если передан номер телефона, то будет осуществлена попытка связать клиента со случайным менеджером колл-центра, находящимся "онлайн"
* *question* - подача вопроса от посетителя сайта; вопрос будет добавлен к заметкам заявки; обязательна передача вопроса в параметре message
* *reserve* - заявка на бронь; обязателен параметр estate\_sell\_id, при этом создаваемый лид будет связан с указанным объектом недвижимости
* *askprice* - запрос информации о цене; после получения лида клиенту будет выслано письмо с презентацией объекта; обязателен параметр estate\_sell\_id, при этом создаваемый лид будет связан с указанным объектом недвижимости
* *meet* - запрос на встречу; добавление задачи с типом «Встреча в офисе»; если у клиента отсутствуют заявки, то будет создана в том числе и заявка; обязательны параметры manager\_id и meet\_date
* *lead* - базовое действие для отправки заявки
* *rate* - заявка на оценку
* `email` (str) - email контакта
* `client_msg` (str) - сообщение от клиента
* `is_force` (boolean) - принудительно создать новую заявку, игнорируя существующие по этому клиенту
* `estate_uid` (int) - ID объекта недвижимости, если заявка привязана к конкретному объекту
* `category` (str) - категория недвижимости
* `manager_uid` (str) - ID менеджера, если требуется назначить заявку конкретному менеджеру
* `meet_date` (datetime) - дата встречи (требуется при `action=meet`)
* `tags` (str) - Теги заявки. Можно передавать одной строкой через запятую
* `buy_interests_uids` (list\[str]) - ID дома или массив с ID домов. При передаче параметра заявке будет присвоен интерес к указанным домам
* `buy_source` (str) -
источник денег для покупки. Допустимые значения:
* *1* - Ипотека
* *2* - Наличные
* *3* - Продажа своего имущества
* *4* - Мат.капитал
* *5* - Обмен (Трейд-ин)
* 6 - Другие субсидии (воен., многодет. и др.)
* *7* - Зачет
* *8* - Рассрочка
* `priority` (str) -
* `reserve_sum` (float) - сумма платной брони (при action=reserve и включенной настройке платной брони)
* `domain` (str) - домен, с которого поступила заявка, для применения специфических настроек домена
* `is_allow_sms` (boolean) - согласие на SMS уведомления
* `is_allow_email` (boolean) - согласие на Email уведомления
* `is_allow_phone` (boolean) - согласие на Звонки
* `is_allow_personal_data` (boolean) - Согласие на обработку персональных данных
* `utm` (dict\[str, str]) - UTM-метки
Пример ответа:
{% code overflow="wrap" lineNumbers="true" %}
```json
{
"result": {
"estate_uid": 5512,
"contact_uid": 41823,
"manager_uid": 102,
"is_contact_created": false,
"is_estate_created": true
}
}
```
{% endcode %}
### Поиск заявок
### Изменение статуса заявки
Для изменения статуса заявки сначала необходимо получить статусы заявок:
{% code overflow="wrap" lineNumbers="true" %}
```jinja
{% macro.get_statuses as res %}
```
{% endcode %}
Пример ответа:
{% code overflow="wrap" lineNumbers="true" %}
```json
{
"statuses": [
{
"uid": 3,
"name": "Нецелевой",
"custom_statuses": []
},
{
"uid": 4,
"name": "Отказ",
"custom_statuses": []
},
{
"uid": 5,
"name": "Неразобранное",
"custom_statuses": []
}
}
```
{% endcode %}
Теперь для смены статуса необходимо использовать следующую процедуру:
{% code overflow="wrap" lineNumbers="true" %}
```jinja
{% macro.edit_request_status request_uid=100 status_uid=20 as res %}
```
{% endcode %}
Параметры процедуры:
* `request_uid`\* (int) - ID заявки на покупку недвижимости
* `status_uid`\* (int) - ID базового статуса, в который нужно перевести заявку
### Добавить заметку к заявке
{% code overflow="wrap" lineNumbers="true" %}
```jinja
{% macro.create_buy_request_note request_uid=9901 note="Клиент перезвонит в пятницу после 15:00" as res %}
```
{% endcode %}
Параметры процедуры:
* `request_uid`\* (int) - ID заявки на покупку недвижимости
* `note`\* (str) - текст заметки
## Задачи
### Создание задачи
Создаёт задачу для сотрудника от имени постановщика
{% code overflow="wrap" lineNumbers="true" %}
```jinja
{% macro.create_task manager_uid=102 assigner_uid=102 title="Связаться с клиентом" description="Уточнить детали по заявке №9901" date_finish=date_finish task_type="call" as res %}
```
{% endcode %}
Параметры процедуры:
* `manager_uid`\* (int) - ID менеджера, которому назначается задача
* `assigner_uid`\* (int) - ID постановщика задачи (может совпадать с manager\_uid)
* `title`\* (str) - название задачи
* `description`\* (str) - описание задачи
* `date_finish`\* (datetime) - срок исполнения задачи (дата и время)
* `task_type`\* (str) - тип задачи. Игнорируется, если передан types\_uid
* *call*
* *other* (default)
* *project*
* `estate_uid` (int) - ID заявки, к которой привязывается задача
* `categroy_uid` (int) - ID категории задачи
* `types_uid` (int) - ID кастомного типа задачи из каталога (используется для системных типов meeting, meeting\_house). При передаче task\_type игнорируется
* `priority` (int) - Приоритет задачи
* *-1* - низкий
* *0* (default) - обычный
* *1* - высокий
* *2* - высочайший
* `hours_plan` (int) - плановое количество часов на задачу
* `project_uid` (int) - ID проекта, связанного с задачей
* `project_task_uid` (int) - ID задачи в рамках проекта
## Интересы, брони и сделки
### Получение списка интересов, броней и сделок
Возвращает плоский список записей жизненного цикла клиент ↔ объект: интересы, бесплатные/платные брони, сделки в работе и завершённые
{% code overflow="wrap" lineNumbers="true" %}
```jinja
{% macro.get_deals_by_contact contact_uid=67890 as deals %}
```
{% endcode %}
Параметры процедуры:
* `contact_uid`\* (int) - ID клиента внутри CRM
Пример ответа:
{% code overflow="wrap" lineNumbers="true" %}
```json
[
{
"id": 555,
"type": "reserve",
"status": 20,
"estate_id": 12345,
"manager_id": 123,
"date_added": "2024-03-01 12:00:00",
"date_modified": "2024-03-10 15:30:00"
}
]
```
{% endcode %}
[^1]: **Upsert** (от англ. **Up**date + In**sert**) — это операция в базах данных, которая автоматически обновляет существующую запись, если она уже есть (по первичному ключу), или создает новую, если запись отсутствует