Публикалық 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 бойынша жазуға жауап — pending бар 202. Лид карточкасында түзету авторы «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 сұрау; одан асса — Retry-After тақырыпшасымен 429. Қалдығы — 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-і
• Интеграциялар