Бизнес-платформа КЛИЕНТИКС
CRM-система для гибкого управления компанией в сфере услуг
Last updated
CRM-система для гибкого управления компанией в сфере услуг
Last updated
Для начала работы необходимо получить данные для авторизации API.
Для этого зайдите в меню в правом верхнем углу, раздел Настройки, подраздел API и нажмите галочку Включить
Получение данных для авторизации API доступно только для тарифов PRO+,API
После получения API переменных переходим в настройки проекта в Salebot -> Константы проекта и сохраняем его в переменные klientiks_account_id, klientiks_user_id и klientiks_access_token соответственно.
Каждая функция возвращает словарь, у которого есть параметр status, он может иметь два значения 0 и 1.
Если значение status=1, то запрос в Клиентикс прошел успешно и в параметре result будет результат запроса:
Например: {'status': '1', 'result':{'2022-03-15': ['2022-03-15 12:00:00', '2022-03-15 13:00:00', '2022-03-15 15:00:00', '2022-03-15 16:00:00']}}
Или запрос в Клиентикс прошел успешно, но ничего не найдено: {'status': '1', 'result':[]}
Если status=0 - то есть какая-то проблема и описание будет находиться в error:
Например: {'status': '0', 'error': 'Missing required variables - phone'}
Для получения списка сотрудников используется функция klientiks_get_employees_list()
Функция возвращает словарь вида:
в случае успеха: {'status': '1', 'result': [{'id': 121125, 'name': 'Алекс', 'phone': '+7 (900) 001-00-00', 'email': 'test03@yandex.ru'}, {'id': 121126, 'name': 'Екатерина', 'phone': '+7 (900) 000-00-00', 'email': ''}]}
в случае ошибки, например: {'status': '0', 'error': "No account_id/user_id/access_token in 'klientiks_api_key' variable in project settings"} – отсутствует необходимая API-переменная
Для получения доступного времени для записи необходимо наличие включенного виджета онлайн-записи. Включить его можно в klientiks меню -> возможности -> онлайн запись -> включить галочку “включить онлайн-запись с сайта”.
klientiks_get_free_date_for_record(start_day, finish_day, service_id, executor_id)
где:
| Аргумент | Статус | Формат | Краткое описание |
|---|---|---|---|
start_day | обязательный | дата в формате дд.мм.гггг | Начальная дата. Дата, за которую нужно показать свободное время. |
finish_day | необязательный | дата в формате дд.мм.гггг | Конечная дата. В этом случае будет показано свободное время от начальной даты. |
service_id | обязательный | число | ID услуги. Будет показано только время сотрудников, которые оказывают эту услугу. Услуги должны быть массивом |
executor_id | обязательный | число | ID сотрудника-исполнителя. Будет возвращено только свободное время выбранного сотрудника |
Внимание! Все переменные записываются в кавычках (' ' или " "). Например, 'Иван'.
Функция возвращает словарь вида:
в случае успеха: {'status': '1', 'result': {'2021-11-25': '2021-11-25 00:00:00', '2021-11-25 01:00:00', '2021-11-25 02:00:00’}}
В случае ошибки, например: {"status":"0","error":"Format not supported or date is not valid. Params must be dd.mm.yyyy"}
В случае, если на сайте не включен онлайн-виджет, или не найдено свободное время функция вернет ответ: {'status': '1', 'result': []}.
Для добавления визита для нового клиента используется функция klientiks_add_record_for_client(executor_id, service_id, start_datetime, name, phone, appointment_id, living_address, birth_date, subclient_name), где:
| Аргумент | Статус | Формат | Краткое описание |
|---|---|---|---|
executor_id | обязательный | число | Идентификатор сотрудника (исполнителя) |
service_id | обязательный | строка | Идентификатор услуги, массив (может быть несколько услуг в визите) |
start_datetime | обязательный | дата в формате дд.мм.гггг чч:мм | Дата и время начала визита |
name | обязательный | строка | Имя клиента |
phone | обязательный | строка | Телефон клиента |
appointment_id | необязательный | число | Идентификатор визита (актуально только при записи на групповое занятие) |
living_address | необязательный | строка | Адрес клиента |
birth_date | необязательный | дата в формате дд.мм.гггг | Дата рождения клиента |
subclient_name | необязательный | строка | Имя субклиента (только для версий с субклиентами) |
Функция возвращает словарь вида:
в случае успеха: {'status': '1', 'result': [{'client': {'id': 7236168, 'name': 'Никола2', 'phone': '79114130045', 'created': '2022-03-12 16:13:41.573838', 'json_data': '{"appointment_confirmation_sms":false}', 'modified': '2022-03-12 16:14:42.149735', 'account_id': 24036, 'country_code': 'RU', 'client_groups': None, 'delay_stat': None, 'unparsed_name': True, 'first_name': 'Никола2', 'patron_name': None, 'second_name': None, 'loyalty_program_status': None, 'demo_entity': False, 'deleted': False, 'author_id': None, 'forbid_roistat_export': False, 'exclude_from_analytics': False, 'responsible_manager_id': None, 'last_appointment_id': None, 'helix_id': None, 'birth_date': '23.02.1993', 'promo_code': None, 'promo_code_activated': None, 'password': None, 'blocked': False, 'ios_last_active': None, 'android_last_active': None, 'failed_push': None, 'phone_operator': None, 'number': '2345678903457', 'external_id': None, 'instagram_name': None, 'telegram_name': None, 'vk_name': None, 'appointment_confirmation_sms': False}, 'appointment': {'id': 11767888, 'start_datetime': '2022-03-13 12:30:00', 'finish_datetime': '2022-03-13 13:30:00', 'appointed_services': [{'id': 17317251, 'appointed_services_executions': [{'name': 'Екатерина', 'id': 121126, 'position': '', 'is_cabinet': False}], 'name': 'Услуга тест', 'service_id': 1214453, 'price': 0, 'duration': 60, 'quantity': 1, 'service_groups': '', 'type': 'service', 'unit_of_measure': None, 'bind_data': '', 'evotor_uuid': None, 'force_certain_supply': None, 'json_data': None, 'mdlp_codes': None}], 'executor_name': 'Екатерина', 'executor_position': '', 'total_cost': '0', 'booked_till': False}]}
в случае ошибки, например: {"status":"0","error":'Missing required variables - service_id'} – отсутствует обязательная переменная "service_id"
Внимание! Если нужно добавить и нового клиента, и его визит, можно воспользоваться предыдущей функцией.
Для добавления нового клиента используется функция klientiks_add_new_clients(phone,name,second_name,email,living_address,sex,appointment_confirmation_sms,patron_name,client_groups), где:
| Аргумент | Статус | Формат | Краткое описание |
|---|---|---|---|
name | обязательный | строка | Имя клиента |
phone | обязательный | строка | Телефон клиента |
second_name | необязательный | строка | Фамилия клиента |
необязательный | строка | email клиента | |
living_address | необязательный | строка | Адрес клиента |
sex | необязательный | число | (1- male, 0 - female) - Пол клиента |
appointment_confirmation_sms | необязательный | число | Подтверждение на согласие получать SMS (1 - согласен, 0 - не согласен) |
patron_name | необязательный | строка | Отчество клиента |
client_groups | необязательный | строка | Группы клиента через запятую |
Внимание! Все переменные записываются в кавычках (' ' или " "). Например, 'Иван'.
Функция возвращает словарь вида:
в случае успеха: {'status': '1', 'result': [{'id': 7236227, 'name': 'Иванов Иван Иванович', 'phone': '+7 (444) 555-00-11', 'created': '2022-03-12 20:19:08.261956', 'modified': '2022-03-12 20:19:08.261956', 'account_id': 24036, 'country_code': 'RU', 'client_groups': 'Новенький', 'delay_stat': None, 'unparsed_name': True, 'first_name': 'Иван', 'patron_name': 'Иванович', 'second_name': 'Иванов', 'loyalty_program_status': None, 'demo_entity': False, 'deleted': False, 'author_id': 121125, 'forbid_roistat_export': False, 'exclude_from_analytics': False, 'responsible_manager_id': None, 'last_appointment_id': None, 'helix_id': None, 'birth_date': None, 'promo_code': None, 'promo_code_activated': None, 'password': None, 'blocked': False, 'ios_last_active': None, 'android_last_active': None, 'failed_push': None, 'phone_operator': None, 'number': '2345678903458', 'external_id': None, 'instagram_name': None, 'telegram_name': None, 'vk_name': None, 'sub_clients': False, 'service_packs': [], 'lead_source': 'бот', 'email': 'test@test.com', 'appointment_confirmation_sms': True, '_phone': '74445550011', 'ap_services': '', 'ap_executors_names': '', 'favourite_services': [], 'favourite_executors': [], 'total_spent': 0, 'appointments_count': 0, 'appointments_cancelled': 0, 'appointments_missed': 0, 'appointments': [], 'new_client': True, 'service_packs_not_active': [], '_modified': 1647116348, '_created': 1647116348, 'new_data': {'id': 7236227, 'name': 'Иванов Иван Иванович', 'phone': '+7 (444) 555-00-11', 'created': '2022-03-12 20:19:08.261956', 'modified': '2022-03-12 20:19:08.261956', 'account_id': 24036, 'country_code': 'RU', 'client_groups': 'Новенький', 'delay_stat': None, 'unparsed_name': True, 'first_name': 'Иван', 'patron_name': 'Иванович', 'second_name': 'Иванов', 'loyalty_program_status': None, 'demo_entity': False, 'deleted': False, 'author_id': 121125, 'forbid_roistat_export': False, 'exclude_from_analytics': False, 'responsible_manager_id': None, 'last_appointment_id': None, 'helix_id': None, 'birth_date': None, 'promo_code': None, 'promo_code_activated': None, 'password': None, 'blocked': False, 'ios_last_active': None, 'android_last_active': None, 'failed_push': None, 'phone_operator': None, 'number': '2345678903458', 'external_id': None, 'instagram_name': None, 'telegram_name': None, 'vk_name': None, 'sub_clients': False, 'service_packs': [], 'lead_source': 'бот', 'email': 'test@test.com', 'appointment_confirmation_sms': True, '_phone': '74445550011', 'ap_services': '', 'ap_executors_names': '', 'favourite_services': [], 'favourite_executors': [], 'total_spent': 0, 'appointments_count': 0, 'appointments_cancelled': 0, 'appointments_missed': 0, 'appointments': [], 'new_client': True, 'service_packs_not_active': [], '_modified': 1647116348, '_created': 1647116348}}, 'order_id': 7236227}]}
в случае ошибки, например: {"status":"0","error":"Missing required variables - name"}
Для удаления визита используется функция klientiks_visit_cancel(visit_id), где: visit_id - обязательный параметр - тип строка - идентификатор визита клиента - например, 1295384
Функция возвращает словарь вида:
в случае успеха: {{'status': '1', 'result': f"Klientiks_visit 1295384 has been cancelled"}
в случае ошибки, например: {'status': '0', 'error': "Klientiks_visit cannot be cancelled"}
Если Вы хотите, чтобы в Salebot номер клиента в шапке заменялся на его имя из журнала Клиентикс CRM, то зайдите в Salebot -> Настройки проекта и в разделе “Общие переменные” введите переменную klientiks_save_name, равную 1:
Теперь при совершении событий из Клиентикс номер клиента будет автоматически заменяться на его имя.
Если в проекте несколько интеграций и включить замену необходимо только у конкретных клиентов, то значение переменной klientiks_save_name = 1 следует задать в калькуляторе нужного блока, а не в общих переменных:
Для настройки webhooks потребуется сгенерировать API-ключ в Salebot. Для этого нужно пройти в Настройки-Ключ доступа к Api-Сгенерировать. Формируем ссылку вида https://chatter.salebot.pro/klientiks_webhook/bf28a54e58066440c50525193a5727c2
Для настройки webhooks в Клиентикс crm следует перейти по следующей ссылке: https://klientiks.ru/clientix/admin/eventHandlers и нажать на “добавить событие-webhook”.
1) Для того чтобы добавить вебхук создание записи на прием, необходимо заполнить следующие поля: событие: Запись клиента на прием адрес запроса: https://chatter.salebot.pro/klientiks_webhook/bf28a54e58066440c50525193a5727c2/?webhook_type=new_visit_record&external_id={{#client}}{{external_id}}{{/client}}&client_id={{#client}}{{id}}{{/client}}&name={{#client}}{{name}}{{/client}}&phone={{client_phone}}&callback=new_visit_has_been_recorded&appointment_date={{appointment_date}}&appointment_time={{appointment_time}}&executor_name={{executor_name}}&executor_phone={{executor_phone}}&services={{services}}&total_cost={{#appointment}}{{total_cost}}{{/appointment}}&position={{#user}}{{position}}{{/user}}&visit_id={{#appointment}}{{id}}{{/appointment}}&bday={{#client}}{{birth_date}}{{/client}} параметры запроса: {107:"1", 47:"1"}
Поля webhook_type, client_id, external_id, name, phone, visit_id являются обязательными!
В адресе запроса они должны выглядеть как в примере: webhook_type=new_visit_record - описание типа запроса client_id={{#client}}{{id}}{{/client}} - внутренний идентификатор клиента(из клиентикс CRM) external_id={{#client}}{{externa_id}}{{/client}} - внешний идентификатор клиента(из salebot) name={{client_name}} - имя клиента phone={{client_phone}} - телефон visit_id={{#appointment}}{{id}}{{/appointment}} - идентификатор визита
Поле callback отвечает за возвращение сообщения о произведенном действии. В Salebot можно добавить реакцию на эту фразу. Можно поставить нужную фразу или оставить фразу по умолчанию: callback=new_visit_has_been_recorded Остальные поля могут быть добавлены/убраны из запроса по необходимости, наполнение - по примеру: appointment_date={{appointment_date}} - дата, на которую происходит запись appointment_time={{appointment_time}} - время, на которое происходит запись executor_name={{executor_name}} - имя специалиста, оказывающего услугу executor_phone={{executor_phone}} - телефон специалиста services={{services}} - услуги, на которые происходит запись total_cost={{#appointment}}{{total_cost}}{{/appointment}} - общая стоимость услуг position={{#user}}{{position}}{{/user}} - должность исполнителя визита bday={{#client}}{{birth_date}}{{/client}} - день рождения клиента
2) редактирование записи на прием событие: Перенос визита, изменение длительности, изменение статуса адрес запроса: https://chatter.salebot.pro/klientiks_webhook/bf28a54e58066440c50525193a5727c2/?webhook_type=visit_record_change&client_id={{#new_data}}{{client_id}}{{/new_data}}&name={{client_name}}&phone={{#new_data}}{{client_phone}}{{/new_data}}&callback=visit_has_been_changed&old_date_start={{#old_data}}{{start_datetime}}{{/old_data}}&old_date_finish={{#old_data}}{{finish_datetime}}{{/old_data}}&old_executor_id={{#old_data}}{{executor_id}}{{/old_data}}&old_executor_name={{#old_data}}{{executor_name}}{{/old_data}}&old_status={{#old_data}}{{status}}{{/old_data}}&new_start_date={{#new_data}}{{start_datetime}}{{/new_data}}&new_finish_date={{#new_data}}{{finish_datetime}}{{/new_data}}&new_status={{#new_data}}{{status}}{{/new_data}}&new_executor_id={{#new_data}}{{executor_id}}{{/new_data}}&new_executor_name={{#new_data}}{{executor_name}}{{/new_data}}&new_start_date={{#new_data}}{{start_date}}{{/new_data}}&new_start_time={{#new_data}}{{start_time}}{{/new_data}}&visit_id={{#new_data}}{{id}}{{/new_data}} параметры запроса: {107:"1", 47:"1"} условия: [{"leftValue":"{{#new_data}}{{status}}{{/new_data}}","rightValue":"cancelled","operator":"!="}]
Поля webhook_type, client_id, name, phone, visit_id являются обязательными!
В адресе запроса они должны выглядеть как в примере: webhook_type=visit_record_change - описание типа запроса client_id={{#new_data}}{{client_id}}{{/new_data}} - id клиента в Клиентикс CRM name={{client_name}} - имя клиента phone={{#new_data}}{{client_phone}}{{/new_data}} - телефон visit_id={{#new_data}}{{id}}{{/new_data}} - идентификатор визита Поле callback отвечает за возвращение сообщения о произведенном действии. В salebot можно добавить реакцию на эту фразу. Можно поставить нужную фразу или оставить фразу по умолчанию: callback=visit_has_been_changed Остальные поля могут быть добавлены/убраны из запроса в зависимости от необходимых данных, наполнение - по примеру: old_start_datetime={{#old_data}}{{start_datetime}}{{/old_data}} - старая дата начала old_date_finish={{#old_data}}{{finish_datetime}}{{/old_data}} - старая дата завершения old_executor_id={{#old_data}}{{executor_id}}{{/old_data}} - id предыдущего специалиста, оказывающего услугу old_executor_name={{#old_data}}{{executor_name}}{{/old_data}} - имя предыдущего специалиста, оказывающего услугу old_status={{#old_data}}{{status}}{{/old_data}} - старый статус услуги(в процессе, назначен, отменен, окончен) new_start_datetime={{#new_data}}{{start_datetime}}{{/new_data}} - новая дата начала new_finish_date={{#new_data}}{{finish_datetime}}{{/new_data}} - новая дата завершения new_status={{#new_data}}{{status}}{{/new_data}} - новый статус услуги(scheduled (запланирована), confirmed (подтверждена), in progress (в процессе оказания услуг) и finished (завершена)) new_executor_id={{#new_data}}{{executor_id}}{{/new_data}} - id нового специалиста, оказывающего услугу new_executor_name={{#new_data}}{{executor_name}}{{/new_data}} - имя нового специалиста, оказывающего услугу new_start_date={{#new_data}}{{start_date}}{{/new_data}} - новая дата начала new_start_time={{#new_data}}{{start_time}}{{/new_data}}- новое время начала Условия для данного вебхука обязательны в том виде, в котором они указаны в примере [{"leftValue":"{{#new_data}}{{status}}{{/new_data}}","rightValue":"cancelled","operator":"!="}] - любой статус, кроме статуса отменен
Поля webhook_type, client_id, name, phone, visit_id являются обязательными!
3) Прием завершен событие: Завершение визита(вызывается для каждого клиента) адрес запроса: https://chatter.salebot.pro/klientiks_webhook/bf28a54e58066440c50525193a5727c2/?webhook_type=visit_finished&client_id={{#client}}{{id}}{{/client}}&external_id={{#client}}{{external_id}}{{/client}}&name={{#client}}{{name}}{{/client}}&phone={{#client}}{{phone}}{{/client}}&callback=visit_has_successfully_ended&start_datetime={{#appointment}}{{start_datetime}}{{/appointment}}&finish_datetime={{#appointment}}{{finish_datetime}}{{/appointment}}&executor_name={{#appointment}}{{executor_name}}{{/appointment}}&status={{#appointment}}{{status}}{{/appointment}}&visit_id={{#appointment}}{{id}}{{/appointment}} параметры запроса: {107:"1", 47:"1"}
Поля webhook_type, client_id,external_id, name, phone, visit_id являются обязательными!
В адресе запроса они должны выглядеть как в примере: webhook_type=visit_finished - описание типа запроса client_id={{#client}}{{id}}{{/client}} - id клиента в Клиентикс CRM external_id={{#client}}{{externa_id}}{{/client}} - внешний идентификатор клиента(из salebot) name={{#client}}{{name}}{{/client}} - имя клиента phone={{#client}}{{phone}}{{/client}} - телефон visit_id={{#appointment}}{{id}}{{/appointment}} - идентификатор визита Поле callback отвечает за возвращение сообщения о произведенном действии. В salebot можно добавить реакцию на эту фразу. Можно поставить нужную фразу или оставить фразу по умолчанию: callback=visit_has_successfully_ended Остальные поля могут быть добавлены/убраны из запроса в зависимости от необходимых данных, наполнение - по примеру: start_datetime={{#appointment}}{{start_datetime}}{{/appointment}} - дата начала finish_datetime={{#appointment}}{{finish_datetime}}{{/appointment}} - дата завершения executor_name={{#appointment}}{{executor_name}}{{/appointment}} - имя специалиста, оказавшего услугу status={{#appointment}}{{status}}{{/appointment}} - статус услуги(завершен)
4) клиент не пришел на прием событие: Перенос визита, изменение длительности, изменение статуса адрес запроса: https://chatter.salebot.pro/klientiks_webhook/bf28a54e58066440c50525193a5727c2/?webhook_type=visit_cancelled&name={{client_name}}&phone={{#new_data}}{{client_phone}}{{/new_data}}&callback=visit_has_been_cancelled_because_clients_absence&disableStatusReset={{#new_data}}{{start_datetime}}{{/new_data}}&id={{#new_data}}{{id}}{{/new_data}}&status={{#new_data}}{{status}}{{/new_data}}&client_id={{#new_data}}{{client_id}}{{/new_data}}&visit_id={{#new_data}}{{id}}{{/new_data}} параметры запроса: {107:"1", 47:"1"} условия:[{"leftValue":"{{#new_data}}{{status}}{{/new_data}}","rightValue":"cancelled","operator":"=="}]
Поля webhook_type, client_id, name, phone, status являются обязательными!
В адресе запроса они должны выглядеть как в примере: webhook_type=visit_cancelled - описание типа запроса client_id={{#new_data}}{{client_id}}{{/new_data}} - id клиента в клиентикс CRM name={{client_name}} - имя клиента phone={{#new_data}}{{client_phone}}{{/new_data}} - телефон status={{#new_data}}{{status}}{{/new_data}} - статус услуги(отменен) visit_id={{#new_data}}{{id}}{{/new_data}} - идентификатор визита Поле callback отвечает за возвращение сообщения о произведенном действии. В salebot можно добавить реакцию на эту фразу. Можно поставить нужную фразу или оставить фразу по умолчанию: callback=visit_has_been_cancelled_because_clients_absence Остальные поля могут быть добавлены/убраны из запроса в зависимости от необходимых данных, наполнение - по примеру: disableStatusReset={{#new_data}}{{start_datetime}}{{/new_data}} - статус отмены(да или нет) id={{#new_data}}{{id}}{{/new_data}} - id клиента в Клиентикс CRM Условия для данного вебхука обязательны в том виде, в котором они указаны в примере [{"leftValue":"{{#new_data}}{{status}}{{/new_data}}","rightValue":"cancelled","operator":"=="}]- срабатывает на значение статуса “отменен”
5) Визит отменен через смс-подтверждение событие: Отмена через подтверждение визитов адрес запроса: https://chatter.salebot.pro/klientiks_webhook/bf28a54e58066440c50525193a5727c2/?webhook_type=visit_cancelled_by_sms&phone={{#client}}{{phone}}{{/client}}&callback=visit_has_been_cancelled_by_sms&name={{#client}}{{name}}{{/client}}&visit_id={{#appointment}}{{id}}{{/appointment}}&status={{#appointment}}{{status}}{{/appointment}}&external_id={{#client}}{{external_id}}{{/client}} параметры запроса: {107:"1", 47:"1"}
Поля webhook_type, client_id, name, phone, status являются обязательными!
В адресе запроса они должны выглядеть как в примере: webhook_type=visit_cancelled_by_sms - описание типа запроса name={{#client}}{{name}}{{/client}} - имя клиента phone={{#client}}{{phone}}{{/client}} - телефон status={{#appointment}}{{status}}{{/appointment}} - статус услуги visit_id={{#appointment}}{{id}}{{/appointment}} - идентификатор визита Поле callback отвечает за возвращение сообщения о произведенном действии. В salebot можно добавить реакцию на эту фразу. Можно поставить нужную фразу или оставить фразу по умолчанию: callback=visit_has_been_cancelled_by_sms
Более подробное описание составления вебхуков можно найти на странице https://klientiks.zendesk.com/hc/ru/articles/115000312125
