Հանրային API և վեբհուքեր

REST API-ն թույլ է տալիս ձեր CRM-ին, կայքի բեքենդին կամ սեփական բոտին աշխատել cenaly.com-ի լիդերի և երկխոսությունների հետ այնպես, ինչպես դա անում է պանելը՝ կարդալ քարտերը, փոխել հատկությունները, ուղարկել իրադարձություններ, պատասխանել երկխոսություններում։ Վեբհուքերը, ընդհակառակը, իրենք են տեղեկացնում ձեր սերվերին նոր լիդերի, իրադարձությունների և հաղորդագրությունների մասին։

Ինչ է անհրաժեշտ մեկնարկի համար#

Քայլ 1. Բանալին և իրավունքները#

1. Բացեք Ինտեգրումներ և էջի վերևում սեղմեք API և վեբհուքեր։
2. Բանալիներ ներդիրում սեղմեք Ստեղծել բանալի, մուտքագրեք անվանումը («CRM», «Կայքի բեքենդ», «Telegram-բոտ»)։
3. Ընտրեք իրավունքների հավաքածուն կամ նշեք իրավունքները մեկ առ մեկ, մի քանի մասնաճյուղերի դեպքում՝ որ մասնաճյուղերին է բանալին թույլատրված, և ժամկետը։
4. Պատճենեք cnk_… գաղտնիքը։ Այն ցուցադրվում է մեկ անգամ․ մեզ մոտ պահվում է միայն դրա մատնահետքը (SHA-256)։

Հավաքածուներ՝ CRM / բեքենդ (լիդեր, հատկություններ, իրադարձություններ, երկխոսությունների և սեգմենտների ընթերցում), Սեփական բոտ (կարդում է լիդերին, պատասխանում է երկխոսություններում, գրում է լիդերին), Միայն ընթերցում, Ամեն ինչ։

• Իրավունքները փոխում են բանալու իրավունքներն ու մասնաճյուղերը անմիջապես — ինտեգրումը շարունակում է աշխատել։
• Վերաթողարկել-ը տալիս է նոր գաղտնիք․ հինն անմիջապես դադարում է աշխատել, իրավունքներն ու մատյանը մնում են։
• Հետ կանչել — անմիջապես և ընդմիշտ, հաջորդ հարցումը կստանա 401։

Բանալին փոխանցվում է Authorization: Bearer cnk_… վերնագրով (կամ X-Api-Key: cnk_…)։ Պահեք այն միայն սերվերում — ոչ բրաուզերում և ոչ բջջային հավելվածում։

Քայլ 2. Առաջին հարցումները#

KEY=cnk_ваш_ключ
API=https://api.cenaly.com/public-api/v1

# что умеет ключ: права, точки, лимит
curl -H "Authorization: Bearer $KEY" "$API/me"

# лиды, свежие сверху (20 на страницу)
curl -H "Authorization: Bearer $KEY" "$API/contacts?limit=20"

# поиск по имени, почте или телефону
curl -H "Authorization: Bearer $KEY" "$API/contacts?q=anna"

Պատասխանը միշտ ծրար է՝

{
  "meta": { "status": 200, "requestId": "…", "nextCursor": "WyIyMDI2LTEwLTA0…" },
  "data": { "total": 128, "contacts": [ { "id": "…", "status": "lead", "name": "Анна", "updatedAt": "2026-10-04T09:12:00Z" } ] }
}

Հաջորդ էջը՝ նույն հարցումը cursor=<meta.nextCursor>-ով․ nextCursor չկա — էջերն այլևս չկան։ Սխալ՝ {"meta": {...}, "error": {"code": "…"}}։

Մասնաճյուղ։ Եթե բանալուն հասանելի է մեկ մասնաճյուղ, այն նշել պետք չէ։ Եթե մի քանիսը՝ ավելացրեք location=<մասնաճյուղի id> (ցանկը՝ GET /v1/locations), հակառակ դեպքում պատասխանը կլինի 400 location_required։

Հատկություններ և իրադարձություններ ձեր user_id-ով։ Պարտադիր չէ պահել լիդի մեր id-ն․ ավելացրեք ?by=user_id, և հասցեն կդառնա ձեր օգտատիրոջ նույնացուցիչը։ Այդպիսի user_id-ով լիդ դեռ չկա — մենք կստեղծենք այն։

# свойства: операции update_or_create, set_once, add, delete, append, union, exclude
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"ops":[{"op":"update_or_create","key":"$email","value":"anna@example.com"},
              {"op":"add","key":"orders","value":1},
              {"op":"union","key":"interests","value":"yoga"}]}' \
  "$API/contacts/u-1001/props?by=user_id"

# события пачкой (до 100), повтор с тем же id засчитывается один раз
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"events":[{"id":"ord-5531","userId":"u-1001","name":"order_paid","props":{"sum":45,"currency":"GEL"}}]}' \
  "$API/events"

# ответ в диалоге и смена статуса
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"text":"Здравствуйте! Заказ передан курьеру."}' "$API/conversations/<id>/reply"
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"status":"resolved"}' "$API/conversations/<id>/status"

Գրառումն անցնում է նույն հերթով, ինչ պանելից արված փոփոխությունները․ փոփոխությունները կիրառվում են վայրկյանների ընթացքում, իսկ user_id-ով գրառման պատասխանը՝ 202՝ pending-ով։ Լիդի քարտում փոփոխության հեղինակը երևում է որպես «API: <բանալու անվանումը>»։

Մեթոդներ#

Յուրաքանչյուր մեթոդի դաշտերը, օրինակներն ու սխալի կոդերը՝ տեղեկատուում։

Քայլ 3. Վեբհուքեր#

Վեբհուքերը կարգավորվում են մասնաճյուղի մակարդակով՝ Չատ → Կարգավորումներ → Վեբհուքեր — https հասցե, իրադարձություններ և ստորագրության գաղտնիք։ Երկխոսության իրադարձություններին (նոր երկխոսություն, նոր հաղորդագրություն, կարգավիճակ, գնահատական, պիտակներ) ավելացան լիդի իրադարձությունները.

{
  "event": "lead.event_tracked",
  "deliveryId": "WD…",
  "at": "2026-10-04T09:12:03Z",
  "webhookId": "…",
  "locationId": "…",
  "contact": { "id": "…", "status": "user", "userId": "u-1001", "props": { "orders": 3 }, "tags": ["vip"] },
  "leadEvent": { "name": "order_paid", "at": "2026-10-04T09:12:00Z", "props": { "sum": 45 } }
}

Լիդի անունը, էլ. փոստը և հեռախոսը հայտնվում են մարմնում միայն այն դեպքում, երբ վեբհուքի մոտ միացված է «Փոխանցել հյուրի կոնտակտները» նշիչը։ Ստորագրության ստուգումը՝ մարմնի HMAC-SHA256 վեբհուքի գաղտնիքով.

# заголовок X-Meni-Signature: sha256=<hex>
echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET"

Պատասխանեք 2xx 5 վայրկյանի ընթացքում — հակառակ դեպքում առաքումը կկրկնվի. անհաջողությունների երկար շարքից հետո վեբհուքն անջատվում է, և դա երևում է կարգավորումներում։ Կրկնօրինակները զտեք deliveryId-ով։

Սահմանափակումներ#

• 60 հարցում մեկ րոպեում մեկ բանալու համար. գերազանցելու դեպքում՝ 429՝ Retry-After վերնագրով։ Մնացորդը՝ X-RateLimit-*-ում։
• Մինչև 200 գրառում մեկ էջում (լռելյայն՝ 50), մինչև 100 իրադարձություն մեկ փաթեթում, մինչև 250 գործողություն հատկությունների հետ մեկ հարցման համար, մինչև 30 պիտակ միաժամանակ։
• Մինչև 20 ակտիվ բանալի մեկ հաշվի համար։
• Բանալու կանչերի մատյանը պահվում է 30 օր. ժամանակը, մեթոդը, ուղու ձևանմուշը (առանց id-ի և մարմնի), պատասխանի կոդը, տևողությունը։
• API-ի միջոցով ուղարկված իրադարձությունները ընկնում են լիդի քարտի մեջ (հոսք, ամփոփում, սեգմենտներ), բայց ոչ այցելությունների վերլուծության չմշակված մատյանի մեջ։
• Լիդին կարելի է գրել միայն գոյություն ունեցող երկխոսության մեջ. երկխոսություն չկա՝ պատասխանը 409 no_conversation է։

Խնդիրների լուծում#

Յուրաքանչյուր հարցում երևում է Կանչերի մատյան ներդիրում՝ պատասխանի կոդով և բանալու անվանմամբ։

Հաճախ տրվող հարցեր#

Կարելի՞ է API-ն կանչել բրաուզերից։ Ոչ. բանալին հասանելիություն է տալիս մասնաճյուղի բոլոր լիդերին։ Կանչեք API-ն ձեր սերվերից։

Ինչո՞վ է user_id-ն տարբերվում լիդի id-ից։ Լիդի id-ն մեր քարտի նույնացուցիչն է։ user_id-ն ձեր օգտատիրոջ նույնացուցիչն է (համարը CRM-ում, հաշվի id-ն կայքում). ?by=user_id-ով քարտին կարելի է դիմել դրանով։

Ի՞նչ կլինի իրադարձությունը կրկին ուղարկելիս։ Նույն id-ով իրադարձությունը հաշվվում է մեկ անգամ — ցանցային սխալի դեպքում կարող եք վստահորեն կրկնել հարցումը։

Առանձին բանալի՞ է պետք յուրաքանչյուր մասնաճյուղի համար։ Ոչ. մեկ բանալին կարող է աշխատել մի քանի մասնաճյուղերի հետ, մասնաճյուղն ընտրվում է location պարամետրով։

Առնչվող բաժիններ#

• Չատ հյուրերի հետ — երկխոսություններ, լիդեր և վեբհուքերի կարգավորումներ
• Հայտեր — միասնական մուտքային հոսք
• Ձեր ԱԿՀ-ի API-ն և MCP-ն — հեռախոսակապի առանձին API
• Ինտեգրումներ