ReactiveCRM Интеграция нұсқаулығы

ReactiveCRM-мен өз интеграциясын жасағысы келетін компаниялар (tenant) үшін техникалық құжаттама: лидтер мен клиенттерді енгізу, мәмілелер құру, маркетингтік оқиғалар жіберу және деректерді экспорттау.

Бұл құжат тек сыртқы интеграциялар үшін жиі қолданылатын API-ларды қамтиды. Ішкі анықтамалық деректер мен әкімшілік қызмет эндпоинттері әдейі қамтылмаған.

1. Интеграцияға шолу

Типтік интеграция ағымы келесідей көрінеді:

мәтін

Сіздің жүйеңіз (бэкенд / сервер жағындағы прокси)
    |
    | 1. POST /api/auth/login  (қатынау + жаңарту токендерін алу)
    v
ReactiveCRM
    | 2. Сілтемелер: GET /api/users/paged, GET /api/statuses, GET /api/stages, GET /api/lead-sources
    |    (ownerId, authorId, statusId және т.б. үшін UUID алу)
    v
    | 3. Негізгі операциялар:
    |      POST /api/leads/create              — лид құру
    |      POST /api/clients/create            — клиент құру
    |      POST /api/contacts/create           — байланыс құру
    |      POST /api/deals/create              — мәміле құру
    |      POST /api/dashboard/marketing/events — маркетингтік оқиға жіберу
    |      POST /api/leads/import/batch         — лидтерді жаппай импорттау
    v
    | 4. Оқу / экспорттау:
    |      GET /api/leads/paged                 — сүзгілермен беттелген оқу
    |      GET /api/export/leads                — барлық лидтерді NDJSON экспорттау

Негізгі қауіпсіздік ережесі: CRM API-сын соңғы пайдаланушының браузерінен тікелей шақырмаңыз. CRM токені мен ішкі идентификаторларды бэкендте (немесе serverless функцияда) сақтаңыз.

2. Аутентификация

2.1. Токендерді алу

Аутентификация эндпоинттері токенді қажет етпейді:

Әдіс	URL	Сипаттама
`POST`	`/api/auth/login`	Пайдаланушы аты + құпия сөзбен кіру, қатынау + жаңарту токендерін қайтарады
`POST`	`/api/auth/refresh`	Жаңарту токенін жаңа токен жұбына айырбастау
`POST`	`/api/auth/logout`	Жаңарту токенін қайтарып алу

bash

curl -X POST "$CRM_BASE_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "integration", "password": "secret123"}'

json

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "refreshToken": "a8f3k2m9Qx7Tt1Vv...",
  "tokenType": "Bearer",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "firstName": "Интеграция",
    "lastName": "Бот",
    "tenantId": "660e8400-e29b-41d4-a716-446655440001"
  },
  "tenant": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Zunga Corp"
  }
}

2.2. Токендерді өңдеу ережелері

Қатынау токені (token) — 1 сағат өмір сүретін JWT. Әрбір сұраныспен бірге жіберіңіз: Authorization: Bearer <token>.
Жаңарту токені (refreshToken) — 7 күн өмір сүретін кездейсоқ жол. Жаңа токен жұбын алу үшін пайдаланыңыз.
Әрбір /api/auth/refresh кезінде сервер жаңарту токенін айналдырады: ескісі жойылып, жаңасы шығарылады. Екі жаңа мәнді де сақтаңыз.
Мерзімі өткен қатынау токені бар сұраныс 401 қайтарады. Бұл жағдайда жаңартып, бастапқы сұранысты қайталаңыз — қайта кірмеңіз.

2.3. Негізгі параметрлер

мәтін

CRM_BASE_URL=https://crm.example.com

Төмендегі барлық мысалдар келесі заголовкаларды болжайды:

http

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

3. Беттелген API конвенциялары

GET /api/*/paged түріндегі барлық тізім эндпоинттері бірдей конвенцияларды бөліседі:

Параметр	Түрі	Әдепкі	Сипаттама
`page`	бүтін	`0`	Бет нөмірі, нөлден басталады
`size`	бүтін	эндпоинт бойынша	Бет өлшемі
`sort`	жол	`createdAt,desc`	`өріс,бағыт` форматында сұрыптау. Бағыты: `asc` немесе `desc`

Беттелген жауап құрылымы

json

{
  "content": [ { "..." } ],
  "page": 0,
  "size": 20,
  "totalElements": 137,
  "totalPages": 7
}

Күн бойынша сүзгілеу

Ауқымдар үшін өрісFrom / өрісTo параметрлерін пайдаланыңыз (ISO 8601):

мәтін

createdAtFrom=2026-01-01T00:00:00Z
createdAtTo=2026-01-31T23:59:59Z

Сұрыптау

Әрқашан ?sort=өріс,бағыт:

мәтін

?sort=createdAt,desc
?sort=name,asc

Кейбір сүзгі өрістерінің арнайы ауқым параметрлері бар (мысалы, dealAmountFrom/dealAmountTo).

Сүзгілеу семантикасы

Барлық сүзгілеу мен сұрыптау сервер жағында орындалады (бәрін жүктеп алып, клиент жағында сүзгілеудің қажеті жоқ).
Бірнеше сүзгілер ЖӘНЕ арқылы біріктіріледі.
Мәтіндік (ішкі жол) сүзгілер регистрге сезімтал емес іздеуді пайдаланады (ILIKE).
Әмбебап search сүзгісі бірнеше өрістер бойынша НЕМЕСЕ арқылы іздейді.

4. Сілтемелер (UUID алу)

Нысандарды құрмас бұрын, байланысты анықтамалық деректердің UUID-лерін алыңыз. Негізгілері:

4.1. Пайдаланушылар (`GET /api/users/paged`)

ownerId, authorId, developingManagerIds үшін пайдаланылады.

bash

curl "$CRM_BASE_URL/api/users/paged?page=0&size=50&sort=createdAt,asc" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

Жауап мысалы (content фрагменті):

json

[
  {
    "id": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "firstName": "Roman",
    "lastName": "Posledovskiy",
    "username": "roman",
    "email": "roman@example.com",
    "tenantId": "660e8400-e29b-41d4-a716-446655440001"
  }
]

4.2. Мәртебелер (`GET /api/statuses`)

Лидтердің, мәмілелердің және мәміле тараптары клиенттерінің statusId үшін пайдаланылады. Массив қайтарады:

bash

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

json

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "New",
    "entityType": "LEAD"
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "name": "In progress",
    "entityType": "STAGE"
  }
]

4.3. Кезеңдер (`GET /api/stages`)

Мәміленің stageId үшін пайдаланылады:

bash

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

4.4. Лид дереккөздері (`GET /api/lead-sources`)

Лид дереккөздерінің ағашын қайтарады. Лидтің leadSourceId үшін пайдаланылады:

bash

curl "$CRM_BASE_URL/api/lead-sources" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

json

[
  {
    "id": "cccc0001-0000-0000-0000-000000000001",
    "name": "Website",
    "children": [
      {
        "id": "cccc0001-0000-0000-0000-000000000002",
        "name": "Feedback form",
        "children": []
      }
    ]
  }
]

5. Лидтер

5.1. Лид құру (`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": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "authorId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "leadSourceId": "cccc0001-0000-0000-0000-000000000002",
    "statusId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "quality": "WARM"
  }'

Сұраныс өрістері:

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

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

json

{
  "id": "22222222-2222-2222-2222-222222222222",
  "message": "Веб-сайт сұранысы: консультация",
  "status": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "New"
  },
  "quality": "WARM",
  "dealId": null,
  "createdAt": "2026-09-05T20:00:00Z",
  "updatedAt": "2026-09-05T20:00:00Z",
  "version": 0,
  "author": {
    "id": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "firstName": "Roman",
    "lastName": "Posledovskiy"
  },
  "owner": {
    "id": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "firstName": "Roman",
    "lastName": "Posledovskiy"
  }
}

Қайтарылған id-ні сақтаңыз — ол маркетингтік оқиғаның leadId үшін қажет (8-бөлімді қараңыз).

5.2. Беттелген оқу (`GET /api/leads/paged`)

bash

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

Негізгі сүзгілер:

Параметр	Түрі	Режим	Сипаттама
`statusId`	uuid	дәл	Мәртебе бойынша сүзгілеу
`leadSourceId`	uuid	дәл	Лид дереккөзі бойынша сүзгілеу
`quality`	enum	дәл	`HOT`, `WARM`, `COOL`, `COLD`
`message`	жол	ILIKE	Хабарламадағы ішкі жол
`search`	жол	ILIKE (НЕМЕСЕ)	Хабарлама, байланыс, электрондық пошта, телефон бойынша іздеу
`contactEmail`	жол	ILIKE	Байланыстың электрондық поштасы бойынша
`contactPhone`	жол	ILIKE	Байланыстың телефоны бойынша
`company`	жол	ILIKE	Компания аты бойынша
`clientId`	uuid	дәл	Клиент ID бойынша
`createdAtFrom` / `createdAtTo`	күн-уақыт	ауқым	Құрылған күні бойынша
`updatedAtFrom` / `updatedAtTo`	күн-уақыт	ауқым	Жаңартылған күні бойынша
`createdBy`	uuid	дәл	Лид авторы бойынша

Сондай-ақ байланысты мәміле үшін сүзгілер бар: dealStatusId, dealStageId, dealAmountFrom/dealAmountTo, dealProbabilityFrom/dealProbabilityTo.

Сұрыптау: createdAt, updatedAt, message, quality, мәртебе/дереккөз және басқалар (өріс,бағыт форматы).

5.3. Бір лидті алу (`GET /api/leads/{id}`)

bash

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

5.4. Лидтерді жаппай импорттау (`POST /api/leads/import/batch`)

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

bash

curl -X POST "$CRM_BASE_URL/api/leads/import/batch" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "leads-2026-09-05.csv",
    "leads": [
      {
        "message": "Сұраныс #1",
        "ownerId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
        "authorId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
        "quality": "WARM"
      },
      {
        "message": "Сұраныс #2",
        "ownerId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
        "authorId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
        "quality": "COOL"
      }
    ]
  }'

Жауап мысалы:

json

{
  "importId": "44444444-4444-4444-4444-444444444444",
  "imported": 2,
  "total": 2,
  "skipped": []
}

imported — қаншасы құрылды.
skipped — index (0-негізінде) және reason бар өткізіп жіберілген жолдар массиві.

Тарих және кері қайтару:

bash

# Импорт тарихы
curl "$CRM_BASE_URL/api/leads/import/history" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

# Импортты кері қайтару
curl -X POST "$CRM_BASE_URL/api/leads/import/rollback/$IMPORT_ID" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

5.5. Веб-сайттан жылдам лид (`POST /api/site/leads`)

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

Арнайы нұсқаулықты қараңыз: site-lead-multi-contract.md.

6. Клиенттер мен Байланыстар

6.1. Клиент құру (`POST /api/clients/create`)

bash

curl -X POST "$CRM_BASE_URL/api/clients/create" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "COMPANY",
    "name": "Romashka LLC",
    "taxId": "7700000001",
    "regNumber": "1234567890",
    "country": "RU",
    "phone": "+7-495-000-00-01",
    "email": "info@romashka.ru",
    "website": "https://romashka.ru",
    "ownerId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "authorId": "7a786a66-3617-48c1-921d-97f4aaefcd35"
  }'

Негізгі өрістер:

Өріс	Түрі	Қатысты	Сипаттама
`type`	enum	барлығы	`INDIVIDUAL` немесе `COMPANY` (міндетті)
`name`	жол	барлығы	Көрсетілетін атау (міндетті)
`firstName` / `lastName`	жол	INDIVIDUAL	Аты/тегі
`taxId`	жол	COMPANY	Салық идентификаторы (INN)
`regNumber`	жол	COMPANY	Тіркеу нөмірі
`legalAddress`	жол	COMPANY	Заңды мекенжай
`phone` / `email` / `website`	жол	барлығы	Байланыстар
`country`	жол	барлығы	ISO ел коды
`ownerId`	uuid	барлығы	Жауапты пайдаланушы
`authorId`	uuid	барлығы	Автор
`developingManagerIds`	uuid[]	барлығы	Дамытушы менеджерлер

6.2. Клиенттерді беттелген оқу (`GET /api/clients/paged`)

bash

curl "$CRM_BASE_URL/api/clients/paged?page=0&size=20&type=COMPANY&search=Romashka&sort=name,asc" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

Негізгі сүзгілер: name, type (INDIVIDUAL/COMPANY), country, taxId, email, phone, lastName (жеке тұлғалар), search (аты/Салық ID/телефоны бойынша), createdAtFrom/createdAtTo, createdBy, developingManagerId.

6.3. Дубликаттарды тексеру (`GET /api/clients/duplicates`)

Клиент құрмас бұрын, ұқсасы бар-жоғын тексеріңіз:

bash

# Салық ID және аты бойынша
curl "$CRM_BASE_URL/api/clients/duplicates?type=COMPANY&taxId=7700000001&name=Romashka" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

6.4. Байланыс құру (`POST /api/contacts/create`)

bash

curl -X POST "$CRM_BASE_URL/api/contacts/create" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Иван",
    "lastName": "Петров",
    "dateOfBirth": "1990-05-15",
    "gender": "MALE",
    "countryCode": "RU",
    "ownerId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "authorId": "7a786a66-3617-48c1-921d-97f4aaefcd35"
  }'

Өрістер: firstName (міндетті), lastName, patronymicName, dateOfBirth (date), gender (MALE/FEMALE), countryCode, ownerId, authorId.

6.5. Байланыстарды беттелген оқу (`GET /api/contacts/paged`)

bash

curl "$CRM_BASE_URL/api/contacts/paged?page=0&size=20&search=Петров&sort=createdAt,desc" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

7. Мәмілелер

7.1. Мәміле құру (`POST /api/deals/create`)

bash

curl -X POST "$CRM_BASE_URL/api/deals/create" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Серверлік аппараттық жеткізу",
    "clientId": "9f128931-69fd-493a-9a08-be5be0e6603d",
    "statusId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "stageId": "dddd0001-0000-0000-0000-000000000001",
    "probability": 60,
    "amount": 150000.00,
    "ownerId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
    "authorId": "7a786a66-3617-48c1-921d-97f4aaefcd35"
  }'

Негізгі өрістер:

Өріс	Түрі	Міндетті	Сипаттама
`name`	жол	иә	Мәміле атауы
`clientId`	uuid	иә	Клиент ID
`statusId`	uuid	жоқ	Мәртебе (кезең мәртебесі)
`stageId`	uuid	жоқ	Сату кезеңі
`probability`	бүтін	жоқ	Ықтималдық 0-100
`amount`	сан	жоқ	Сома
`plannedAmount`	сан	жоқ	Жоспарланған сома
`discountPercent`	бүтін	жоқ	Жеңілдік 0-100
`startDate` / `expectedCloseDate`	күн-уақыт	жоқ	Күндер
`ownerId`	uuid	жоқ	Иесі
`leadId`	uuid	жоқ	Байланысты лид
`contactId`	uuid	жоқ	Байланысты байланыс
`productIds`	uuid[]	жоқ	Өнімдер (жеңілдетілген формат)
`dealProducts`	массив	жоқ	Мәміле жолдары (толық формат)
`dealParties`	массив	жоқ	Мәміле тараптары

7.2. Мәмілелерді беттелген оқу (`GET /api/deals/paged`)

bash

curl "$CRM_BASE_URL/api/deals/paged?page=0&size=20&stageKind=OPEN&sort=createdAt,desc" \
  -H "Authorization: Bearer $CRM_ACCESS_TOKEN"

Негізгі сүзгілер: name (ILIKE), clientId, clientName, statusId, stageId, stageKind (OPEN/WON/LOST), ownerId, search, startDateFrom/startDateTo, expectedCloseDateFrom/expectedCloseDateTo, actualCloseDateFrom/actualCloseDateTo, createdAtFrom/createdAtTo.

8. Маркетингтік оқиғалар (Атрибуция)

UTM тегтерін, жарнама идентификаторларын және трафик дереккөздерін жіберу үшін пайдаланыңыз:

`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 құрыңыз (UUID немесе бірегей requestId). Бір source/tenant үшін бірдей externalId арқылы қайта жіберу duplicate: true қайтарады — бұл қате емес.
Қайталап жібергенде жаңа externalId жасамаңыз.
metadata ішіне дербес идентификациялық ақпаратты (электрондық пошта, телефон, аты, хабарлама мәтіні) салмаңыз. Тек форма аты немесе бет түрі сияқты техникалық атрибуттар.

Толығырақ site-leads-integration-guide.md қараңыз.

9. Деректерді экспорттау (NDJSON)

Экспорт эндпоинттері tenant-ның барлық жазбаларын NDJSON форматында қайтарады (жолына бір JSON объекті, \n арқылы бөлінген).

Эндпоинт	Сипаттама
`GET /api/export/leads`	Барлық tenant лидтері
`GET /api/export/clients`	Барлық tenant клиенттері
`GET /api/export/contacts`	Барлық tenant байланыстары

bash

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

Жауап мысалы (жол ағыны):

мәтін

{"id":"550e8400-e29b-41d4-a716-446655440001","message":"Веб-сайт сұранысы","quality":"WARM","statusName":"New","createdAt":"2026-08-20T10:00:00+03:00","ownerName":"Иван Иванов","clientName":"Romashka LLC","contactFirstName":"Петр","contactLastName":"Петров","leadSourceName":"Paid search"}
{"id":"550e8400-e29b-41d4-a716-446655440002","message":"Телефон қоңырауы","quality":"COOL","statusName":"In progress","createdAt":"2026-08-19T09:00:00+03:00","ownerName":"Мария Смирнова","clientName":null}

Маңызды: NDJSON жарамды JSON массиві емес. Жауапты ReadableStream арқылы жол бойынша оқыңыз (бүкіл жауапқа JSON.parse() шақырмаңыз).

10. Аяқтан-аяққа интеграция мысалы

Келесі сценарий веб-сайт лидін жасайды, байланыс пен клиентті байланыстырады, мәміле құрады және маркетингтік оқиға жібереді.

bash

CRM_BASE_URL=https://crm.example.com
CRM_TOKEN="<access-token>"

# 1. Кіру
curl -s -X POST "$CRM_BASE_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "integration", "password": "secret123"}' | tee /tmp/login.json

CRM_TOKEN=$(jq -r '.token' /tmp/login.json)

OWNER_ID=$(curl -s "$CRM_BASE_URL/api/users/paged?page=0&size=50" \
  -H "Authorization: Bearer $CRM_TOKEN" | jq -r '.content[0].id')

# 2. Клиент құру
curl -s -X POST "$CRM_BASE_URL/api/clients/create" \
  -H "Authorization: Bearer $CRM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"type\": \"COMPANY\",
    \"name\": \"Romashka LLC\",
    \"taxId\": \"7700000001\",
    \"country\": \"RU\",
    \"ownerId\": \"$OWNER_ID\",
    \"authorId\": \"$OWNER_ID\"
  }" | tee /tmp/client.json

CLIENT_ID=$(jq -r '.id' /tmp/client.json)

# 3. Байланыс құру
curl -s -X POST "$CRM_BASE_URL/api/contacts/create" \
  -H "Authorization: Bearer $CRM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"firstName\": \"Иван\",
    \"lastName\": \"Петров\",
    \"countryCode\": \"RU\",
    \"ownerId\": \"$OWNER_ID\",
    \"authorId\": \"$OWNER_ID\"
  }" | tee /tmp/contact.json

CONTACT_ID=$(jq -r '.id' /tmp/contact.json)

# 4. Лид құру
curl -s -X POST "$CRM_BASE_URL/api/leads/create" \
  -H "Authorization: Bearer $CRM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"Веб-сайт сұранысы\",
    \"clientId\": \"$CLIENT_ID\",
    \"contactId\": \"$CONTACT_ID\",
    \"ownerId\": \"$OWNER_ID\",
    \"authorId\": \"$OWNER_ID\",
    \"quality\": \"WARM\"
  }" | tee /tmp/lead.json

LEAD_ID=$(jq -r '.id' /tmp/lead.json)

# 5. Лидке байланысты мәміле құру
curl -s -X POST "$CRM_BASE_URL/api/deals/create" \
  -H "Authorization: Bearer $CRM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Иван Петров үшін консультация\",
    \"clientId\": \"$CLIENT_ID\",
    \"leadId\": \"$LEAD_ID\",
    \"contactId\": \"$CONTACT_ID\",
    \"amount\": 50000.00,
    \"ownerId\": \"$OWNER_ID\",
    \"authorId\": \"$OWNER_ID\"
  }"

# 6. Маркетингтік оқиға жіберу
curl -s -X POST "$CRM_BASE_URL/api/dashboard/marketing/events" \
  -H "Authorization: Bearer $CRM_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"eventType\": \"lead_submitted\",
    \"occurredAt\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",
    \"leadId\": \"$LEAD_ID\",
    \"externalId\": \"request-$(uuidgen)\",
    \"source\": \"website\",
    \"channel\": \"direct\",
    \"landingUrl\": \"https://www.example.com/form\",
    \"metadata\": {\"formName\": \"consultation\"}
  }"

11. Идемпотенттілік және қателерді өңдеу

Тұрақты идентификатор: әрбір жіберу үшін өзіңіздің externalId (UUID немесе requestId) жасаңыз. Бірдей externalId қайта жіберу дубликат жасамауы керек (маркетингтік оқиғалар үшін бұл серверде өңделеді — duplicate: true).
Бірдей идентификатормен қайталау: желілік қате кезінде сол externalId арқылы қайталаңыз; жаңасын жасамаңыз.
Соқыр дубликаттамаңыз: егер құру сұранысы уақыты аяқталса, алдымен нәтижені тексеріңіз (өзіңіздің requestId пайдаланып немесе құрылған нысанды тауып) жаңасын жасаудың орнына.
400: жарамсыз жүктеме — өзгеріссіз қайталау көмектеспейді; деректерді түзетіңіз.
401: қатынау токенінің мерзімі өткен — /api/auth/refresh шақырып, сұранысты қайталаңыз.
403: рұқсат жоқ — рөл мен tenant-ны тексеріңіз.
5xx/уақыт аяқталды: өтпелі қате — сол externalId арқылы қайталаңыз (лидтер үшін кезекті пайдаланыңыз).

12. Жылдам бастау

Аутентификациядан өтіңіз POST /api/auth/login арқылы; token және refreshToken сақтаңыз.
Қосыңыз әрбір сұранысқа Authorization: Bearer <token>. 401 кезінде /api/auth/refresh арқылы жаңартыңыз.
Сілтемелерді алыңыз (пайдаланушылар/мәртебелер/кезеңдер/лид дереккөздері) бір рет және UUID-лерді кэштеңіз.
Нысандарды құрыңыз логикалық тәртіпте: клиент → байланыс → лид → мәміле.
Беттелген эндпоинттерді пайдаланыңыз сервер жағындағы сүзгілеу және сұрыптау арқылы оқу үшін.
Экспорттар үшін NDJSON эндпоинттерін пайдаланыңыз және ағынды жол бойынша оқыңыз.
Жаппай енгізу үшін batch эндпоинттерін пайдаланыңыз (/api/leads/import/batch, /api/clients/import/batch) кері қайтару қолдауымен.
Маркетингтік атрибуцияны жіберіңіз POST /api/dashboard/marketing/events арқылы тұрақты externalId көмегімен.
Ешқашан сақтамаңыз және маркетингтік оқиғаның metadata ішіне PII бермеңіз.
Әрбір API бойынша толық құжаттаманы қараңыз: site-leads-integration-guide.md.

ReactiveCRM Интеграция нұсқаулығы

1. Интеграцияға шолу

2. Аутентификация

2.1. Токендерді алу

2.2. Токендерді өңдеу ережелері

2.3. Негізгі параметрлер

3. Беттелген API конвенциялары

Беттелген жауап құрылымы

Күн бойынша сүзгілеу

Сұрыптау

Сүзгілеу семантикасы

4. Сілтемелер (UUID алу)

4.1. Пайдаланушылар (GET /api/users/paged)

4.2. Мәртебелер (GET /api/statuses)

4.3. Кезеңдер (GET /api/stages)

4.4. Лид дереккөздері (GET /api/lead-sources)

5. Лидтер

5.1. Лид құру (POST /api/leads/create)

5.2. Беттелген оқу (GET /api/leads/paged)

5.3. Бір лидті алу (GET /api/leads/{id})

5.4. Лидтерді жаппай импорттау (POST /api/leads/import/batch)

5.5. Веб-сайттан жылдам лид (POST /api/site/leads)

6. Клиенттер мен Байланыстар

6.1. Клиент құру (POST /api/clients/create)

6.2. Клиенттерді беттелген оқу (GET /api/clients/paged)

6.3. Дубликаттарды тексеру (GET /api/clients/duplicates)

6.4. Байланыс құру (POST /api/contacts/create)

6.5. Байланыстарды беттелген оқу (GET /api/contacts/paged)

7. Мәмілелер

7.1. Мәміле құру (POST /api/deals/create)

7.2. Мәмілелерді беттелген оқу (GET /api/deals/paged)

8. Маркетингтік оқиғалар (Атрибуция)

POST /api/dashboard/marketing/events

9. Деректерді экспорттау (NDJSON)

10. Аяқтан-аяққа интеграция мысалы

11. Идемпотенттілік және қателерді өңдеу

12. Жылдам бастау

4.1. Пайдаланушылар (`GET /api/users/paged`)

4.2. Мәртебелер (`GET /api/statuses`)

4.3. Кезеңдер (`GET /api/stages`)

4.4. Лид дереккөздері (`GET /api/lead-sources`)

5.1. Лид құру (`POST /api/leads/create`)

5.2. Беттелген оқу (`GET /api/leads/paged`)

5.3. Бір лидті алу (`GET /api/leads/{id}`)

5.4. Лидтерді жаппай импорттау (`POST /api/leads/import/batch`)

5.5. Веб-сайттан жылдам лид (`POST /api/site/leads`)

6.1. Клиент құру (`POST /api/clients/create`)

6.2. Клиенттерді беттелген оқу (`GET /api/clients/paged`)

6.3. Дубликаттарды тексеру (`GET /api/clients/duplicates`)

6.4. Байланыс құру (`POST /api/contacts/create`)

6.5. Байланыстарды беттелген оқу (`GET /api/contacts/paged`)

7.1. Мәміле құру (`POST /api/deals/create`)

7.2. Мәмілелерді беттелген оқу (`GET /api/deals/paged`)

`POST /api/dashboard/marketing/events`