Көп келісімшартты веб-сайттан лидтерді қабылдау

Бұл құжат веб-сайт бэкенді лид деректерін, келушінің байланыс мәліметтерін және маркетингтік UTM метрикаларын ReactiveCRM-ге бір сұраныспен жіберетін бірыңғай API келісімшартын сипаттайды.

1. Мақсаты

Веб-сайт интеграторы байланысты, телефонды, электрондық поштаны, лидті және маркетингтік оқиғаны бөлек жасаудың қажеті жоқ. Бір сұраныс атомарлы түрде мыналарды жасауы керек:

байланыс;
байланыстың негізгі телефоны;
байланыстың негізгі электрондық поштасы, егер берілсе;
лид;
байланыс пен лид арасындағы байланыс;
маркетингтік оқиға және UTM атрибуциясы.

Егер кез келген қадам сәтсіз болса, бүкіл сұраныс кері қайтарылады және ішінара жасалған деректер сақталмайды.

2. Эндпоинт

http

POST /api/site/leads
Authorization: Bearer <CRM_ACCESS_TOKEN>
Content-Type: application/json

Токен тек веб-сайт бэкендінен немесе serverless функциясынан берілуі керек. CRM токенін браузер JavaScript-іне ешқашан қоймаңыз.

Tenant авторизация токенінен анықталады. Барлық берілген UUID осы tenant ішінде тексеріледі.

3. Толық JSON келісімшарты

json

{
  "externalId": "site-form-01J7K9A2M4Y5T6",
  "lead": {
    "leadSourceId": "7b33b18f-55bd-48a5-a8f0-e450a56dde47",
    "quality": "WARM",
    "message": "CRM енгізу бойынша консультация алғым келеді"
  },
  "contact": {
    "firstName": "Иван",
    "lastName": "Иванов",
    "phone": "+79991234567",
    "email": "ivan@example.com"
  },
  "marketing": {
    "occurredAt": "2026-09-06T18:00:00Z",
    "visitorId": "visitor-8b7f",
    "sessionId": "session-31ac",
    "source": "website",
    "channel": "paid",
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "summer-consulting",
    "utmContent": "banner-a",
    "utmTerm": "crm consultation",
    "gclid": "EAIaIQobChMI-example",
    "fbclid": null,
    "landingUrl": "https://example.com/consultation",
    "referrer": "https://www.google.com/"
  }
}

4. Сұраныс өрістері

4.1. Түбір өрістер

Өріс	Түрі	Міндетті	Сипаттама
`externalId`	жол	ұсынылады	Идемпотенттілік үшін форманы жіберудің тұрақты бірегей ID-і
`lead`	объект	иә	Құрылып жатқан лидтің деректері
`contact`	объект	иә	Байланыс адамының деректері
`marketing`	объект	жоқ	Маркетингтік визиттің UTM метрикалары мен техникалық деректері

externalId бірінші жіберу әрекетіне дейін жасалады. Уақыт аяқталуынан немесе желілік қатеден кейін сұранысты қайталағанда, сол мәнді пайдаланыңыз.

4.2. `lead` объектісі

Өріс	Түрі	Міндетті	Сипаттама
`leadSourceId`	uuid	иә	Ағымдағы tenant-тағы лид дереккөзінің ID-і
`quality`	жол	жоқ	Бастапқы бағалау: `HOT`, `WARM`, `COOL` немесе `COLD`
`message`	жол	жоқ	Келушінің хабарламасы немесе жіберу туралы пікір

Егер сайт алдын ала саралауды орындамаса, quality өрісін жібермеген дұрыс.

4.3. `contact` объектісі

Өріс	Түрі	Міндетті	Сипаттама
`firstName`	жол	иә	Байланыс адамының аты
`lastName`	жол	жоқ	Байланыс адамының тегі
`phone`	жол	иә	Негізгі телефон; E.164 форматы ұсынылады
`email`	жол(email)	жоқ	Байланыс адамының негізгі электрондық поштасы

Жіберуді өңдеу үшін қажетті ең аз деректер — firstName және phone.

4.4. `marketing` объектісі

Өріс	Түрі	Міндетті	Сипаттама
`occurredAt`	күн-уақыт	жоқ	Форманы жіберу уақыты; болмаған жағдайда CRM уақыты пайдаланылады
`visitorId`	жол	жоқ	Анонимді келуші ID-і
`sessionId`	жол	жоқ	Сайт сессиясының ID-і
`source`	жол	жоқ	Оқиға дереккөзі, әдепкі бойынша `website`
`channel`	жол	жоқ	Арна: мысалы `paid`, `organic`, `social`, `email`, `direct`
`utmSource`	жол	жоқ	`utm_source` мәні
`utmMedium`	жол	жоқ	`utm_medium` мәні
`utmCampaign`	жол	жоқ	`utm_campaign` мәні
`utmContent`	жол	жоқ	`utm_content` мәні
`utmTerm`	жол	жоқ	`utm_term` мәні
`gclid`	жол	жоқ	Google басу ID-і
`fbclid`	жол	жоқ	Meta/Facebook басу ID-і
`landingUrl`	жол	жоқ	Қону бетінің URL-і
`referrer`	жол	жоқ	Алдыңғы беттің URL-і

Жеке деректер маркетинг объектісінде қайталанбауы керек. Аты, телефоны, электрондық поштасы және хабарлама мәтіні тек contact және lead арқылы беріледі.

5. Ең аз сұраныс

json

{
  "externalId": "site-form-550e8400-e29b-41d4-a716-446655440000",
  "lead": {
    "leadSourceId": "7b33b18f-55bd-48a5-a8f0-e450a56dde47"
  },
  "contact": {
    "firstName": "Иван",
    "phone": "+79991234567"
  }
}

6. Сәтті жауап

Бірінші сұраныс — `201 Created`

json

{
  "leadId": "22222222-2222-2222-2222-222222222222",
  "contactId": "33333333-3333-3333-3333-333333333333",
  "phoneId": "44444444-4444-4444-4444-444444444444",
  "emailId": "55555555-5555-5555-5555-555555555555",
  "marketingEventId": "66666666-6666-6666-6666-666666666666",
  "duplicate": false,
  "createdAt": "2026-09-06T18:00:01Z"
}

Егер электрондық пошта немесе маркетинг деректері берілмесе, сәйкес ID-лер null ретінде қайтарылады.

Бірдей `externalId` арқылы қайталау — `200 OK`

json

{
  "leadId": "22222222-2222-2222-2222-222222222222",
  "contactId": "33333333-3333-3333-3333-333333333333",
  "phoneId": "44444444-4444-4444-4444-444444444444",
  "emailId": "55555555-5555-5555-5555-555555555555",
  "marketingEventId": "66666666-6666-6666-6666-666666666666",
  "duplicate": true,
  "createdAt": "2026-09-06T18:00:01Z"
}

Қайталанатын сұраныс екінші лид немесе байланыс жасамауы керек.

7. cURL мысалы

bash

curl -X POST "$CRM_BASE_URL/api/site/leads" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "site-form-01J7K9A2M4Y5T6",
    "lead": {
      "leadSourceId": "7b33b18f-55bd-48a5-a8f0-e450a56dde47",
      "quality": "WARM",
      "message": "Маған қоңырау шалыңыз"
    },
    "contact": {
      "firstName": "Иван",
      "lastName": "Иванов",
      "phone": "+79991234567",
      "email": "ivan@example.com"
    },
    "marketing": {
      "utmSource": "google",
      "utmMedium": "cpc",
      "utmCampaign": "crm-demo",
      "landingUrl": "https://example.com/demo"
    }
  }'

8. TypeScript интерфейстері

type LeadQuality = 'HOT' | 'WARM' | 'COOL' | 'COLD';

interface SiteLeadRequest {
  externalId?: string;
  lead: {
    leadSourceId: string;
    quality?: LeadQuality;
    message?: string;
  };
  contact: {
    firstName: string;
    lastName?: string;
    phone: string;
    email?: string;
  };
  marketing?: {
    occurredAt?: string;
    visitorId?: string;
    sessionId?: string;
    source?: string;
    channel?: string;
    utmSource?: string;
    utmMedium?: string;
    utmCampaign?: string;
    utmContent?: string;
    utmTerm?: string;
    gclid?: string;
    fbclid?: string;
    landingUrl?: string;
    referrer?: string;
  };
}

interface SiteLeadResponse {
  leadId: string;
  contactId: string;
  phoneId: string;
  emailId: string | null;
  marketingEventId: string | null;
  duplicate: boolean;
  createdAt: string;
}

9. Сервер жағындағы мысал

export async function sendLeadToCrm(payload: SiteLeadRequest): Promise<SiteLeadResponse> {
  const response = await fetch(`${process.env.CRM_BASE_URL}/api/site/leads`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.CRM_ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`ReactiveCRM returned ${response.status}: ${body}`);
  }

  return response.json() as Promise<SiteLeadResponse>;
}

10. Қателер

HTTP	Себебі	Интегратордың әрекеті
`400`	Формат қатесі, міндетті өріс жоқ, жарамсыз электрондық пошта/телефон/quality	Деректерді түзетіңіз; өзгеріссіз автоматты түрде қайталамаңыз
`401`	Токен жоқ немесе жарамсыз	Интеграция токенін жаңартыңыз
`403`	Tenant-қа немесе операцияға рұқсат жоқ	Интеграция пайдаланушысы мен рөлін тексеріңіз
`404`	`leadSourceId` ағымдағы tenant-та табылмады	Сайт параметрлеріндегі дереккөз ID-ін жаңартыңыз
`409`	`externalId` үйлесімсіз сұранысқа байланысты	ID генерациясын және интеграция журналын тексеріңіз
`5xx`	Өтпелі CRM қатесі	Сол `externalId` арқылы сол сұранысты қайталаңыз

Тексеру қатесінің мысалы:

json

{
  "status": 400,
  "error": "Bad Request",
  "message": "contact.phone must not be blank",
  "path": "/api/site/leads"
}

11. Идемпотенттілік

externalId tenant және website дереккөзі ішінде бірегей болуы керек.
externalId бірінші сұранысқа дейін жасап, оны сайт жіберуінде сақтаңыз.
Уақыт аяқталғанда, сол дене және сол externalId арқылы сұранысты қайталаңыз.
Бір жіберуді қайталағанда жаңа externalId жасамаңыз.
Егер duplicate: true болса, жіберу қазірдің өзінде өңделген және сәтті жеткізілген деп саналады.

12. Веб-сайт әзірлеушісіне арналған шағын нұсқаулық

Бірінші визитте UTM тегтерін, gclid, fbclid, қону URL-ін және реферерді сақтаңыз.
Форма жіберілгенде, тұрақты externalId жасаңыз.
Форманы сайт бэкендіне жіберіңіз.
Бэкенд CRM токенін қосып, POST /api/site/leads шақырады.
201 немесе 200 және duplicate: true болса, жіберуді жеткізілген деп санаңыз.
Уақыт аяқталғанда немесе 5xx кезінде сұранысты сол externalId арқылы қайталаңыз.
CRM токенін браузерден тікелей ешқашан жібермеңіз.

13. CRM менеджері не алады

Сәтті сұраныстан кейін CRM келесі лидті қамтиды:

leadSourceId дереккөзі орнатылған;
келушінің хабарламасын сақтайды;
егер сайт берген болса, бастапқы сапа бағасы бар;
аты және негізгі телефоны бар байланыспен байланысты;
егер берілсе, негізгі электрондық поштамен байланысты;
аналитика үшін UTM метрикалары мен жарнама идентификаторларын сақтайды.

Бұл жиынтық менеджерге жіберуді көру, байланысқа қоңырау шалу және лидті саралау үшін жеткілікті.

Көп келісімшартты веб-сайттан лидтерді қабылдау

1. Мақсаты

2. Эндпоинт

3. Толық JSON келісімшарты

4. Сұраныс өрістері

4.1. Түбір өрістер

4.2. lead объектісі

4.3. contact объектісі

4.4. marketing объектісі

5. Ең аз сұраныс

6. Сәтті жауап

Бірінші сұраныс — 201 Created

Бірдей externalId арқылы қайталау — 200 OK

7. cURL мысалы

8. TypeScript интерфейстері

9. Сервер жағындағы мысал

10. Қателер

11. Идемпотенттілік

12. Веб-сайт әзірлеушісіне арналған шағын нұсқаулық

13. CRM менеджері не алады

4.2. `lead` объектісі

4.3. `contact` объектісі

4.4. `marketing` объектісі

Бірінші сұраныс — `201 Created`

Бірдей `externalId` арқылы қайталау — `200 OK`