ReactiveCRM इंटीग्रेशन गाइड

उन कंपनियों (टेनेंट्स) के लिए तकनीकी दस्तावेज़ जो ReactiveCRM के साथ अपना इंटीग्रेशन बनाना चाहती हैं: लीड और क्लाइंट इनजेस्ट करना, डील बनाना, मार्केटिंग इवेंट भेजना और डेटा एक्सपोर्ट करना।

यह दस्तावेज़ केवल उन API को कवर करता है जो बाहरी इंटीग्रेशन में सबसे अधिक उपयोग होते हैं। आंतरिक रेफ़रेंस डेटा और एडमिन सर्विस endpoint जानबूझकर दायरे से बाहर रखे गए हैं।

1. इंटीग्रेशन अवलोकन

एक सामान्य इंटीग्रेशन फ़्लो कुछ इस तरह दिखता है:

text

आपका सिस्टम (backend / server-side proxy)
    |
    | 1. POST /api/auth/login  (access + refresh token प्राप्त करें)
    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                 — फ़िल्टर के साथ paged रीड
    |      GET /api/export/leads                — सभी लीड का NDJSON एक्सपोर्ट

मुख्य सुरक्षा नियम: अंतिम उपयोगकर्ता के ब्राउज़र से सीधे CRM API को कभी कॉल न करें। CRM टोकन और आंतरिक पहचानकर्ता अपने backend (या serverless function) पर रखें।

2. ऑथेंटिकेशन

2.1. टोकन प्राप्त करना

ऑथेंटिकेशन endpoint को टोकन की आवश्यकता नहीं होती:

Method	URL	विवरण
`POST`	`/api/auth/login`	username + password से लॉगिन, access + refresh token लौटाता है
`POST`	`/api/auth/refresh`	refresh token के बदले नया token pair प्राप्त करें
`POST`	`/api/auth/logout`	refresh token रद्द करें

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": "Integration",
    "lastName": "Bot",
    "tenantId": "660e8400-e29b-41d4-a716-446655440001"
  },
  "tenant": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Zunga Corp"
  }
}

2.2. टोकन हैंडलिंग नियम

Access token (token) — एक JWT जो 1 घंटे तक चलता है। हर रिक्वेस्ट के साथ भेजें: Authorization: Bearer <token>।
Refresh token (refreshToken) — एक रैंडम स्ट्रिंग जो 7 दिन तक चलती है। इससे नया token pair प्राप्त करें।
हर /api/auth/refresh पर सर्वर refresh token को रोटेट करता है: पुराना हटा दिया जाता है और नया जारी किया जाता है। दोनों नई वैल्यू सुरक्षित रखें।
समाप्त access token वाली रिक्वेस्ट 401 लौटाती है। उस स्थिति में, refresh करें और मूल रिक्वेस्ट दोबारा भेजें — फिर से लॉगिन न करें।

2.3. बेस सेटिंग्स

text

CRM_BASE_URL=https://crm.example.com

नीचे दिए गए सभी उदाहरण इन हेडर को मानते हैं:

http

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

3. Paged API नियम

GET /api/*/paged रूप के सभी लिस्ट endpoint एक ही नियम साझा करते हैं:

पैरामीटर	प्रकार	डिफ़ॉल्ट	विवरण
`page`	integer	`0`	पेज नंबर, शून्य-आधारित
`size`	integer	प्रति endpoint	पेज साइज़
`sort`	string	`createdAt,desc`	`field,direction` प्रारूप में सॉर्टिंग। दिशा: `asc` या `desc`

Paged रिस्पॉन्स का आकार

json

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

तिथि फ़िल्टरिंग

रेंज के लिए fieldFrom / fieldTo पैरामीटर उपयोग करें (ISO 8601):

text

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

सॉर्टिंग

हमेशा ?sort=field,direction:

text

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

कुछ फ़िल्टर फ़ील्ड के लिए समर्पित रेंज पैरामीटर हैं (जैसे dealAmountFrom/dealAmountTo)।

फ़िल्टरिंग का अर्थ

सारी फ़िल्टरिंग और सॉर्टिंग सर्वर-साइड होती है (सब कुछ डाउनलोड करके क्लाइंट-साइड फ़िल्टर करने की ज़रूरत नहीं)।
कई फ़िल्टर AND से जोड़े जाते हैं।
टेक्स्ट (सबस्ट्रिंग) फ़िल्टर केस-असंवेदनशील खोज (ILIKE) का उपयोग करते हैं।
सार्वभौमिक search फ़िल्टर कई फ़ील्ड में OR के साथ खोजता है।

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 के लिए उपयोग होता है। एक array लौटाता है:

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": "Website inquiry: consultation",
    "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`	string	नहीं	संदेश / पूछताछ टेक्स्ट
`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": "Website inquiry: consultation",
  "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. Paged रीड (`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	exact	स्टेटस से फ़िल्टर करें
`leadSourceId`	uuid	exact	लीड स्रोत से फ़िल्टर करें
`quality`	enum	exact	`HOT`, `WARM`, `COOL`, `COLD`
`message`	string	ILIKE	संदेश में सबस्ट्रिंग
`search`	string	ILIKE (OR)	संदेश, संपर्क, ईमेल, फ़ोन में खोज
`contactEmail`	string	ILIKE	संपर्क ईमेल से
`contactPhone`	string	ILIKE	संपर्क फ़ोन से
`company`	string	ILIKE	कंपनी नाम से
`clientId`	uuid	exact	क्लाइंट ID से
`createdAtFrom` / `createdAtTo`	date-time	range	निर्माण तिथि से
`updatedAtFrom` / `updatedAtTo`	date-time	range	अपडेट तिथि से
`createdBy`	uuid	exact	लीड लेखक से

संबंधित डील के लिए भी फ़िल्टर हैं: dealStatusId, dealStageId, dealAmountFrom/dealAmountTo, dealProbabilityFrom/dealProbabilityTo।

सॉर्टिंग: createdAt, updatedAt, message, quality, स्टेटस/स्रोत और अन्य (field,direction प्रारूप)।

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 endpoint उपयोग करें। यह लीड का array स्वीकार करता है, एक इम्पोर्ट-इतिहास रिकॉर्ड बनाता है, और पूरे इम्पोर्ट को रोलबैक करने की सुविधा देता है।

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": "Inquiry #1",
        "ownerId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
        "authorId": "7a786a66-3617-48c1-921d-97f4aaefcd35",
        "quality": "WARM"
      },
      {
        "message": "Inquiry #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 — छोड़ी गई पंक्तियों का array, 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`)

वेबसाइट फ़ॉर्म के लिए एक संयुक्त endpoint है जो एक ही रिक्वेस्ट में संपर्क, उसका प्राथमिक फ़ोन और ईमेल, लीड, संपर्क–लीड लिंक और मार्केटिंग इवेंट को एटॉमिक रूप से बनाता है — externalId के माध्यम से idempotency के साथ।

समर्पित गाइड देखें: 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`	string	सभी	प्रदर्शन नाम (आवश्यक)
`firstName` / `lastName`	string	INDIVIDUAL	पहला/अंतिम नाम
`taxId`	string	COMPANY	टैक्स ID (INN)
`regNumber`	string	COMPANY	पंजीकरण संख्या
`legalAddress`	string	COMPANY	कानूनी पता
`phone` / `email` / `website`	string	सभी	संपर्क
`country`	string	सभी	ISO देश कोड
`ownerId`	uuid	सभी	ज़िम्मेदार यूज़र
`authorId`	uuid	सभी	लेखक
`developingManagerIds`	uuid[]	सभी	विकास मैनेजर

6.2. Paged क्लाइंट रीड (`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 (नाम/taxId/फ़ोन से), createdAtFrom/createdAtTo, createdBy, developingManagerId।

6.3. डुप्लिकेट जाँच (`GET /api/clients/duplicates`)

क्लाइंट बनाने से पहले जाँचें कि समान क्लाइंट पहले से मौजूद है या नहीं:

bash

# tax 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": "Ivan",
    "lastName": "Petrov",
    "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. Paged संपर्क रीड (`GET /api/contacts/paged`)

bash

curl "$CRM_BASE_URL/api/contacts/paged?page=0&size=20&search=Petrov&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": "Server hardware delivery",
    "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`	string	हाँ	डील का नाम
`clientId`	uuid	हाँ	क्लाइंट ID
`statusId`	uuid	नहीं	स्टेटस (स्टेज स्टेटस)
`stageId`	uuid	नहीं	सेल्स स्टेज
`probability`	integer	नहीं	प्रायिकता 0-100
`amount`	number	नहीं	राशि
`plannedAmount`	number	नहीं	नियोजित राशि
`discountPercent`	integer	नहीं	छूट 0-100
`startDate` / `expectedCloseDate`	date-time	नहीं	तिथियाँ
`ownerId`	uuid	नहीं	ओनर
`leadId`	uuid	नहीं	संबंधित लीड
`contactId`	uuid	नहीं	संबंधित संपर्क
`productIds`	uuid[]	नहीं	प्रोडक्ट (सरलीकृत प्रारूप)
`dealProducts`	array	नहीं	डील लाइन आइटम (पूर्ण प्रारूप)
`dealParties`	array	नहीं	डील पक्ष

7.2. Paged डील रीड (`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/टेनेंट के लिए समान externalId के साथ दोबारा भेजने पर duplicate: true लौटता है — यह त्रुटि नहीं है।
रीट्राई पर नया externalId न बनाएँ।
metadata में व्यक्तिगत रूप से पहचान योग्य जानकारी (ईमेल, फ़ोन, नाम, संदेश टेक्स्ट) न रखें। केवल तकनीकी विशेषताएँ जैसे फ़ॉर्म नाम या पेज प्रकार।

विवरण के लिए देखें site-leads-integration-guide.md।

9. डेटा एक्सपोर्ट (NDJSON)

एक्सपोर्ट endpoint टेनेंट के सभी रिकॉर्ड NDJSON प्रारूप में लौटाते हैं (प्रति पंक्ति एक JSON ऑब्जेक्ट, \n-सेपरेटेड)।

Endpoint	विवरण
`GET /api/export/leads`	सभी टेनेंट लीड
`GET /api/export/clients`	सभी टेनेंट क्लाइंट
`GET /api/export/contacts`	सभी टेनेंट संपर्क

bash

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

उदाहरण रिस्पॉन्स (लाइन स्ट्रीम):

text

{"id":"550e8400-e29b-41d4-a716-446655440001","message":"Website inquiry","quality":"WARM","statusName":"New","createdAt":"2026-08-20T10:00:00+03:00","ownerName":"Ivan Ivanov","clientName":"Romashka LLC","contactFirstName":"Petr","contactLastName":"Petrov","leadSourceName":"Paid search"}
{"id":"550e8400-e29b-41d4-a716-446655440002","message":"Phone call","quality":"COOL","statusName":"In progress","createdAt":"2026-08-19T09:00:00+03:00","ownerName":"Maria Smirnova","clientName":null}

महत्वपूर्ण: NDJSON एक वैध JSON array नहीं है। रिस्पॉन्स को 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\": \"Ivan\",
    \"lastName\": \"Petrov\",
    \"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\": \"Website inquiry\",
    \"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\": \"Consultation for Ivan Petrov\",
    \"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. Idempotency और त्रुटि हैंडलिंग

स्थिर पहचानकर्ता: प्रत्येक सबमिशन के लिए अपना externalId (UUID या requestId) बनाएँ। समान externalId दोबारा भेजने पर डुप्लिकेट नहीं बनना चाहिए (मार्केटिंग इवेंट के लिए यह सर्वर द्वारा संभाला जाता है — duplicate: true)।
समान पहचानकर्ता के साथ रीट्राई: नेटवर्क त्रुटि पर, समान externalId के साथ रीट्राई करें; नया न बनाएँ।
आँख बंद करके डुप्लिकेट न करें: यदि create रिक्वेस्ट टाइमआउट हो जाए, तो पहले परिणाम सत्यापित करें (अपने requestId से या बनाई गई इकाई खोजकर) बजाय नई बनाने के।
400: अमान्य payload — बिना बदलाव रीट्राई करने से मदद नहीं होगी; डेटा ठीक करें।
401: समाप्त access token — /api/auth/refresh कॉल करें और रिक्वेस्ट दोबारा भेजें।
403: अनुमति नहीं — भूमिका और टेनेंट जाँचें।
5xx/timeout: अस्थायी त्रुटि — समान externalId के साथ रीट्राई करें (लीड के लिए, एक क्यू उपयोग करें)।

12. क्विक स्टार्ट

POST /api/auth/login के माध्यम से ऑथेंटिकेट करें; token और refreshToken संग्रहीत करें।
हर रिक्वेस्ट में Authorization: Bearer <token> जोड़ें। 401 पर, /api/auth/refresh से रीफ़्रेश करें।
रेफ़रेंस (users/statuses/stages/lead-sources) एक बार प्राप्त करें और UUID कैश करें।
इकाइयाँ तार्किक क्रम में बनाएँ: क्लाइंट → संपर्क → लीड → डील।
रीड के लिए सर्वर-साइड फ़िल्टरिंग और सॉर्टिंग के साथ paged endpoint उपयोग करें।
एक्सपोर्ट के लिए, NDJSON endpoint उपयोग करें और स्ट्रीम को पंक्ति दर पंक्ति पढ़ें।
बल्क इनजेशन के लिए, रोलबैक समर्थन के साथ batch endpoint उपयोग करें (/api/leads/import/batch, /api/clients/import/batch)।
स्थिर externalId के साथ POST /api/dashboard/marketing/events के माध्यम से मार्केटिंग एट्रिब्यूशन भेजें।
मार्केटिंग-इवेंट metadata में PII कभी संग्रहीत या पास न करें।
विस्तृत प्रति-API दस्तावेज़ देखें: site-leads-integration-guide.md।

ReactiveCRM इंटीग्रेशन गाइड

1. इंटीग्रेशन अवलोकन

2. ऑथेंटिकेशन

2.1. टोकन प्राप्त करना

2.2. टोकन हैंडलिंग नियम

2.3. बेस सेटिंग्स

3. Paged API नियम

Paged रिस्पॉन्स का आकार

तिथि फ़िल्टरिंग

सॉर्टिंग

फ़िल्टरिंग का अर्थ

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. Paged रीड (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. Paged क्लाइंट रीड (GET /api/clients/paged)

6.3. डुप्लिकेट जाँच (GET /api/clients/duplicates)

6.4. संपर्क बनाएँ (POST /api/contacts/create)

6.5. Paged संपर्क रीड (GET /api/contacts/paged)

7. डील

7.1. डील बनाएँ (POST /api/deals/create)

7.2. Paged डील रीड (GET /api/deals/paged)

8. मार्केटिंग इवेंट (एट्रिब्यूशन)

POST /api/dashboard/marketing/events

9. डेटा एक्सपोर्ट (NDJSON)

10. एंड-टू-एंड इंटीग्रेशन उदाहरण

11. Idempotency और त्रुटि हैंडलिंग

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. Paged रीड (`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. Paged क्लाइंट रीड (`GET /api/clients/paged`)

6.3. डुप्लिकेट जाँच (`GET /api/clients/duplicates`)

6.4. संपर्क बनाएँ (`POST /api/contacts/create`)

6.5. Paged संपर्क रीड (`GET /api/contacts/paged`)

7.1. डील बनाएँ (`POST /api/deals/create`)

7.2. Paged डील रीड (`GET /api/deals/paged`)

`POST /api/dashboard/marketing/events`