Оформление
Передача конверсий (runtime)
Используйте метод, когда событие подтверждается на сервере, в CRM или мобильном приложении. Для события в браузере подходит вызов JavaScript. В обоих случаях используется идентификатор вызываемой вручную цели из кабинета.
Два способа сообщить об одной цели
| Где произошло событие | Как передать |
|---|---|
| На сайте с установленным кодом | ninja('reachGoal', goalId, params); текущий клиент и визит добавляются автоматически |
| В CRM, приложении или на сервере | Запрос ниже; передайте время события и доступные сведения о клиенте и источнике |
Описание метода
http
POST https://api.sales-ninja.me/public/{source}/v1.0/goals/reach
X-SN-TOKEN: <project token>
Content-Type: application/json{source} — mobile или backend. Другие значения отклоняются. Токен храните на сервере; получение токена и ошибки.
Тело запроса
Пример с идентификатором события для повторной отправки:
json
{
"goalId": "299837db-9b51-45a4-996b-844d3fd05bbd",
"conversionId": "d49f6076-717a-4123-8fba-68ce436abf9e",
"customerId": "user-42-from-your-system",
"sessionId": "0f6b4e0f-2d1a-4a02-9a3f-6a1f1d5f77c2",
"createdOn": "2026-04-15T12:23:25Z",
"sourceUpdatedOnUtc": "2026-04-15T12:23:25Z",
"yandexClickId": "example-click-id",
"utmSource": "example-source",
"utmCampaign": "example-campaign",
"pageUrl": "https://example.com/checkout",
"landingUrl": "https://example.com/catalog",
"params": {"revenue": "12350", "netProfit": "900"}
}Значения вымышлены. Передавайте только реальные идентификаторы и адреса своего события.
Поля
| Поле | Что передавать |
|---|---|
goalId | Обязательно: GUID цели в Sales Ninja, из адреса её редактора |
conversionId | Необязательный GUID одного достижения цели. Сохраните его до первой отправки и используйте при повторе того же события |
createdOn | Фактическое время события в UTC, ISO 8601. Передавайте явно при импорте и повторной отправке |
sourceUpdatedOnUtc | Необязательное время версии записи в источнике, UTC. При повторе той же версии не меняйте его |
customerId | Необязательный строковый идентификатор клиента. На сайте его можно получить через ninja('getCustomerIdAsync') |
sessionId | Необязательный GUID исходного визита, полученный через ninja('getSessionIdAsync') |
yandexClientId | Идентификатор клиента Яндекс.Метрики, сохранённый с заявкой |
yandexClickId | yclid исходного рекламного перехода |
utmSource, utmMedium, utmCampaign, utmContent, utmTerm | Сохранённые рекламные метки, отдельными полями запроса |
pageUrl, landingUrl | Адрес страницы события и исходной страницы входа |
ip | Необязательный IP клиента; для mobile при отсутствии используется IP соединения |
params | Необязательный словарь строк; revenue и netProfit — денежные суммы |
Если conversionId и createdOn не переданы, используется текущее серверное время. При передаче conversionId всегда указывайте фактический createdOn: не рассчитывайте на подстановку времени каждого запроса.
Связь с визитом и рекламой
Сохраните customerId и sessionId рядом с заявкой, пока посетитель находится на сайте, и верните их при подтверждении конверсии. Если sessionId отсутствует, передавайте доступные идентификаторы Метрики, клика, UTM и адреса. Система пытается сопоставить событие с визитом один раз при обработке; успех зависит от сохранённых данных, а не только от наличия полей в запросе. Несопоставленное событие также сохраняется и может остаться без рекламной привязки; автоматического последующего пересопоставления для этого пути нет. Для сравнения, цель из фида создаёт конверсию после сопоставления. Подробнее — ограничения сопоставления.
Выручка и прибыль
В params суммы передаются строками, например "12350". Используйте десятичную точку и не добавляйте символ валюты. Ключи revenue и netProfit распознаются без учёта регистра. Правила замены отсутствующих или нулевых сумм описаны в настройках выручки и прибыли.
Другие ключи params не становятся денежными суммами. customUserScopeParams и customPageScopeParams не являются полями этого метода.
Ответ
200 OK с пустым телом означает, что запрос принят для асинхронной обработки. Это не подтверждение появления конверсии или её привязки к рекламе. Проверьте событие в конверсиях выбранной цели, его время, суммы и источник.
При ошибке используйте справочник runtime-ошибок.
Примеры кода
Сохраните пример тела в conversion.json. Отправка через curl с сервера:
bash
curl --fail-with-body -X POST "https://api.sales-ninja.me/public/backend/v1.0/goals/reach" \
-H "X-SN-TOKEN: $SN_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @conversion.jsonСохраните тело запроса вместе с событием до отправки. Пример вызова с сохранённым телом:
js
async function sendConversion(conversion) {
const response = await fetch(
'https://api.sales-ninja.me/public/backend/v1.0/goals/reach',
{
method: 'POST',
headers: {
'X-SN-TOKEN': process.env.SN_TOKEN,
'Content-Type': 'application/json',
},
body: JSON.stringify(conversion),
},
)
if (!response.ok) {
throw new Error(`Conversion request failed: ${response.status}`)
}
}Python использует то же сохранённое тело:
python
import json
import os
import requests
with open("conversion.json", encoding="utf-8") as file:
conversion = json.load(file)
response = requests.post(
"https://api.sales-ninja.me/public/backend/v1.0/goals/reach",
headers={"X-SN-TOKEN": os.environ["SN_TOKEN"]},
json=conversion,
timeout=15,
)
response.raise_for_status()Идемпотентность и дубли
Один conversionId относится к одному достижению одной цели. Для нового достижения создавайте новый GUID; для повторной отправки используйте сохранённые conversionId, goalId и createdOn. Не создавайте новый идентификатор или текущее время при каждом повторе.
Без conversionId каждый запрос получает новый идентификатор. Одинаковые customerId и goalId не являются ключом повторной отправки: один клиент может достигать цели несколько раз. Передача sourceUpdatedOnUtc сама по себе не гарантирует исправления уже сохранённой конверсии: проверяйте результат, не считая повтор запроса обновлением данных.