Импорт и обновление профиля

В этой статье покажем, как написать и отправить 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.

подсказка

Хотя в статье описано поэтапное добавление и обновление данных профиля, на практике вы можете сразу отправить финальный запрос. Если профиль с указанными данными уже существует в базе, он будет обновлен, а если нет — будет создан новый профиль с полными данными и подписками на ресурс.

подсказка

В статье описывается лишь часть возможных параметров для данного запроса. С остальными параметрами можно ознакомиться здесь.