Загрузка событий Ecomm

С помощью S2S API вы можете передать Ecomm события, совершённые вне сайта. Например, изменение статуса заказа в системе учёта, в административной панели сайта или оформленный через CRM-систему платёж.

Также через S2S API можно передавать данные по заказам в приложениях iOS и Android.

Подробнее о передаче событий на сайте см. раздел Ecommerce

Методы

Для загрузки событий Ecommerce на сервер MyTracker используйте следующие методы:

order для передачи одного события;
orderBatch для передачи сразу нескольких событий.

Все загруженные данные будут включены в общую статистику и появятся в интерфейсе MyTracker в течение 4 часов.

order

Формат запроса: https://tracker-s2s.my.com/v1/order/?idApp=XXX

Обязательные параметры: параметры события, параметры товара, а также идентификатор пользователя и/или устройства, к которым будет привязано событие:

Для сайтов: customUserId и/или lvid
Для мобильных приложений: customUserId и/или instanceId, gaid, appSetId, androidId, idfa, iosVendorId

orderBatch

Формат запроса: https://tracker-s2s.my.com/v1/orderBatch/?idApp=XXX

Обязательные параметры:

Название параметра	Описание	Тип	Пример
	Один параметр без названия. Это массив, через который передают параметры из метода `order`. Если хотя бы в одном наборе параметров нарушены правила валидации, сервер вернет ошибку	Массив. Максимальный размер 20	[ {"order_id": "000919", "status":"ADD", "items":[{"item_id": "00912", "item_name":"Apple", "quantity": "6"}]}, {"order_id": "000930", "status":"PAY", "items":[{"item_id": "00912", "item_name":"Apple", "quantity": "6"}]} ]

Параметры

Все параметры передаются в теле POST запроса в формате json.

Ограничение на максимальный размер загружаемых данных — 10Кб.

Параметры события

Название параметра	Описание	Тип	Пример
order_id*	Уникальный номер заказа	Строка	"order_id":"000919"
status	Действие по заказу: ADD (добавление товара) PAY (оплата товара, значение по умолчанию) CANCEL (удаление неоплаченного товара) REFUND (возврат оплаченного товара) ADD и PAY соответствуют событию mt_order в dataLayer. CANCEL и REFUND соответствуют событию mt_refund в dataLayer.	Строка	"status":"PAY"
currency_code	Трёхбуквенный код валюты по ISO 4217. Если значение не передано, то подставляется валюта проекта	Строка	"currency_code":"USD"
action_id	Уникальный номер действия (события) в рамках заказа	Строка	"action_id":"119029"
action_ts	Время события на сервере клиента (timestamp)	Строка	"action_ts":"1577191920"
coupon	Название или код купона на заказ	Строка	"coupon":"two-for-one"
items*	Массив с описанием товаров	Массив	[ {"item_id": "00912", "item_name":"Apple", "quantity": "6"}, {"item_id": "00920", "item_name":"Apple", "quantity": "4"} ]

* — обязательные параметры

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

Параметр	Описание	Тип	Пример
item_id*	Уникальный идентификатор товара	Строка	"item_id":"00912"
item_name*	Название товара. Может быть не уникальным и меняться.	Строка	"item_name":"Apple"
affiliation	Поставщик или магазин, к которому относится товар	Строка	"affiliation":"Gardens"
price	Цена товара, без учёта скидок	Число	"price":"11.90"
discount	Сумма скидки на товар	Число	"discount":"2"
coupon	Название или код купона на товар	Строка	"coupon":"two-for-one"
tax	НДС и другие налоговые издержки. Значение от 1 до 100, в процентах.	Число	"tax":"20"
index	Позиция товара в списке	Целое число	"index":"1"
item_brand	Бренд товара	Строка	"item_brand":"Honey Crisp"
item_variant	Разновидность товара	Строка	"item_variant":"Green"
item_list_id	Идентификатор списка, в котором товар представлен пользователю	Строка	"item_list_id":"5"
item_list_name	Название списка, в котором товар представлен пользователю	Строка	"item_list_name":"Fruits"
item_category1	Одна из категорий, к которой относится товар	Строка	"item_category1":"Foodstuffs"
item_category2	Одна из категорий, к которой относится товар	Строка	"item_category2":"Fruits"
item_category3	Одна из категорий, к которой относится товар	Строка	"item_category3":"Apples"
item_category4	Одна из категорий, к которой относится товар	Строка	"item_category4":"Sweet"
location_id	Идентификатор или название местоположение товара, магазина, пункта выдачи и др.	Строка	"location_id":"Oregon"
quantity	Количество единиц товара	Целое число	"quantity":"3"

* — обязательные параметры

Параметры S2S API

Название параметра	Описание	Тип	Пример
Общие
eventTimestamp	Время события	Число, минимальное 946674000, максимальное значение 4294967295. По умолчанию берётся timestamp получения события	"eventTimestamp":"1577191920"
customUserId	Идентификатор пользователя	Строка, максимальный размер 1024	"customUserId":"1234"
ipv4	ipv4-адрес	Строка, максимальный размер 15	"ipv4":"125.125.125.125"
ipv6	ipv6-адрес	Строка, максимальный размер 45	"ipv6":"2001:0db8:85a3:0000:0000:8a2e:0370:7334"
idGender	Пол	Число, возможные варианты: 0 — неизвестно 1 — мужчина 2 — женщина	"idGender":"1"
age	Возраст	Число, максимальное значение 128	"age":"38"
connectionType	Тип соединения	Число, возможные варианты: 0 — неизвестно 1 — мобильная 2 — wi-fi По умолчанию 0	"connectionType":"1"
bluetoothEnabled	Bluetooth	Число, возможные варианты: 0 — неизвестно 1 — включён 2 — выключен По умолчанию 0	"bluetoothEnabled":"2"
Для мобильных приложений
instanceId	S2S идентификатор устройства	Строка, кол-во символов 36	"instanceId":"00000000-0000-0000-0000-000000000000"
adTrackingEnabled	Разрешение отслеживания	Число, возможные варианты: 1 — включено 0 — выключено По умолчанию 1	"adTrackingEnabled":"0"
iOS
idfa	Рекламный идентификатор iOS	Строка, кол-во символов 36	"idfa":"00000000-0000-0000-0000-000000000000"
iosVendorId	Идентификатор производителя IOS	Строка, кол-во символов 36	"iosVendorId":"00000000-0000-0000-0000-000000000000"
Android
gaid	Рекламный идентификатор Android (advertisingId)	Строка, кол-во символов 36	"gaid":"00000000-0000-0000-0000-000000000000"
appSetId	Идентификатор Android, уникальный в рамках аккаунта разработчика Google Play	Строка, кол-во символов 36	"appSetId":"00000000-0000-0000-0000-000000000000"
androidId	Идентификатор Android	Строка, кол-во символов 16	"androidId":"000000000000000"
Для сайтов
lvid	S2S идентификатор устройства	Строка, кол-во символов 32	"lvid":"00000000000000000000000000000000"
adBlocker	Блокировщик рекламы	Число, возможные варианты: 1 — включён 0 — выключен По умолчанию 0	"adBlocker":"0"
userAgent	User-Agent	Строка, максимальный размер 2048	"userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.87 Safari/537.36"

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

Рассмотрим примеры передачи различных событий:

Событие	Параметры
Оформление заказа с оплатой	"status": "PAY" Отправлять событие нужно в тот момент, когда пользователь полностью оплатил заказ на сайте и завершил оформление.
Оформление заказа без оплаты	"status": "ADD" Отправлять событие нужно в тот момент, когда пользователь завершил оформление заказа с отложенной оплатой, например, в пункте выдачи заказов или курьеру.
Полная или частичная оплата заказа	Оплата заказа подразумевает, что перед этим уже было отправлено событие в статусе ADD. Возможная цепочка действий: ADD→PAY. "status": "PAY" "order_id": "номер оформленного ранее заказа" "items": "описание оплаченных товаров" Отправлять событие нужно в момент оплаты.
Дополнение заказа	Дополнение заказа подразумевает, что перед этим уже было отправлено событие с тем же `order_id`. Возможные цепочки действий: ADD→ADD, ADD→PAY, PAY→ADD, PAY→PAY. "status": "PAY" если товары оплачены "status": "ADD" если товары не оплачены "order_id": "номер оформленного ранее заказа" "items": "описание добавленных товаров" Отправлять событие нужно в момент добавления товаров.
Полная или частичная отмена неоплаченного заказа	Отмена заказа подразумевает, что перед этим уже было отправлено событие с тем же `order_id`. Возможные цепочки действий: ADD→CANCEL, PAY→CANCEL. "status": "CANCEL" "order_id": "номер оформленного ранее заказа" "items": "описание отменённых товаров" Отправлять событие нужно в тот момент, когда пользователь отменил заказ или часть товаров, или, например, когда истёк срок резерва заказа.
Полная или частичная отмена оплаченного заказа	Отмена оплаченного заказа подразумевает, что перед этим уже было отправлено событие с тем же `order_id`. Возможные цепочки действий: PAY→REFUND, CANCEL→REFUND. "status": "REFUND" "order_id": "номер оплаченного ранее заказа" "items": "описание возвращённых товаров" Отправлять событие нужно в тот момент, когда пользователь оформил возврат.

Оформление заказа без оплаты

curl --location 'https://tracker-s2s.my.com/v1/order/?idApp=001' \
--header 'Content-Type: application/json' \
--header 'Authorization: aaaaaAAAaaa01aaaaaaa1aaAAA11a' \
--data '{
    "lvid": "00000000000000000000000000000000",
    "order": {
        "order_id": "000919",
        "currency_code": "USD",
        "status": "ADD",
        "action_ts": "1709317326",
        "coupon": "two-for-one",
        "items": [
            {
                "item_id": "00912",
                "item_name": "Apple",
                "affilation": "Gardens",
                "item_list_id": "5",
                "item_list_name": "Fruits",
                "price": "11.90",
                "discount": "2",
                "coupon": " two-for-one",
                "tax": "20",
                "index": "1",
                "item_brand": "Honey Crisp",
                "item_variant": "Green",
                "item_category1": "Foodstuffs",
                "item_category2": "Fruits",
                "item_category3": "Apples",
                "item_category4": "Sweet",
                "location_id": "Oregon",
                "quantity": "5"
            }
        ]
    }
}'

Частичная оплата заказа

curl --location 'https://tracker-s2s.my.com/v1/order/?idApp=001' \
--header 'Content-Type: application/json' \
--header 'Authorization: aaaaaAAAaaa01aaaaaaa1aaAAA11a' \
--data '{
    "lvid": "00000000000000000000000000000000",
    "order": {
        "order_id": "000919",
        "currency_code": "USD",
        "status": "PAY",
        "action_ts": "1709478868",
        "coupon": "two-for-one",
        "items": [
            {
                "item_id": "00912",
                "item_name": "Apple",
                "affilation": "Gardens",
                "item_list_id": "5",
                "item_list_name": "Fruits",
                "price": "11.90",
                "discount": "2",
                "coupon": " two-for-one",
                "tax": "20",
                "index": "1",
                "item_brand": "Honey Crisp",
                "item_variant": "Green",
                "item_category1": "Foodstuffs",
                "item_category2": "Fruits",
                "item_category3": "Apples",
                "item_category4": "Sweet",
                "location_id": "Oregon",
                "quantity": "4"
            }
        ]
    }
}'

Частичная отмена неоплаченного заказа

curl --location 'https://tracker-s2s.my.com/v1/order/?idApp=001' \
--header 'Content-Type: application/json' \
--header 'Authorization: aaaaaAAAaaa01aaaaaaa1aaAAA11a' \
--data '{
    "lvid": "00000000000000000000000000000000",
    "order": {
        "order_id": "000919",
        "currency_code": "USD",
        "status": "CANCEL",
        "action_ts": "1709479828",
        "coupon": "two-for-one",
        "items": [
            {
                "item_id": "00912",
                "item_name": "Apple",
                "affilation": "Gardens",
                "item_list_id": "5",
                "item_list_name": "Fruits",
                "price": "11.90",
                "discount": "2",
                "coupon": " two-for-one",
                "tax": "20",
                "index": "1",
                "item_brand": "Honey Crisp",
                "item_variant": "Green",
                "item_category1": "Foodstuffs",
                "item_category2": "Fruits",
                "item_category3": "Apples",
                "item_category4": "Sweet",
                "location_id": "Oregon",
                "quantity": "1"
            }
        ]
    }
}'

Частичный возврат оплаченного заказа

curl --location 'https://tracker-s2s.my.com/v1/order/?idApp=001' \
--header 'Content-Type: application/json' \
--header 'Authorization: aaaaaAAAaaa01aaaaaaa1aaAAA11a' \
--data '{
    "lvid": "00000000000000000000000000000000",
    "order": {
        "order_id": "000919",
        "currency_code": "USD",
        "status": "REFUND",
        "action_ts": "1709652628",
        "coupon": "two-for-one",
        "items": [
            {
                "item_id": "00912",
                "item_name": "Apple",
                "affilation": "Gardens",
                "item_list_id": "5",
                "item_list_name": "Fruits",
                "price": "11.90",
                "discount": "2",
                "coupon": " two-for-one",
                "tax": "20",
                "index": "1",
                "item_brand": "Honey Crisp",
                "item_variant": "Green",
                "item_category1": "Foodstuffs",
                "item_category2": "Fruits",
                "item_category3": "Apples",
                "item_category4": "Sweet",
                "location_id": "Oregon",
                "quantity": "1"
            }
        ]
    }
}'

Коды ответов

Код	Ответ	Описание
200	{"message": "ОK"}	Запрос был успешно обработан
400	{"error": "Bad Request"}	Ошибка запроса, параметры не прошли валидацию
403	{"error": "Forbidden"}	Токен не прошёл валидацию, либо не подходит для приложения
400	{"error": "Empty post data"}	Пустое тело запроса
400	{"error": "Bad json"}	Передан битый json в теле запроса
400	{"error": "Bad api version"}	Неподдерживаемая версия API
404	{"error": "Method not found"}	Метод API не найден
500	{"error": "Internal Server Error"}	Внутренняя ошибка API. Нужно повторить запрос позже

Была ли эта статья полезна?