Важно!
Для успешной отправки событий каждое событие должно быть настроено в Личном кабинете Unisender.
Метод позволяет передавать в Unisender информацию о действиях пользователей на сайте или в приложении. О покупках, добавлении товаров в корзину, регистрациях и любых других событиях. Данные привязываются к контакту по email и становятся доступны для сегментации и просмотра в карточке контакта.
В одном запросе можно передать до 25 событий (батч). Если часть событий в батче невалидна, валидные события все равно будут записаны, запрос не отменяется целиком.
1.1. Отслеживание серверных событий
1.1.1. Метод: POST
1.1.2. URL: https://event.unisender.com/v1/events/
Аутентификация
Передавайте ключ доступа к API через заголовок Authorization. Ключ доступен в настройках аккаунта и не имеет срока действия. В целях безопасности не публикуйте ключ в открытом доступе.
Authorization: Bearer {ваш_api_ключ}
Запрос без корректного ключа вернет ошибку 401.
1.1.3. Заголовки запроса
| Заголовок | Значение | Обязательное поле |
| Content-Type | application/json | да |
| Authorization | Bearer {Ваш_API_ключ} | да |
1.1.4. Тело запроса
Тело запроса передается в формате JSON и имеет следующую структуру:
| {
"events": [ ] } |
EventObject
Каждый элемент массива events — это объект со следующими полями:
| Поле | Тип | Обязательное поле | Описание |
| events | array | да | Массив объектов событий. От 1 до 25 элементов включительно. |
| name | string | да | Название события. Должно совпадать с именем события, созданного в Менеджере событий. Длина: 1–40 символов. |
| string | да | Email пользователя, к которому будет привязано событие. Допустимы только ASCII-символы в локальной части (до @). Поддерживаются домены в формате Punycode. Интернационализированные адреса (RFC 6530–6532) не поддерживаются. | |
| created | string | нет | Дата и время события в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС. Если не указано, используется время получения запроса сервером. |
| (custom fields) | any | нет | Любые дополнительные поля с произвольными именами и значениями. Поддерживаются вложенные объекты и массивы. Ограничения. |
1.1.5. Пример запроса
Отправка одного события с дополнительными полями:
| curl --request POST \
--url https://event.unisender.com/events/ \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "events": [ { "name": "abandoned_cart", "email": "user@example.com", "created": "2026-05-13 10:00:00", "cart_value": 4990, "currency": "RUB", "item_count": 2 } ] } |
Пример с несколькими событиями в одном батче:
| curl --request POST \
--url https://event.unisender.com/events/\ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "events": [ { "name": "purchase", "email": "alice@example.com", "created": "2026-05-13 09:00:00", "items": [ { "code": 11122, "count": 1, "price": 100 }, { "code": 22233, "count": 2, "price": 250 } ], "total": { "currency": "RUB", "amount": 600 } } |
1.1.6. Коды ответов
Валидация входящего запроса выполняется в два этапа:
- Этап 1 — проверка аутентификации, корректности заголовков и структуры JSON. Ошибка на этом этапе отменяет весь батч.
- Этап 2 — проверка каждого EventObject внутри батча. Невалидное событие отклоняется, остальные события в батче записываются.
| Код | Значение |
| 200 OK | Все события в батче приняты и записаны. |
| 400 Bad Request | Один или несколько EventObject не прошли валидацию (этап 2). Валидные события из того же батча записаны. Подробности — в теле ответа. |
| 401 Unauthorized | API-ключ отсутствует, неверен или отозван. Проверьте заголовок Authorization. |
| 500 Internal Server Error | Ошибка на стороне сервиса. Выполните повторный запрос с экспоненциальной задержкой. Если ошибка повторяется — обратитесь в поддержку с Error ID из тела ответа. |
200 OK — все события приняты
| {
"success": true } |
400 Bad Request — часть событий отклонена
Ответ 400 означает частичный сбой: некоторые события в батче невалидны, но остальные записаны. Тело ответа содержит подробности:
| { "code": "invalid_params",
"error": "Error ID: 019E1FF8-... { \"invalidEvents\": [ ... ], \"inactiveEvents\": [ ... ] }" } |
| Поле в error | Описание |
| invalidEvents | Массив EventObject, не прошедших валидацию схемы: не указан или невалиден email, слишком длинное поле name и т.п. |
| inactiveEvents | Массив EventObject с именами событий, которые не найдены в Менеджере событий, выключены или удалены. |
401 Unauthorized
| {
"code": "unauthorized", "error": "Error ID: 911B6D1B-... Unauthorized." } |
500 Internal Server Error
| {
"code": "server_error", "error": "Error ID: 019BE0C6-... Sth went wrong." } |
Ограничения
1.1.7. Ограничения
| Параметр | Лимит |
| Событий в одном запросе (батч) | 25 |
| Полей в одном EventObject | 25 (включая name и email) |
| Длина поля name | 1– 40 символов |
| Максимальный размер тела запроса | 130 KB |
Запросы, превышающие лимиты, отклоняются полностью — ни одно событие из такого батча не будет записано.
1.1.8. Рекомендации
Батчевая отправка предпочтительна. Группируйте события в батчи до 25 штук — это снижает накладные расходы на сетевые запросы. Не отправляйте по одному событию на запрос, если этого можно избежать.
Поле created необязательно, но важно. Если не передать created, сервер проставит временную метку по моменту получения запроса. Для событий в реальном времени это нормально. Для исторических данных или при буферизации всегда передавайте фактическое время события.
Ответ 400 — не всегда полный сбой. Код 400 означает, что хотя бы одно событие в батче невалидно. Валидные события при этом записаны. Разберите массивы invalidEvents и inactiveEvents из строки error, чтобы понять, какие именно события не были приняты.
1.1.9. Пример быстрого запуска
Минимальный рабочий пример — отправить одно событие и корректно обработать ответ:
| curl --request POST \
--url https://event.unisender.com/events/ \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "events": [ { "name": "signup", "email": "newuser@example.com", "created": "2026-05-13 10:00:00" } ] } |
Успешный ответ:
| {
"success": true } |
Ответ при частичной ошибке (например, событие выключено в Менеджере событий):
| {
"code": "invalid_params", "error_id": "019E1FF8-1D95-79AE-B786-FC583BA6E0AD", "details": { "invalidEvents": [], "inactiveEvents": [ { "name": "signup", "email": "newuser@example.com" } ] } } |
