Веб-сайттан лидтер алу

Веб-сайт формасын ReactiveCRM-мен интеграциялау бойынша нұсқаулық: форма жіберулерді лидтер ретінде түсіру, маркетингтік атрибуция оқиғаларын жіберу және нәтижені тексеру.

1. Шолу

Ұсынылатын ағым екі сұраныстан тұрады:

Сайт форма деректерін өз бэкендіне жібереді.
Сайт бэкенді CRM-де POST /api/leads/create арқылы лид жасайды.
Сәтті жасалғаннан кейін бэкенд POST /api/dashboard/marketing/events арқылы lead_submitted маркетингтік оқиғасын жібереді, алынған leadId мәнін береді.
CRM маркетингтік атрибуция үшін UTM тегтерін, жарнама идентификаторларын және реферерді сақтайды.

мәтін

Веб-сайт формасы
    |
    v
Сайт бэкенді / сервер жағындағы прокси
    |  POST /api/leads/create
    v
ReactiveCRM -> leadId
    |  POST /api/dashboard/marketing/events
    v
Маркетингтік атрибуция және бақылау тақтасы

CRM JWT және құпияларды браузерден тікелей жібермеңіз. CRM токені мен қызмет идентификаторлары келушіге ешқашан ұшырамауы үшін сайт бэкендін немесе serverless функциясын пайдаланыңыз.

2. Аутентификация және негізгі URL

Барлық сұраныстар тиісті tenant контекстінде орындалады және CRM авторизациясын қажет етеді:

http

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

Мысалдарда мына мән пайдаланылады:

мәтін

CRM_BASE_URL=https://crm.example.com

Оны өз ортаңыздың URL-імен ауыстырыңыз.

3. Сайтта жинау үшін деректер

Лид деректері

Лид құру үшін API мыналарды қолдайды:

Өріс	Міндетті	Сипаттама
`message`	жоқ	Формадан алынған сұраныстың хабарламасы немесе мәтіні
`ownerId`	иә	Лидке жауапты CRM пайдаланушысының UUID-і
`authorId`	иә	Лидті құрған CRM пайдаланушысының UUID-і
`clientId`	жоқ	Бар клиенттің UUID-і
`contactId`	жоқ	Бар байланыстың UUID-і
`leadSourceId`	жоқ	Лид дереккөзі ағашындағы түйіннің UUID-і
`statusId`	жоқ	Бастапқы мәртебенің UUID-і
`quality`	жоқ	`HOT`, `WARM`, `COOL` немесе `COLD`

ownerId және authorId — CRM пайдаланушыларының UUID-лері. Жалпыға ортақ веб-сайт формасы үшін келушіге бұл мәндерді өзі орнатуға рұқсат бермеңіз: бэкенд оларды интеграция конфигурациясынан беруі керек.

Маркетингтік визит деректері

Форма жіберілмес бұрын, келесілерді cookie-де, сессия сақтауышында немесе бэкендте сақтаңыз:

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": "Веб-сайт сұранысы: консультация сұранысы",
    "ownerId": "11111111-1111-1111-1111-111111111111",
    "authorId": "11111111-1111-1111-1111-111111111111",
    "quality": "WARM"
  }'

`201 Created` жауап мысалы

json

{
  "id": "22222222-2222-2222-2222-222222222222",
  "message": "Веб-сайт сұранысы: консультация сұранысы",
  "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": "Бот"
  },
  "owner": {
    "id": "11111111-1111-1111-1111-111111111111",
    "firstName": "CRM",
    "lastName": "Бот"
  }
}

Жауаптағы id мәнін сақтаңыз: бұл мән маркетингтік оқиғаның leadId өрісінде беріледі.

5. Lead-Submitted оқиғасын жіберу

Эндпоинт

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 және tenant жұбы үшін бұрын өңделген болса, 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 || `Веб-сайт сұранысы: ${form.subject || 'тақырып жоқ'}`,
        ownerId: process.env.CRM_LEAD_OWNER_ID,
        authorId: process.env.CRM_LEAD_AUTHOR_ID,
        quality: 'WARM',
      }),
    },
  );

  if (!leadResponse.ok) {
    throw new Error(`CRM лид құру сәтсіз аяқталды: ${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 маркетингтік оқиғасы сәтсіз аяқталды: ${eventResponse.status}`);
  }

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

7. Идемпотенттілік және қайталап жіберу

Әрбір форма жіберу үшін тұрақты externalId жасаңыз. Мысалы, бірінші сұранысқа дейін жасалған UUID немесе бірегей форма requestId пайдаланыңыз.
Желілік қате кезінде маркетингтік оқиға сұранысын сол externalId арқылы қайталаңыз.
Қайталағанда жаңа externalId жасамаңыз: бұл қайталанатын оқиға жасайды.
Егер лид құру сұранысы уақыт аяқталуына байланысты белгісіз нәтижемен аяқталса, соқыр түрде жаңа лид жасамаңыз. Алдымен өзіңіздің requestId және сайт бэкендіндегі дедупликация механизмін пайдаланыңыз, немесе CRM-ден жасалған лидті табыңыз.
Оқиғаны жіберу қатесі пайдаланушыны лид құру нәтижесін тексермей форманы қайта жіберуге мәжбүрлемеуі керек.

8. Жеке деректер және metadata

metadata ішіне жеке деректер мен форма мазмұнын беруге тыйым салынады:

электрондық пошта
телефон
аты мен тегі
мекенжай
хабарлама мәтіні
жеке деректері бар идентификаторларды қамтитын cookie-лер

Жеке деректер тек осыған арналған CRM нысандарында берілуі керек — мысалы, алдын ала жасалған contactId/clientId ішінде. metadata ішінде тек техникалық атрибуттарды қалдырыңыз: форма аты, бет түрі, баннер нұсқасы және т.б.

9. Типтік жауаптар мен қателер

HTTP	Жағдай	Не істеу керек
`201`	Лид жасалды	`id` мәнін сақтаңыз және `lead_submitted` жіберіңіз
`200` + `duplicate: false`	Оқиға қабылданды	`eventId` мәнін интеграция журналында сақтаңыз
`200` + `duplicate: true`	Оқиға бұрын қабылданған	Өңделген деп қараңыз; қайта жібермеңіз
`400`	Жарамсыз деректер немесе `metadata` ішінде PII	Жүктемені түзетіңіз; өзгеріссіз қайталау көмектеспейді
`401`	Токен жарамсыз немесе жоқ	Бэкендте CRM токенін жаңартыңыз
`403`	Токенде операцияға рұқсат жоқ	Рөл мен tenant-ны тексеріңіз
`5xx` / уақыт аяқталды	Өтпелі 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. Веб-сайт лидтерін алу үшін, егер тиісті деректер CRM-де сақталса, message, createdAtFrom/createdAtTo, contactEmail немесе search сүзгілерін қосымша пайдаланыңыз.

Веб-сайттан лидтер алу

1. Шолу

2. Аутентификация және негізгі URL

3. Сайтта жинау үшін деректер

Лид деректері

Маркетингтік визит деректері

4. Лид құру

Эндпоинт

Сұраныс мысалы

201 Created жауап мысалы

5. Lead-Submitted оқиғасын жіберу

Эндпоинт

Сұраныс мысалы

Жауап мысалы

6. Сервер жағындағы өңдеушінің мысалы

7. Идемпотенттілік және қайталап жіберу

8. Жеке деректер және metadata

9. Типтік жауаптар мен қателер

10. Нәтижелерді CRM-де тексеру

Жасалған лидті алу

Тізім немесе салыстыру үшін лидтерді алу

`201 Created` жауап мысалы