Импорт и обновление профиля
В этой статье покажем, как написать и отправить API-запр осы для выполнения следующих задач:
- Добавление профиля в базу данных
- Обновление данных существующего профиля
- Подписка профиля на различные каналы
Получение API-токена
API-токен — это ключ доступа к платформе через API. Он используется в любом API-запросе.
Найти токен можно в настройках платформы Altcraft, в разделе "Токены". Если у вас ещё нет токена, создайте его, нажав на соответствующую кнопку:
API-токен могут создать только мастер-пользователи. Если у вас нет необходимых прав, обратитесь к пользователю с правами мастера.
Установка и запуск Postman
Для работы с API-запросами потребуется приложение, позволяющее отправлять и принимать их.
1. Скачайте и установите приложение Postman или откройте его веб-версию.
2. Выберите метод POST для вашего запроса.
3. Перейдите на вкладку Body и выберите режим raw. Убедитесь, что выбран формат JSON.
URL-адрес запроса
Для отправки запроса на сервер вам необходимо ввести его URL. Он индивидуален для каждого запроса. Например, для запроса на импорт профиля URL-адрес будет таким:
https://example.com/api/v1.1/profiles/import
Замените example.com на домен, на котором развернута ваша платформа. Вы можете скопировать адрес прямо из адресной строки:
Создание запроса
Добавление нового профиля
Перейдем к написанию запроса. Предположим, мы хотим добавить в базу #5 профиль клиента с электронной почтой i.petrov@example.com. Составим запрос:
{
"token": "abcdefghklmnopqrstzxc",
"db_id": 5,
"matching": "email",
"email": "i.petrov@example.com",
"data": {
"email": "i.petrov@example.com"
}
}
- "token" — API-токен. Подробнее о том, где можно его найти, можно прочитать в начале статьи.
- "db_id" — номер базы, в которую добавляется профиль. Это число указано рядом с названием базы профилей справа от знака #.
- "data" — объект, содержащий данные профиля. В примере выше мы передаём в этом объекте только email-адрес клиента.
- "matching" и "email" — параметр для поиска профиля в базе. В данном случае для поиска профиля используется email-адрес. Если профиль с таким адресом уже есть в базе, то запрос обновит его данные, если нет — создаст новый профиль. Параметр "matching" может принимать различные значения. При этом он не является обязательным и, если его не указать, поиск профиля произойдёт по email.
Подробнее о параметре matching
Параметр matching определяет, по какому полю будет происходить поиск профиля в базе данных. В платформе доступно несколько режимов поиска, например, платформа может искать профиль по email-адресу, номеру телефона, системному идентификатору или по любому значению, которое вы храните в дополнительном поле базы.
Главное, чтобы поле, по которому вы запускаете поиск в ба зе, было уникальным для профиля, т.е. значение этого поля не должно совпадать у разных профилей в одной базе.
Если вы хотите найти профиль по его email, то matching будет выглядеть так:
{
"matching": "email",
"email": "example@example.com"
}
Поиск профиля по телефону:
{
"matching": "phone",
"phone": "+79000000000"
}
Поиск профиля по идентификатору (только при обновлении профиля):
{
"matching": "profile_id",
"profile_id": "012452gf62fcd71fjh8ec0"
}
Идентификатор профиля можно найти здесь:
Если для поиска профиля в базе вы используете дополнительное поле, то ваш запрос будет выглядеть так:
{
"matching": "custom",
"field_name": "CRM_ID",
"field_value": "12345"
}
где CRM_ID — это название поля, а 12345 — значение этого поля у профиля.
Больше информации о матчинге вы найдете в этой статье.
Обновление данных профиля
Допустим, мы получили новые данные о клиенте: его зовут Иван Петров, родился 15.01.1990, живёт в Москве, телефон — +79000000000. Теперь нам необходимо обновить профиль и добавить эту информацию. Запрос будет выглядеть так:
{
"token": "abcdefghklmnopqrstzxc",
"db_id": 5,
"matching": "email",
"email": "i.petrov@example.com",
"data": {
"email": "i.petrov@example.com",
"_fname": "Ivan",
"_lname": "Petrov",
"_sex": "male",
"_bdate": "1990-01-15T12:00:00Z",
"_city": "Moscow",
"phones": ["+79000000000"]
}
}
Мы расширили параметр "data" следующими данными:
- "_fname" — имя
- "_lname" — фамилия
- "_bdate" — дата рождения в формате "1990-01-15T12:00:00Z"
- "_sex" — пол, "male" для мужчины, "female" для женщины
- "_city" — город
- "phones" — номер телефона.
Добавление подписок в профиль
Мы обновили профиль и теперь нам нужно подписать его на email, sms и push-каналы в ресурсе #1. Для этого нужно добавить в data массив subsriptions:
{
"token": "abcdefghklmnopqrstzxc",
"db_id": 5,
"matching": "email",
"email": "i.petrov@example.com",
"data": {
"email": "i.petrov@example.com",
"_fname": "Ivan",
"_lname": "Petrov",
"_sex": "male",
"_bdate": "1990-01-15T12:00:00Z",
"_city": "Moscow",
"phones": ["+79000000000"],
"subscriptions": [
{
"channel": "email",
"email": "i.petrov@example.com",
"resource_id": 1
},
{
"channel": "sms",
"phone": "+79000000000",
"resource_id": 1
},
{
"channel": "push",
"provider": "Firefox",
"resource_id": 1,
"subscription_id":"abcdefghijklmnqrstuvwxyz"
}
]
}
}
Для каждого канала связи, через который будет осуществляться рассылка, необходимо указать следующие параметры:
- "channel" — тип канала, например, "email", "sms", "push"
- "resource_id" — идентификатор ресурса, который необходимо настроить заранее.
Также в зависимости от канала, на который вы подписываете профиль, потребуется указать определенные контактные данные. Например, для email-канала — это email-адрес, для sms-канала — номер телефона, а для push-канала — провайдер (provider) и push-токен (subscription_id).
Обратите внимание на синтаксис вашего запроса. Лишние символы или незакрытые скобки могут привести к ошибке.
Отправка запроса
Чтобы отправить запрос, нажмите кнопку Send в Postman. При успешном выполнении вы получите сообщение об успешной отправке запроса:
Если что-то пошло не так, в ответном сообщении будет указан код ошибки и ее описание:
Если у вас не получилось самостоятельно устранить ошибку, передайте код и описание ошибки в службу поддержки Altcraft.
Хотя в статье описано поэтапное добавление и обновление данных профиля, на практике вы можете сразу отправить финальный запрос. Если профиль с указанными данными уже существует в базе, он будет обновлен, а если нет — будет создан новый профиль с полными данными и подписками на ресурс.
В статье описывается лишь часть возможных параметров для данного запроса. С остальными параметрами можно ознакомиться здесь.