Читать 17

Импорт данных по клиентам

Описание

Метод позволяет импортировать данные по клиентам из внешних источников в Calltouch. Это полезно, когда вы хотите объединить свою клиентскую базу с данными, собранными системой автоматически.

Как работает метод

Метод использует логику матчинга по контактам (Телефон, Email, VK ID, Telegram ID, Telegram Username, WhatsApp). Если контакт из передаваемых данных совпадает с существующим клиентом в системе — метод обновляет (обогащает) этого клиента новой информацией. Если клиента с таким контактом нет — метод создает нового клиента с передаваемыми данными.

Какими данными можно обогатить клиента

При импорте вы можете передавать следующие типы данных:

Контактная информация — основные и дополнительные телефоны, email-адреса, контакты в мессенджерах (VK, Telegram, WhatsApp).
ФИО — полное имя клиента.
Теги — присвоить клиенту теги для быстрой классификации.
Ответственные менеджеры — назначить менеджеров для работы с клиентом.
Информация о сессиях — связать клиента с его цифровым следом на вашем сайте. Система найдет все сессии и взаимодействия, связанные с переданными идентификаторами, и добавит их в историю клиента.
Комментарии — добавить заметки по клиенту.
Пользовательские поля — передавать дополнительные атрибуты клиента.

С помощью пользовательских полей можно расширить возможности системы. Передавайте в пользовательские поля любые данные, релевантные вашему бизнесу: дату рождения клиента, семейное положение, наличие детей, компанию, тип покупателя и т.д. Эти данные отображаются в журнале клиентов, используются для фильтрации и работы с целевыми клиентами.

API-метод для импорта данных по клиентам

Запрос

POST:

https://api.calltouch.ru/clients-service/v1/api/client/import

HTTP-заголовки:

Access-Token — API-ключ;
SiteId — ID ЛК Calltouch.

Тело запроса в формате JSON.

Пример тела запроса

{
    "clients": [
        // клиент 1
        {
            "externalClientId": "123321",
            "clientContacts": {
                "mainContacts": {
                   "fio": "Иван",
                   "phoneNumber": "79000000000",
                   "email": "test@test.ru",
                   "vkId": "12345",
                   "tgId": "12345",
                   "tgUsername": "testuser1",
                   "waPhoneNumber": "79000000000"
               },
               "otherContacts": {
                   "phoneNumber": ["79000000001","79000000002"],
                   "email": ["test2@test.ru","test3@test.ru"],
                   "vkId": ["123456"],
                   "tgId": ["123456"],
                   "tgUsername": ["testuser2"],
                   "waPhoneNumber": ["79000000001"]
                }
            },
            "tags": [ "Тег1", "Тег2" ],
            "managers": [ "Менеджер1", "Менеджер2" ],
            "customFields": [
                {"field": "birthday", "value": "01-01-1991"},
                {"field": "car", "value": "lada"},
                {"field": "points", "value": 123}
            ],
            "comment": {
                "text": "Комментарий"
            },
            "sessionsInfo": {
                "sessionId": ["1234567"],
                "ctClientId": ["1234567"],
                "ctGlobalId": ["1234567"],
                "gaClientId": ["1234567"],
                "yaClientId": ["1234567"],
                "attrs": [{"value": "1234567", "name": "myuserid_1"}]
            }
        },
        ...
        // клиент 2
        ...
    ]
}

Параметры запроса

Параметр	Формат	Обязательный	Описание
clients	array	Да	Массив импортируемых данных по клиентам. Один элемент массива соответствует данным по одному клиенту. Ограничения: максимум 100 клиентов за один запрос.
clients[n].externalClientId	string	Нет	ID клиента из внешней системы. Формат: любые символы. Может быть не заполнен или повторяться у разных клиентов. Ограничения: максимум 50 символов. Используется как дополнительный контакт при сопоставлении импортируемых данных с существующими клиентами Calltouch.
clients[n].clientContacts	object	Да	Данные по контактам клиента.
clients[n].clientContacts. mainContacts	object	Да	Данные по основным контактам клиента.
clients[n].clientContacts. mainContacts. fio	string	Нет	ФИО клиента. Формат: любые символы. Ограничения: максимум 50 символов.
clients[n].clientContacts. mainContacts. phoneNumber	strin	Да, должен быть указан хотя бы один контакт из: phoneNumber, email, vkId, tgUsername, waPhoneNumber При совместном указании параметров mainContacts и otherContacts, при передаче в otherContacts параметра phoneNumber - в mainContacts обязательно тоже должен быть передан phoneNumber.	Основной номер телефона клиента. Номера могут быть в любом формате (71234567890, +71234567890, 8 (123) 456-78-90 и т.д.) Ограничения: максимум 50 символов.
clients[n].clientContacts. mainContacts. email	string	Да, должен быть указан хотя бы один контакт из: phoneNumber, email, vkId, tgUsername, waPhoneNumber При совместном указании параметров mainContacts и otherContacts, при передаче в otherContacts параметра email - в mainContacts обязательно тоже должен быть передан email.	Основной email клиента. Формат: xxx@domen.xx Ограничения: максимум 50 символов.
clients[n].clientContacts. mainContacts. vkId	string	Да, должен быть указан хотя бы один контакт из: phoneNumber, email, vkId, tgUsername, waPhoneNumber При совместном указании параметров mainContacts и otherContacts, при передаче в otherContacts параметра vkId - в mainContacts обязательно тоже должен быть передан vkId.	Основной ID ВКонтакте клиента. Формат: только цифры. Ограничения: максимум 50 символов.
clients[n].clientContacts. mainContacts. tgId	string	Нет При совместном указании параметров mainContacts и otherContacts, при передаче в otherContacts параметра tgId - в mainContacts обязательно тоже должен быть передан tgId.	Основной ID Telegram клиента. Формат: только цифры. Ограничения: максимум 50 символов.
clients[n].clientContacts. mainContacts. tgUsername	string	Да, должен быть указан хотя бы один контакт из: phoneNumber, email, vkId, tgUsername, waPhoneNumber При совместном указании параметров mainContacts и otherContacts, при передаче в otherContacts параметра tgUsername - в mainContacts обязательно тоже должен быть передан tgUsername.	Основной Telegram Username клиента. Формат: любые символы. Ограничения: максимум 50 символов.
clients[n].clientContacts. mainContacts. waPhoneNumber	string	Да, должен быть указан хотя бы один контакт из: phoneNumber, email, vkId, tgUsername, waPhoneNumber При совместном указании параметров mainContacts и otherContacts, при передаче в otherContacts параметра waPhoneNumber - в mainContacts обязательно тоже должен быть передан waPhoneNumber.	Основной номер телефона из Whatsapp клиента. Номера могут быть в любом формате (71234567890, +71234567890, 8 (123) 456-78-90 и т.д.) Ограничения: максимум 50 символов.
clients[n].clientContacts. otherContacts	object	Нет	Данные по дополнительным контактам клиента.
clients[n].clientContacts. otherContacts. phoneNumber	array	Нет	Массив из дополнительных номеров телефона клиента. Номера могут быть в любом формате (71234567890, +71234567890, 8 (123) 456-78-90 и т.д.) Ограничения: максимум 10 элементов в массиве, до 50 символов каждый.
clients[n].clientContacts. otherContacts. email	array	Нет	Массив из дополнительных email клиента. Формат: xxx@domen.xx Ограничения: максимум 10 элементов в массиве, до 50 символов каждый.
clients[n].clientContacts. otherContacts. vkId	array	Нет	Массив из дополнительных ID ВКонтакте клиента. Формат: только цифры. Ограничения: максимум 10 элементов в массиве, до 50 символов каждый.
clients[n].clientContacts. otherContacts. tgId	array	Нет	Массив из дополнительных ID Telegram клиента. Формат: только цифры. Ограничения: максимум 10 элементов в массиве, до 50 символов каждый.
clients[n].clientContacts. otherContacts. tgUsername	array	Нет	Массив из дополнительных Telegram Username клиента. Формат: любые символы. Ограничения: максимум 10 элементов в массиве, до 50 символов каждый.
clients[n].clientContacts. otherContacts. waPhoneNumber	array	Нет	Массив из дополнительных номеров телефона из Whatsapp клиента. Номера могут быть в любом формате (71234567890, +71234567890, 8 (123) 456-78-90 и т.д.) Ограничения: максимум 10 элементов в массиве, до 50 символов каждый.
clients[n].tags	array	Нет	Массив из тегов клиента. Формат: любые символы. Ограничения: до 50 символов на один тег, максимум 50 тегов.
clients[n].managers	array	Нет	Массив из менеджеров клиента. Формат: любые символы. Ограничения: до 50 символов в одном менеджере, максимум 10 менеджеров.
clients[n].customFields	array	Нет	Пользовательские поля клиента. Массив объектов с дополнительными атрибутами клиента. Формат: "customFields": [ {"field": "name", "value": "Вася"}, {"field": "birthday", "value": "1990-01-01"} ] В field передается название пользовательского поля в API, в value передается значение пользовательского поля. Требования: Максимум: 20 пользовательских полей на клиента Поле должно существовать: все указанные поля должны быть предварительно созданы в ЛК (раздел API настроек). Несуществующее поле вызовет ошибку валидации. Валидация: правила зависят от типа поля, настроенного в системе (аналогично валидации в API создания звонков, заявок и сделок) Параметры: field Название поля в API, как указано в настройках ЛК. Формат: только английские буквы, дефис «-», подчеркивание «_». Максимум 100 символов. value Значение поля. Формат зависит от типа: Текстовое — строка до 100 символов Числовое — целое или дробное число (дробная часть через точку), до 100 символов. Дата — формат "DD-MM-YYYY hh:mm:ss" или только "DD-MM-YYYY" Подробнее о настройке и валидации пользовательских полей см. в справке Пользовательские поля в API.
clients[n].comment.text	string	Нет	Комментарий к клиенту. Формат: любые символы. Ограничения: максимум 500 символов.
clients[n].sessionsInfo	object	Нет	Данные для связи клиента с его цифровым следом на вашем сайте. Система использует переданные идентификаторы для поиска существующих сессий и взаимодействий клиента, и если находит — обогащает историю клиента всеми связанными данными.
clients[n].sessionsInfo. sessionId	array	Нет	Массив из ID сессий Calltouch клиента, зафиксированные на вашем сайте. Формат: только цифры. Ограничения: максимум 20 элементов в массиве, до 50 символов каждый.
clients[n].sessionsInfo. ctClientId	array	Нет	Массив из ID куки Calltouch клиента, зафиксированные на вашем сайте. Формат: любые символы. Ограничения: максимум 20 элементов в массиве, до 50 символов каждый.
clients[n].sessionsInfo. ctGlobalId	array	Нет	Массив из ID глобальной куки Calltouch клиента, зафиксированные на вашем сайте. Формат: любые символы. Ограничения: максимум 20 элементов в массиве, до 50 символов каждый.
clients[n].sessionsInfo. gaClientId	array	Нет	Массив идентификаторов клиента, зафиксированных в Google Analytics на вашем сайте. Формат: любые символы. Ограничения: максимум 20 элементов в массиве, до 50 символов каждый.
clients[n].sessionsInfo. yaClientId	array	Нет	Массив идентификаторов клиента, зафиксированных в Яндекс.Метрика на вашем сайте. Формат: любые символы. Ограничения: максимум 20 элементов в массиве, до 50 символов каждый.
clients[n].sessionsInfo. attrs	array	Нет	Массив дополнительных атрибутов сессии клиента с вашего сайта. Ограничения: максимум 20 элементов в массиве. Формат: "attrs": [ {"value": "1234567", "name": "myuserid_1"} ] В value — любые символы, максимум 50 символов. В name — любые символы, максимум 50 символов.

Ответ

Импорт данных выполняется асинхронно. При успешной валидации запроса вы получите ответ с logId - уникальным идентификатором операции. Используйте этот ID для проверки статуса импорта через отдельный API-запрос.

Пример ответа

{
    "meta": [],
    "data": {
        "logId": 1234
    }
}

Параметры ответа

Параметр	Формат	Описание
data.logId	integer	Уникальный идентификатор операции импорта данных по клиентам.

API-метод для получение статуса импорта данных по клиентам

Запрос

POST:

https://api.calltouch.ru/clients-service/v1/api/client/import/status?logId=ID_лога

HTTP-заголовки:

Access-Token — API-ключ;
SiteId — ID ЛК Calltouch.

Параметры запроса

Параметр	Формат	Обязательный	Описание
logId	integer	Да	Уникальный идентификатор операции импорта данных по клиентам. Передайте этот ID как GET-параметр в URL запроса для получение статуса импорта.

Ответ

В ответе содержится актуальная информация о статусе операции импорта и результаты обработки каждого клиента. Вы получите параметр status — статус импорта, и массив clients — результаты с информацией об успешности импорта каждого клиента, его ID в Calltouch, статусе создания/обновления, ошибках (если они были) и контактных данных из исходного запроса.

Пример ответа

{
    "meta": [],
    "data": {        
        "status": "success",
        "clients": [
            {
                "externalClientId": null,
                "clientContacts": {
                    "mainContacts": {
                       "fio": "Иван",
                       "phoneNumber": "79000000000",
                   },
                   "otherContacts": {
                       "phoneNumber": ["79000000001","79000000002"]
                   }
                },
                "imported": true,
                "clientId": "f19e7a17-e913-4b4d-a14c-e3e31d08352d",
                "isCreatedNew": true,
                "errorCode": null,
                "error": null
            },
            {
                "externalClientId": '123321',
                "clientContacts": {
                    "mainContacts": {
                       "phoneNumber": "79000000003",
                   }
                },
                "imported": false,
                "clientId": null,
                "isCreatedNew": null,
                "errorCode": 3,
                "error": "Пояснение ошибки при импорте"
            }
        ]
    }
}

Параметры ответа

Параметр	Формат	Описание
data.status	string	Текущий статус импорта данных по клиентам. Возможные значения: import_in_progress — процесс импорта выполняется. success — процесс импорта успешно завершен, некоторые данные по некоторым клиентам могли не быть импортированы из-за ошибок, но процесс в целом отработал успешно в штатном режиме. error — процесс импорта завершился с ошибкой, никакие данные не были импортированы. delete_in_progress — выполняется процесс удаления. deleted —- импортированные данные были удалены.
data.clients	array	Массив данных по импортированным клиентам. Отдается только если data.status=success
data.clients[n]. externalClientId	string	Внешний ID импортируемого клиента. Может быть null если в исходном запросе на импорт клиентов externalClientId не был передан.
data.clients[n]. clientContacts	object	Объект с контактами, которые были переданы в исходном запросе на импорт. Содержит в себе mainContacts и otherContacts в таком же формате, как они были переданы в исходном запросе на импорт клиентов.
data.clients[n]. imported	boolean	Флаг успешности импорта клиента. Возможные значения: true — импорт данных по клиенту прошел успешно false — при импорте возникла ошибка
data.clients[n]. clientId	string	ID клиента в Calltouch. Это либо ID существующего клиента, который был обновлен, либо ID новосозданного клиента. `null` если при импорте возникла ошибка.
data.clients[n]. isCreatedNew	boolean	Флаг создания нового клиента в Calltouch на основе переданных в импорте данных. Возможные значения: true — был создан новый клинет false — был обновлен существующий клиент `null` если при импорте возникла ошибка.
data.clients[n]. errorCode	integer	Внутренний код ошибки при импорте клиента. Возвращается только если при импорте возникла ошибка. `null` если импорт прошел успешно.
data.clients[n]. error	string	Текстовое описание ошибки при импорте клиента. Возвращается только если при импорте возникла ошибка. `null` если импорт прошел успешно.

API-метод для удаления импорта данных по клиентам

Запрос

POST:

https://api.calltouch.ru/clients-service/v1/api/client/import/delete?logId=ID_лога

HTTP-заголовки:

Access-Token — API-ключ;
SiteId — ID ЛК Calltouch.

Параметры запроса

Параметр	Формат	Обязательный	Описание
logId	integer	Да	Уникальный идентификатор операции импорта данных по клиентам. Передайте этот ID как GET-параметр в URL запроса для удаления импортированных данных и отмены всех связанных обновлений клиентов.

Ответ

Удаление импорта выполняется асинхронно. В ответе возвращается статус delete_in_progress, указывающий, что удаление было инициировано. При завершении удаления будут удалены все клиенты, созданные при импорте, и отменены все связанные обновления.

Пример ответа

{
    "meta": [],
    "data": {        
        "status": "delete_in_progress"
    }
}

Параметры ответа

Параметр

Формат

Описание

data.status

string

Статус операции удаления импорта.

После поступления запроса на удаление импорта — статус импорта меняется на "delete_in_progress". Этот статус отдается в ответе.

После успешного завершения удаления статус изменится на "deleted".

Для проверки текущего статуса используйте метод получения статуса импорта данных по клиентам.

Типовые ошибки

При обнаружении ошибок валидации (код 400) импорт не выполняется. API возвращает описание проблемы с указанием поля:

{
    "meta": [],
    "data": {
        "type": "validationError",
        "apiErrorData": null,
        "validationErrorData": {
            "violations": [
                {
                    "fieldPath": "Путь к полю с ошибкой",
                    "message": "Описание ошибки"
                }
            ]
        }
    }
}

Cписок типовых ошибок авторизации и валидации вы можете посмотреть в справке об ошибках API.

Система баллов API

Система баллов API — механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное и часовое количество баллов. За каждый успешно выполненный запрос списываются баллы. Подробнее читайте в статье: Система баллов API Calltouch.

Таблица стоимости методов импорта данных по клиентам:

Метод	URL	Экспорт /импорт	За успешный вызов	За объект
API-методы импорта данных по клиентам	https://api.calltouch.ru/clients-service/v1/api/client/import	Импорт	10	5
	https://api.calltouch.ru/clients-service/v1/api/client/import/status	Импорт	2	—
	https://api.calltouch.ru/clients-service/v1/api/client/import/delete	Импорт	10	—

Количество запросов в секунду к API Calltouch ограничено — не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой c кодом 429 (Too Many Requests).

04 января 2026

Не нашли решение проблемы?

Заполните форму, и мы вам поможем.

Оцените статью

Общая информация

Элементы сценариев

Импорт данных по клиентам

Описание

Как работает метод

Какими данными можно обогатить клиента

API-метод для импорта данных по клиентам

Запрос

Пример тела запроса

Параметры запроса

Ответ

Пример ответа

Параметры ответа

API-метод для получение статуса импорта данных по клиентам

Запрос

Параметры запроса

Ответ

Пример ответа

Параметры ответа

API-метод для удаления импорта данных по клиентам

Запрос

Параметры запроса

Ответ

Пример ответа

Параметры ответа

Типовые ошибки

Система баллов API