Регистрация события достижения цели

Описание

Запрос регистрирует событие достижения цели. В рамках регистрации события также можно передавать дополнительную информацию о профиле.

Данные о событии достижения цели можно использовать в следующих механиках платформы:

сегментация профилей по истории действий;
запуск триггерной рассылки или сценария;
движение профиля по сценарию (узлы "Условие", "JSON-фильтр" и "Вызов API");
подставновка динамического контента в шаблоны сообщений.

URL-адрес

Метод: POST

https://example.com/api/v1.1/goals/register

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

Основные параметры

Параметр	Тип	Пример	Обязательный	Описание
token	string	"abcdefghijklmnqrstuvwxyz"	Да	API-токен
db_id	int	1	Да	Идентификатор базы данных
pixel_id	int	1	Да	Идентификатор пикселя
goal	string	"card"	Нет	Название цели
goals	JSON array	`[ { "goal": "card", "value": 10.0 } ]`	Нет	Несколько целей со значениями
value	float	-25.5	Нет	Значение цели
date	string	"2006-01-25T15:04:05+07:00"	Нет	Дата события в формате RFC 3339

Параметры матчинга

Эти параметры используются для поиска профиля в базе. Подробнее.

Параметр	Тип	Пример	Обязательный	Описание
matching	string	"email" – поиск по email из профиля или подписок "email_profile" – по email из профиля "email_sub" – по email из подписок "phone" – по телефону из профиля или подписок "phone_sub" – по телефону из подписок "profile_id" – по идентификатору профиля (только при обновлении!) "push_sub" – по пуш подписке "custom" – по кастомному полю "custom_sub" – по подписке на кастомный канал "email_phone" – по email или телефону из профиля "email_phone_sub" – по email или телефону из подписок	Нет, если поиск по email из профиля или подписок	Режим поиска подписчика. По умолчанию - email.
email	string	"john@example.com"	"matching":"email" - по профилю и подпискам "matching":"email_profile" - только по профилю	Email-адрес
phone	string	"+79000000000"	"matching":"phone"	Номер телефона
profile_id	string	"abcdefghijklmnqrstuvwxyz"	"matching":"profile_id"	Идентификатор профиля
field_name	string	"CRM_ID"	"matching":"custom"	Название кастомного поля профиля для поиска.
field_value	int/string	"12345"	"matching":"custom"	Значение кастомного поля для поиска. Доступен поиск по сочетанию значений поля с типом "теги". Теги передаются в строке черз запятую: "тег_1, тег_2".

Дополнительные параметры

Параметр	Тип	Пример	Обязательный	Описание
pixel_data	JSON object	`{ "key":"value", "array":[1,2,3] }`	Нет	JSON-объект с дополнительными данными события цели. Объект не должен содержать вложенные объекты или массивы. Размер объекта не больше 1 KB.
skip_triggers	bool	false	Нет	Отключает настроенные на событие триггеры и сценарии. По умолчанию — false.
enrich_profile	bool	true	Нет	Событие обновляет данные профиля. Используется для обновления данных через следующие поля: browser, os, device, country, region, city, zip, time_zone.
is_test	bool	false	Нет	Событие отмечается как тестовое для аналитики. По умолчанию — false.
vendor	string	"altcraft"	Нет	Поле профиля `_vendor` на момент события
external_type	string	"event_pixel_test"	Нет	Тип внешнего идентификатора
external_event_id	string	"qwerty123"	Нет	Внешний идентификатор
altcraft_client_id	string	"9f11d32d-2935-43d0-b8df-f4c3568095b2"	Нет	Уникальный сквозной идентификатор Altcraft

HTTP-параметры

Параметр	Тип	Пример	Обязательный	Описание
referer	string	"api.example.com"	Нет	Заголовок запроса Referer
user_agent	string	"Mozilla/5.0 (Linux; Android 6.0.1; SM-G935S Build/MMB29K; wv)"	Нет	Заголовок запроса User-Agent
accept_language	string	"fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5"	Нет	Язык операционной системы устройства клиента (Заголовок запроса Accept-Language)
client_ip	string	"10.0.0.0"	Нет	IP клиента из оригинального запроса
client_ip_v4	string	"198.16.74.224"	Нет	IPv4 адрес клиента
client_ip_v6	string	"fe80::5215:5556:d75f:806b"	Нет	IPv6 адрес клиента
browser	string	"Chrome"	Нет	Браузер клиента Получить список допустимых значений можно через запрос `/v1.1/dictionary ("browsers")`
os	string	"Ubuntu"	Нет	Операционная система клиента Получить список допустимых значений можно через запрос `/v1.1/dictionary ("oses")`
device	string	"Desktop"	Нет	Тип клиентского устройства Получить список допустимых значений можно через запрос `/v1.1/dictionary ("devices")`

подсказка

Поля browser, os и device автоматически заполняются платформой на основе содержимого поля user_agent.

Если в одном запросе вы передаёте и user_agent, и отдельные значения для browser, os и device, то данные из user_agent имеют приоритет и перезаписывают указанные значения.

Если вы передаёте поля browser, os и device без user_agent, для обновления профиля необходимо указать "enrich_profile": true, иначе платформа не обновит профиль.

Параметры геолокации

Платформа автоматически определит значения, если передать client_ip.

Параметр	Тип	Пример	Обязательный	Описание
lat	float	55.244075	Да, если передаётся lon	Широта клиента
lon	float	55.244075	Да, если передаётся lat	Долгота клиента
country	string	"RU"	Нет	Страна клиента (ISO-код или полное название)
region	string	"Ryazan"	Нет	Регион клиента
city	string	"Ryazan"	Нет	Город клиента
address	string	"Pochtovaya street"	Нет	Адрес клиента
zip	string	"390000"	Нет	Почтовый индекс клиента
time_zone	string	"Europe/Moscow"	Нет	Часовой пояс

подсказка

Платформа автоматически определяет значения полей country, region, city, zip и time_zone на основе IP-адреса, переданного в параметрах client_ip, client_ip_v4 или client_ip_v6. Если в запросе указаны как IP-адрес, так и отдельные значения для этих полей, данные, определённые по IP, будут иметь приоритет и перезапишут переданные вручную значения.

Для обновления профиля с использованием значений из полей country, region, city, zip и time_zone необходимо установить параметр "enrich_profile": true.

UTM-параметры

Параметр	Тип	Пример	Обязательный	Описание
utm_content	string	"utm_content"	Нет	UTM параметры
utm_medium	string	"utm_medium"	Нет
utm_source	string	"utm_source"	Нет
utm_campaign	string	"utm_campaign"	Нет
utm_term	string	"utm_term"	Нет

Параметры сети

Параметр	Тип	Пример	Обязательный	Описание
net_ssid	string	"10.200.0.0"	Нет	Имя сети клиента
net_mac_addr	string	"28:87:ba:c1:0d:5e"	Нет	MAC-адрес клиента
net_gateway_ipv4	string	"10.200.0.1"	Нет	IPv4 адрес шлюза клиента
net_gateway_ipv6	string	"::ff"	Нет	IPv6 адрес шлюза клиента

Параметры рассылки

Параметр	Тип	Пример	Обязательный	Описание
send_message_id	string	"abcdefghijklmnqrstuvwxyz"	Нет	Идентификатор отправленного сообщения в платформе. Позволяет связать событие пикселя с конкретной рассылкой.

Параметры программы лояльности

Параметр	Тип	Пример	Обязательный	Описание
loyalty_id	int	5	Нет	Идентификатор программы лояльности
promo_id	string	"6285183c3f62fcd4ac5ed36d"	Нет	Идентификатор привязанного промокода

Параметры маркета

Параметр	Тип	Пример	Обязательный	Описание
endpoint_eid	string	"example_endpoint"	Нет	Внешний идентификатор точки контакта. Если для пикселя выбрана определенная база профилей, то эта база должна совпадать с базой канала продаж.
order_eid	string	"12345"	Нет	Внешний идентификатор заказа
product_eid	string	"example_product"	Да, если передается sku_eid	Внешний идентификатор продукта
sku_eid	string	"example_sku"	Нет	Внешний идентификатор SKU. При использовании этого параметра в запросе также необходимо передавать product_eid.
region_eid	string	"region_eYFe2AE6s"	Нет	Внешний идентификатор региона
count_items	int	1	Нет	Количество товара в позиции заказа
categories	array	`[ "category_1", "category_2" ]`	Нет	Категории продукта или SKU

к сведению

Максимальная длина любого строкового поля — 128 символов.

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

Пример запроса для регистрации одной цели и её значения

JSON
XML

{
    "token": "91f1dfa81c264a938b475677c60ce967",
    "db_id": 1,
    "goal": "card",
    "pixel_id": 1,
    "referer": "api.example.com",
    "value": -25.5,
    "matching":"profile_id",
    "profile_id": "abcdefghijklmnqrstuvwxyz"
}

<xml>
    <token>abcdefghijklmnqrstuvwxyz</token>
    <db_id>1</db_id>
    <goal>card</goal>
    <pixel_id>1</pixel_id>
    <referer>api.example.com</referer>
    <value>-25.5</value>
    <matching>profile_id</matching>
    <profile_id>abcdefghijklmnqrstuvwxyz</profile_id> 
</xml>

Пример запроса для регистрации нескольких целей и их значений

JSON
XML

{
    "token": "abcdefghijklmnqrstuvwxyz",
    "client_ip": "10.20.30.40",
    "db_id": 24,
    "goals": [
        {
            "goal": "view product",
            "value": 10.99
        },
        {
            "goal": "add to cart",
            "value": -12.34
        }
    ],
    "pixel_id": 7,
    "matching": "profile_id",
    "profile_id": "abcdefghijklmnqrstuvwxyz",
    "referer": "api.req.from.my.site"
}

<xml>
    <token>abcdefghijklmnqrstuvwxyz</token>
    <client_ip>10.20.30.40</client_ip>
    <db_id>24</db_id>
    <goals>
        <goal>view product</goal>
        <value>10.99</value>
    </goals>
    <goals>
        <goal>add to cart</goal>
        <value>-12.34</value>
    </goals>
    <pixel_id>7</pixel_id>
    <matching>profile_id</matching>
    <profile_id>abcdefghijklmnqrstuvwxyz</profile_id>
    <referer>api.req.from.my.site</referer>
</xml>

Пример запроса для передачи дополнительной информации о событии

JSON
XML

{
    "token": "abcdefghijklmnqrstuvwxyz",
    "db_id": 24,
    "goals": [
        {
            "goal": "cart",
            "value": 10.99
        },
        {
            "goal": "two",
            "value": -12.34
        }
    ],
    "client_ip": "192.168.0.0",
    "pixel_id": 7,
    "referer": "api.req.from.my.site",
    "accept_language": "fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5",
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
    "matching": "profile_id",
    "profile_id": "abcdefghijklmnqrstuvwxyz",
    "pixel_data": {
        "hello": "hi",
        "arr": [
            1,
            2,
            3
        ],
        "int_val": 56893,
        "bool_val": true,
        "date_val": "2023-08-12"
    },
    "skip_triggers": false,
    "enrich_profile": true,
    "is_test": true,
    "vendor": "altcraft",
    "external_type": "event_pixel_test",
    "external_event_id": "qwerty123",
    "altcraft_client_id": "9f11d32d-2935-43d0-b8df-f4c3568095b2",
    "browser": "Chrome",
    "os": "Ubuntu",
    "device": "Desktop",
    "utm_content": "utm_content",
    "utm_medium": "utm_medium",
    "utm_source": "utm_source",
    "utm_campaign": "utm_campaign",
    "utm_term": "utm_term",
    "client_ip_v4": "198.16.74.224",
    "client_ip_v6": "fe80::5215:5556:d75f:806b",
    "net_ssid": "10.200.0.0",
    "net_mac_addr": "28:87:ba:c1:0d:5e",
    "net_gateway_ipv4": "10.200.0.1",
    "net_gateway_ipv6": "::ff",
    "loyalty_id": 5,
    "promo_id": "abcdefghijklmnqrstuvwxyz",
    "endpoint_eid": "online_store",
    "order_eid": "12345",
    "product_eid": "hd_450_bt_earphones",
    "sku_eid": "hd_450bt_earphones_black",
    "region_eid": "region_eYFe2AE6s",
    "count_items": 1,
    "categories": [
        "category_KBZ1qurFP"
    ],
    "lat": 55.244075,
    "lon": 19.379932,
    "country": "RU",
    "region": "Ryazan",
    "city": "Ryazan",
    "address": "Pochtovaya street",
    "zip": "390000",
    "time_zone": "Europe/Moscow",
    "send_message_id": "w4Wq877djSG1_2_a1_6t_2p_U_2_g.2UCSmxz7zFnuCfCMK_5KmKH9"
}

<xml>
    <token>abcdefghijklmnqrstuvwxyz</token>
    <db_id>24</db_id>
    <goals>
        <goal>cart</goal>
        <value>10.99</value>
    </goals>
    <goals>
        <goal>two</goal>
        <value>-12.34</value>
    </goals>
    <client_ip>192.168.0.0</client_ip>
    <pixel_id>7</pixel_id>
    <referer>api.req.from.my.site</referer>
    <accept_language>fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5</accept_language>
    <user_agent>Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36</user_agent>
    <matching>profile_id</matching>
    <profile_id>651516181a5c52f94532fb1d</profile_id>
    <pixel_data>
        <hello>hi</hello>
        <arr>1</arr>
        <arr>2</arr>
        <arr>3</arr>
        <int_val>56893</int_val>
        <bool_val>true</bool_val>
        <date_val>2023-08-12</date_val>
    </pixel_data>
    <skip_triggers>false</skip_triggers>
    <enrich_profile>true</enrich_profile>
    <is_test>true</is_test>
    <vendor>altcraft</vendor>
    <external_type>event_pixel_test</external_type>
    <external_event_id>qwerty123</external_event_id>
    <altcraft_client_id>9f11d32d-2935-43d0-b8df-f4c3568095b2</altcraft_client_id>
    <browser>Chrome</browser>
    <os>Ubuntu</os>
    <device>Desktop</device>
    <utm_content>utm_content</utm_content>
    <utm_medium>utm_medium</utm_medium>
    <utm_source>utm_source</utm_source>
    <utm_campaign>utm_campaign</utm_campaign>
    <utm_term>utm_term</utm_term>
    <client_ip_v4>198.16.74.224</client_ip_v4>
    <client_ip_v6>fe80::5215:5556:d75f:806b</client_ip_v6>
    <net_ssid>10.200.0.0</net_ssid>
    <net_mac_addr>28:87:ba:c1:0d:5e</net_mac_addr>
    <net_gateway_ipv4>10.200.0.1</net_gateway_ipv4>
    <net_gateway_ipv6>::ff</net_gateway_ipv6>
    <loyalty_id>5</loyalty_id>
    <promo_id>6285183c3f62fcd4ac5ed36d</promo_id>
    <endpoint_eid>online_store</endpoint_eid>
    <order_eid>12345</order_eid>
    <product_eid>hd_450_bt_earphones</product_eid>
    <sku_eid>hd_450bt_earphones_black</sku_eid>
    <region_eid>region_eYFe2AE6s</region_eid>
    <count_items>1</count_items>
    <categories>category_KBZ1qurFP</categories>
    <lat>55.244075</lat>
    <lon>19.379932</lon>
    <country>RU</country>
    <region>Ryazan</region>
    <city>Ryazan</city>
    <address>Pochtovaya street</address>
    <zip>390000</zip>
    <time_zone>Europe/Moscow</time_zone>
    <send_message_id>w4Wq877djSG1_2_a1_6t_2p_U_2_g.2UCSmxz7zFnuCfCMK_5KmKH9</send_message_id>
</xml>

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

JSON
XML

{
    "error": 0,
    "error_text": "Successful operation"
}

<xml>
    <error>0</error>
    <error_text>Successful operation</error_text>
</xml>

Возвращаемые параметры

Параметр	Тип	Описание
error	int	Код ошибки
error_text	string	Текст ошибки

Описание​

URL-адрес​

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

Основные параметры​

Параметры матчинга​

Дополнительные параметры​

HTTP-параметры​

Параметры геолокации​

UTM-параметры​

Параметры сети​

Параметры рассылки​

Параметры программы лояльности​

Параметры маркета​

Примеры запроса​

Пример запроса для регистрации одной цели и её значения​

Пример запроса для регистрации нескольких целей и их значений​

Пример запроса для передачи дополнительной информации о событии​

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

Возвращаемые параметры​