Получение лидов с вашего сайта

Инструкция по интеграции формы вашего сайта с ReactiveCRM: фиксация отправок формы как лидов, отправка событий маркетинговой атрибуции и проверка результата.

1. Обзор

Рекомендуемый сценарий состоит из двух запросов:

Сайт отправляет данные формы на собственный бэкенд.
Бэкенд сайта создаёт лид в CRM через POST /api/leads/create.
После успешного создания бэкенд отправляет маркетинговое событие lead_submitted через POST /api/dashboard/marketing/events, передавая полученный leadId.
CRM сохраняет UTM-метки, рекламные идентификаторы и referrer для маркетинговой атрибуции.

text

Website form
    |
    v
Site backend / server-side proxy
    |  POST /api/leads/create
    v
ReactiveCRM -> leadId
    |  POST /api/dashboard/marketing/events
    v
Marketing attribution and dashboard

Не отправляйте CRM JWT и секреты напрямую из браузера. Используйте бэкенд сайта или serverless-функцию, чтобы CRM-токен и служебные идентификаторы никогда не попадали к посетителю.

2. Аутентификация и базовый URL

Все запросы выполняются в контексте соответствующего тенанта и требуют CRM-авторизации:

http

Authorization: Bearer <CRM_ACCESS_TOKEN>
Content-Type: application/json

В примерах используется:

text

CRM_BASE_URL=https://crm.example.com

Замените его на URL вашего окружения.

3. Данные для сбора на сайте

Данные лида

Для создания лида API поддерживает:

Поле	Обязательно	Описание
`message`	нет	Сообщение или текст обращения из формы
`ownerId`	да	UUID пользователя CRM, ответственного за лид
`authorId`	да	UUID пользователя CRM, создавшего лид
`clientId`	нет	UUID существующего клиента
`contactId`	нет	UUID существующего контакта
`leadSourceId`	нет	UUID узла в дереве источников лидов
`statusId`	нет	UUID начального статуса
`quality`	нет	`HOT`, `WARM`, `COOL` or `COLD`

ownerId и authorId — это UUID пользователей CRM. Для публичной формы на сайте не позволяйте посетителю задавать эти значения самостоятельно: бэкенд должен брать их из конфигурации интеграции.

Данные маркетингового визита

До отправки формы сохраните следующее в cookies, session storage или на бэкенде:

utm_source → utmSource
utm_medium → utmMedium
utm_campaign → utmCampaign
utm_content → utmContent
utm_term → utmTerm
gclid — идентификатор Google Ads
fbclid — идентификатор Meta/Facebook
URL посадочной страницы → landingUrl
URL предыдущей страницы → referrer
Собственные идентификаторы посетителя и сессии → visitorId, sessionId

Сохраняйте значения при первом визите и не перезаписывайте их пустыми параметрами при навигации по сайту.

4. Создание лида

Эндпоинт

http

POST /api/leads/create

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

bash

curl -X POST "$CRM_BASE_URL/api/leads/create" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Website inquiry: consultation request",
    "ownerId": "11111111-1111-1111-1111-111111111111",
    "authorId": "11111111-1111-1111-1111-111111111111",
    "quality": "WARM"
  }'

Пример ответа `201 Created`

json

{
  "id": "22222222-2222-2222-2222-222222222222",
  "message": "Website inquiry: consultation request",
  "quality": "WARM",
  "dealId": null,
  "createdAt": "2026-09-05T20:00:00Z",
  "updatedAt": "2026-09-05T20:00:00Z",
  "version": 0,
  "author": {
    "id": "11111111-1111-1111-1111-111111111111",
    "firstName": "CRM",
    "lastName": "Bot"
  },
  "owner": {
    "id": "11111111-1111-1111-1111-111111111111",
    "firstName": "CRM",
    "lastName": "Bot"
  }
}

Сохраните id из ответа: это значение передаётся в поле leadId маркетингового события.

5. Отправка события «лид отправлен»

Эндпоинт

http

POST /api/dashboard/marketing/events

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

bash

curl -X POST "$CRM_BASE_URL/api/dashboard/marketing/events" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "lead_submitted",
    "occurredAt": "2026-09-05T20:00:00Z",
    "visitorId": "visitor-8b7f",
    "sessionId": "session-31ac",
    "leadId": "22222222-2222-2222-2222-222222222222",
    "externalId": "site-form-submit-20260905-000123",
    "source": "website",
    "channel": "paid",
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "summer-consulting",
    "utmContent": "banner-a",
    "utmTerm": "crm consultation",
    "gclid": "EAIaIQobChMI-example",
    "landingUrl": "https://www.example.com/consultation",
    "referrer": "https://www.google.com/",
    "metadata": {
      "formName": "consultation",
      "pageType": "landing"
    }
  }'

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

json

{
  "accepted": true,
  "duplicate": false,
  "eventId": "33333333-3333-3333-3333-333333333333"
}

Если тот же externalId уже обработан для этой пары source и тенанта, API возвращает успешный ответ с duplicate: true. Считайте это успехом, а не ошибкой, и не создавайте второй лид.

6. Пример серверного обработчика

Ниже приведён упрощённый пример на Node.js. Данные формы должны идти на бэкенд сайта, а не напрямую в CRM из браузера.

async function createWebsiteLead(form, attribution) {
  const headers = {
    Authorization: `Bearer ${process.env.CRM_ACCESS_TOKEN}`,
    'Content-Type': 'application/json',
  };

  const leadResponse = await fetch(
    `${process.env.CRM_BASE_URL}/api/leads/create`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        message: form.message || `Website inquiry: ${form.subject || 'no subject'}`,
        ownerId: process.env.CRM_LEAD_OWNER_ID,
        authorId: process.env.CRM_LEAD_AUTHOR_ID,
        quality: 'WARM',
      }),
    },
  );

  if (!leadResponse.ok) {
    throw new Error(`CRM lead creation failed: ${leadResponse.status}`);
  }

  const lead = await leadResponse.json();
  const externalId = `website-${form.requestId}`;

  const eventResponse = await fetch(
    `${process.env.CRM_BASE_URL}/api/dashboard/marketing/events`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        eventType: 'lead_submitted',
        occurredAt: new Date().toISOString(),
        visitorId: attribution.visitorId,
        sessionId: attribution.sessionId,
        leadId: lead.id,
        externalId,
        source: 'website',
        channel: attribution.channel || 'direct',
        utmSource: attribution.utmSource,
        utmMedium: attribution.utmMedium,
        utmCampaign: attribution.utmCampaign,
        utmContent: attribution.utmContent,
        utmTerm: attribution.utmTerm,
        gclid: attribution.gclid,
        fbclid: attribution.fbclid,
        landingUrl: attribution.landingUrl,
        referrer: attribution.referrer,
        metadata: { formName: form.formName || 'website' },
      }),
    },
  );

  if (!eventResponse.ok) {
    // Лид уже создан. Поставьте событие в очередь и повторите его
    // с тем же externalId, вместо создания второго лида.
    throw new Error(`CRM marketing event failed: ${eventResponse.status}`);
  }

  return { leadId: lead.id, marketingEvent: await eventResponse.json() };
}

7. Идемпотентность и повторы

Генерируйте стабильный externalId для каждой отправки формы. Например, используйте UUID, созданный до первого запроса, или уникальный requestId формы.
При сетевой ошибке повторите запрос маркетингового события с тем же externalId.
Не генерируйте новый externalId при повторе: это создаст дублирующее событие.
Если запрос на создание лида завершился с неопределённым результатом из-за тайм-аута, не создавайте новый лид вслепую. Сначала используйте собственный requestId и механизм дедупликации на бэкенде сайта либо найдите созданный лид в CRM.
Ошибка отправки события не должна заставлять пользователя повторно отправлять форму без проверки результата создания лида.

8. Персональные данные и metadata

Передавать персональные данные и содержимое формы в metadata запрещено:

email
phone
имя и фамилия
адрес
текст сообщения
cookies с идентификаторами, содержащими персональные данные

Персональные данные должны передаваться только в предназначенных для этого сущностях CRM — например, в предварительно созданных contactId/clientId. Оставляйте в metadata только технические атрибуты: название формы, тип страницы, вариант баннера и т. д.

9. Типичные ответы и ошибки

HTTP	Ситуация	Что делать
`201`	Лид создан	Сохраните `id` и отправьте `lead_submitted`
`200` + `duplicate: false`	Событие принято	Сохраните `eventId` в журнале интеграции
`200` + `duplicate: true`	Событие уже было принято	Считайте обработанным; не отправляйте повторно
`400`	Некорректные данные или персональные данные в `metadata`	Исправьте данные; повтор без изменений не поможет
`401`	Неверный или отсутствующий токен	Обновите CRM-токен на бэкенде
`403`	У токена нет прав на операцию	Проверьте роль и тенант
`5xx` / timeout	Временная ошибка CRM или сети	Повторите с тем же `externalId`; для лидов используйте очередь

10. Проверка результатов в CRM

После интеграции проверьте:

Лид отображается через GET /api/leads/{id} или в списке GET /api/leads/paged.
Владелец, автор и время создания лида корректны.
Ответ маркетингового события при первой отправке содержит duplicate равный false.
Повторная отправка той же заявки возвращает duplicate: true.
В маркетинговом дашборде данные появляются в нужном периоде, канале и кампании.

Получение созданного лида

bash

curl "$CRM_BASE_URL/api/leads/$LEAD_ID" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

Получение лидов для списка или сверки

bash

curl "$CRM_BASE_URL/api/leads/paged?page=0&size=20&createdAtFrom=2026-09-05T00:00:00Z&createdAtTo=2026-09-05T23:59:59Z&sort=createdAt,desc" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

Параметр page начинается с 0; значение size по умолчанию — 20. Чтобы получить лиды с сайта, дополнительно используйте фильтры message, createdAtFrom/createdAtTo, contactEmail или search, если нужные данные уже сохранены в CRM.

Получение лидов с вашего сайта

1. Обзор

2. Аутентификация и базовый URL

3. Данные для сбора на сайте

Данные лида

Данные маркетингового визита

4. Создание лида

Эндпоинт

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

Пример ответа 201 Created

5. Отправка события «лид отправлен»

Эндпоинт

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

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

6. Пример серверного обработчика

7. Идемпотентность и повторы

8. Персональные данные и metadata

9. Типичные ответы и ошибки

10. Проверка результатов в CRM

Получение созданного лида

Получение лидов для списка или сверки

Пример ответа `201 Created`