Server API (REST)

Для серверных действий — оплат, регистраций, апдейтов профиля — которые нельзя доверять браузеру. Вызывается с вашего бэкенда по секретному ключу.

Базовый URL

https://livecontext.ru/v1

Авторизация

Все запросы требуют секретный ключ sk_… в заголовке Authorization. Ключ выдаётся в настройках организации и не должен попадать в браузер.

Authorization: Bearer sk_ВАШ_СЕКРЕТНЫЙ_КЛЮЧ

Неверный или отозванный ключ → 401 Unauthorized. Лимит — 1200 запросов в минуту на организацию (превышение → 429).

POST /v1/events

Отправить серверное событие. Обязательно указать одно из полей идентификации контакта: contactId, userId или email. Ответ — 202 Accepted (событие обрабатывается асинхронно).

POST https://livecontext.ru/v1/events
Authorization: Bearer sk_ВАШ_КЛЮЧ
Content-Type: application/json

{
  "userId": "user-42",
  "name": "purchase",
  "properties": { "amount": 4990, "currency": "RUB" }
}

Поле	Тип	Описание
`contactId`	uuid	ID контакта в LiveContext. Одно из трёх обязательно.
`userId`	string	Ваш внешний ID пользователя (тот же, что в `identify`).
`email`	string	Email контакта.
`name`	string	Обязательно. Имя события, до 100 символов.
`properties`	object	Произвольные свойства события.
`messageId`	uuid	Необязательно. Ключ идемпотентности для повторов.
`timestamp`	ISO-8601	Необязательно. Время события (по умолчанию — время приёма).

POST /v1/contacts

Создать или обновить контакт (upsert по userId или email, без дублей). Одно из полей userId / email обязательно. Ответ — 200 с карточкой контакта.

POST https://livecontext.ru/v1/contacts
Authorization: Bearer sk_ВАШ_КЛЮЧ
Content-Type: application/json

{
  "userId": "user-42",
  "email": "anna@shop.ru",
  "name": "Анна",
  "phone": "+7 900 000-00-00",
  "attributes": { "plan": "pro", "is_vip": true }
}

Поле	Тип	Описание
`userId`	string	Внешний ID. Одно из userId/email обязательно.
`email`	string	Email контакта.
`name`	string	Имя контакта.
`phone`	string	Телефон.
`attributes`	object	Кастомные атрибуты (string / number / boolean).

GET /v1/contacts

Найти контакт по внешнему ID или email. Ответ — карточка контакта или 404.

GET https://livecontext.ru/v1/contacts?userId=user-42
GET https://livecontext.ru/v1/contacts?email=anna@shop.ru
Authorization: Bearer sk_ВАШ_КЛЮЧ

GET /v1/contacts/:id

Получить контакт по его ID в LiveContext.

GET https://livecontext.ru/v1/contacts/CONTACT_ID
Authorization: Bearer sk_ВАШ_КЛЮЧ

Коды ответов

Код	Значение
`200`	Успех (contacts).
`202`	Событие принято в обработку (events).
`400`	Не передан идентификатор контакта или невалидное тело.
`401`	Нет ключа, ключ неверный или отозван.
`404`	Контакт не найден.
`429`	Превышен лимит запросов.

Фронтенд-события

Действия в браузере (просмотры, клики, корзина) отправляйте не через Server API, а сниппетом или npm-пакетом.