#Офлайн-конверсии

Статус: Планируется. Метод POST /analytics/conversions проектируется. Страница фиксирует согласованные принципы; состав полей — предварительный и уточнится в OpenAPI 3.1.

Назначение: передать в Формула ИИ оплату или выигранную сделку из вашей CRM и учётной системы, чтобы платформа связала деньги с лидом, сессией и каналом привлечения и посчитала окупаемость каналов.

#Содержание

1. Зачем это нужно
2. Когда использовать
3. Доступ
4. Запрос
5. Привязка к лиду, сессии или внешнему идентификатору
6. Ответ
7. Ошибки
8. Примеры
9. Как конверсии попадают в отчёты
10. Заметки
11. Открытые вопросы

#Зачем это нужно

Счётчики сайта видят визиты и заявки, но не деньги: оплата происходит в CRM, на кассе или на расчётном счёте. Без неё стратег Формула ИИ знает, сколько лидов принёс канал, но не знает, сколько он заработал. Офлайн-конверсия добавляет недостающее звено «лид → оплата» и позволяет рассчитать окупаемость канала.

В «Обзоре» шаги воронки deals_created, deals_won и revenue строятся по данным CRM платформы. Если ваши сделки живут во внешней CRM, этот метод и Лиды и CRM — способ дать платформе те же сведения. Правила, по которым конверсии и сделки платформы объединяются без двойного счёта, — в разделе Как конверсии попадают в отчёты.

#Когда использовать

#Доступ

Адреса ячеек: RU https://formula-cream.pro, EN https://wfacademy.org, ID https://wfacademy.id. Валюта суммы соответствует рынку ячейки: RUB для RU, GBP для EN, IDR для ID (Ячейки и данные).

#Запрос

Заголовки: Authorization, Content-Type: application/json, Idempotency-Key (Соглашения).

Тело (предварительно)

Нужен хотя бы один из lead_id, external_id, session_id. Если указано несколько, приоритет определяется в порядке lead_id, external_id, session_id (предварительно).

{
  "conversion_id": "pay_48213_1",
  "type": "payment",
  "value": { "amount": "4990.00", "currency": "RUB" },
  "occurred_at": "2026-10-11T08:15:30Z",
  "external_id": "crm-48213",
  "properties": { "product": "emulsion-mastery" }
}

#Привязка к лиду, сессии или внешнему идентификатору

Если лид или сессия не найдены, конверсия отклоняется с кодом not_found; платформа не создаёт «висячих» конверсий.

#Ответ

Успех — 201 Created для новой конверсии и 200 OK при повторе с тем же conversion_id. Метод не асинхронный: объект operation не возвращается, а пересчёт отчётов идёт после ответа.

{
  "conversion_id": "pay_48213_1",
  "status": "attributed",
  "lead_id": "lead_EXAMPLE_01",
  "attribution": { "channel": "search", "basis": "form" },
  "created_at": "2026-10-11T08:16:02Z"
}

Имена полей ответа предварительные.

#Ошибки

Формат — application/problem+json, коды — в каталоге ошибок.

#Примеры

#curl

curl -X POST 'https://formula-cream.pro/api/public/v1/analytics/conversions' \
  -H 'Authorization: Bearer sap_ru_live_EXAMPLE0KEYI_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pay_48213_1' \
  -d '{
    "conversion_id": "pay_48213_1",
    "type": "payment",
    "value": { "amount": "4990.00", "currency": "RUB" },
    "occurred_at": "2026-10-11T08:15:30Z",
    "external_id": "crm-48213"
  }'

#Python

import os, requests

response = requests.post(
    "https://wfacademy.org/api/public/v1/analytics/conversions",
    headers={
        "Authorization": f"Bearer {os.environ['API_KEY']}",
        "Idempotency-Key": "pay_48213_1",
    },
    json={
        "conversion_id": "pay_48213_1",
        "type": "payment",
        "value": {"amount": "49.00", "currency": "GBP"},
        "occurred_at": "2026-10-11T08:15:30Z",
        "external_id": "crm-48213",
    },
    timeout=5,
)
response.raise_for_status()

#Как конверсии попадают в отчёты

Метрики deals_won и revenue в аналитике (Чтение аналитики) берутся из CRM платформы или из офлайн-конверсий, без двойного счёта:

• конверсия с lead_id, у которого в CRM платформы уже есть выигранная сделка, заменяет её сумму; если конверсий по лиду несколько, действует последняя по occurred_at;
• конверсия без выигранной сделки у лида добавляется как новая выигранная сделка на сумму value;
• в режимах CRM external и both (режимы) тот же принцип: платформа не складывает сделку и конверсию по одному лиду.

Конверсия попадает и в разрез по каналам. Стратег использует её, чтобы считать окупаемость канала и приоритизировать темы и рекламу. Данные появляются в отчётах не мгновенно: пересчёт идёт после приёма.

#Возвраты

Возврат передаётся как конверсия с отрицательной суммой в value.amount (например, "-4990.00") и собственным conversion_id. Она уменьшает revenue за период, в который попал occurred_at возврата.

{
  "conversion_id": "refund_48213_1",
  "type": "payment",
  "value": { "amount": "-4990.00", "currency": "RUB" },
  "occurred_at": "2026-10-20T10:00:00Z",
  "external_id": "crm-48213"
}

#Заметки

• Деньги — только строкой и только в валюте ячейки; пересчёта валют нет.
• Повтор с тем же conversion_id безопасен.
• Возвраты передаются отрицательной суммой (Возвраты).

#Открытые вопросы

1. Техническое. Состав и имена полей запроса и ответа предварительные: проект задаёт лишь замысел «оплата, сделка с привязкой к лиду/сессии».
2. К владельцу. Мультивалютность: допустимо ли присылать сумму в валюте, отличной от валюты ячейки.
3. Техническое. Предельное «окно» давности occurred_at и порядок пересчёта окупаемости при поздних конверсиях; частичные оплаты и корректировки суммы (кроме возврата).
4. К владельцу. Область analytics:write общая с событиями; раздельного права на конверсии (денежные данные) нет.