API publik dhe webhooks

REST API i mundëson CRM-së tuaj, backend-it të faqes ose botit tuaj të punojë me lead-et dhe bisedat e cenaly.com njësoj si paneli: të lexojë kartat, të ndryshojë vetitë, të dërgojë ngjarje, të përgjigjet në biseda. Webhooks, përkundrazi, njoftojnë vetë serverin tuaj për lead-e të reja, ngjarje dhe mesazhe.

Çfarë nevojitet për të nisur#

Hapi 1. Çelësi dhe të drejtat#

1. Hapni Integrimet dhe klikoni API dhe webhooks në krye të faqes.
2. Në skedën Çelësat klikoni Krijo çelës, shkruani një emër ("CRM", "Backend i faqes", "Bot Telegram").
3. Zgjidhni një grup të drejtash ose shënoni të drejtat një nga një, me disa njësi — për cilat njësi lejohet çelësi, dhe afatin.
4. Kopjoni sekretin cnk_…. Ai shfaqet vetëm një herë: tek ne ruhet vetëm gjurma e tij (SHA-256).

Grupet: CRM / backend (lead-e, veti, ngjarje, lexim bisedash dhe segmentesh), Boti juaj (lexon lead-e, përgjigjet në biseda, u shkruan lead-eve), Vetëm lexim, Të gjitha.

• Të drejtat ndryshojnë të drejtat dhe njësitë e çelësit në çast — integrimi vazhdon të punojë.
• Rigjenero jep një sekret të ri; i vjetri ndalon së punuari menjëherë, të drejtat dhe regjistri mbeten.
• Anulo — menjëherë dhe përgjithmonë, kërkesa e radhës merr 401.

Çelësi dërgohet me header-in Authorization: Bearer cnk_… (ose X-Api-Key: cnk_…). Ruajeni vetëm në server — jo në shfletues dhe jo në aplikacionin mobil.

Hapi 2. Kërkesat e para#

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"

Përgjigja është gjithmonë një zarf:

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

Faqja tjetër — e njëjta kërkesë me cursor=<meta.nextCursor>; pa nextCursor — nuk ka më faqe. Gabim — {"meta": {...}, "error": {"code": "…"}}.

Njësia. Nëse çelësi ka akses vetëm në një njësi, nuk është e nevojshme ta tregoni. Nëse ka disa — shtoni location=<id e njësisë> (lista — GET /v1/locations), përndryshe përgjigja 400 location_required.

Vetitë dhe ngjarjet sipas user_id tuaj. Nuk është e detyrueshme të ruani id-në tonë të lead-it: shtoni ?by=user_id, dhe adresa do të bëhet identifikuesi juaj i përdoruesit. Nëse lead-i me atë user_id nuk ekziston ende — ne do ta krijojmë.

# свойства: операции 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"

Shkrimi kalon nëpër të njëjtën radhë si ndryshimet nga paneli: ndryshimet zbatohen brenda sekondave, dhe përgjigja për shkrimin sipas user_id — 202 me pending. Në kartën e lead-it autori i ndryshimit shfaqet si "API: <emri i çelësit>".

Metodat#

Fushat, shembujt dhe kodet e gabimeve të secilës metodë — në udhëzuesin.

Hapi 3. Webhook-et#

Webhook-et konfigurohen te njësia: Chat → Cilësimet → Webhook-et — adresa https, ngjarjet dhe sekreti i nënshkrimit. Ngjarjeve të bisedës (bisedë e re, mesazh i ri, status, vlerësim, etiketa) iu shtuan ngjarjet e lead-it:

{
  "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 } }
}

Emri, email-i dhe telefoni i lead-it përfshihen në trup vetëm nëse te webhook-u është aktivizuar kutia «Përcillni kontaktet e vizitorit». Verifikimi i nënshkrimit — HMAC-SHA256 i trupit me sekretin e webhook-ut:

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

Përgjigjuni 2xx brenda 5 sekondave — përndryshe dërgimi përsëritet; pas një serie të gjatë dështimesh webhook-u çaktivizohet dhe kjo shihet në cilësimet. Dublikatat i ndani me deliveryId.

Kufizimet#

• 60 kërkesa në minutë për çelës; mbi këtë — 429 me kokën Retry-After. Mbetja — në X-RateLimit-*.
• Deri në 200 regjistrime për faqe (si parazgjedhje 50), deri në 100 ngjarje në grup, deri në 250 operacione me vetitë për kërkesë, deri në 30 etiketa njëherësh.
• Deri në 20 çelësa aktivë për llogari.
• Regjistri i thirrjeve të çelësit ruhet 30 ditë: koha, metoda, modeli i shtegut (pa id dhe trup), kodi i përgjigjes, kohëzgjatja.
• Ngjarjet e dërguara përmes API vendosen në kartën e lead-it (rrjedha, përmbledhja, segmentet), por jo në regjistrin e papërpunuar të analitikës së vizitave.
• Lead-it mund t'i shkruani vetëm në një bisedë ekzistuese: pa bisedë — përgjigja 409 no_conversation.

Zgjidhja e problemeve#

Çdo kërkesë shihet në skedën Regjistri i thirrjeve — me kodin e përgjigjes dhe emrin e çelësit.

Pyetje të shpeshta#

A mund të thirret API nga shfletuesi? Jo: çelësi jep akses në të gjithë lead-et e njësisë. Thirreni API nga serveri juaj.

Si ndryshon user_id nga id i lead-it? id i lead-it është identifikuesi ynë i kartës. user_id është identifikuesi juaj i përdoruesit (numri në CRM, id e llogarisë në sajt); me ?by=user_id karta mund të adresohet me të.

Çfarë ndodh kur dërgohet përsëri një ngjarje? Ngjarja me të njëjtin id llogaritet një herë — mund ta përsëritni me qetësi kërkesën në rast gabimi rrjeti.

A duhet një çelës i veçantë për çdo njësi? Jo: një çelës mund të punojë me disa njësi, njësia zgjidhet me parametrin location.

Seksione të lidhura#

• Chat me vizitorët — bisedat, lead-et dhe cilësimet e webhook-ve
• Kërkesat — rrjedha e unifikuar hyrëse
• API dhe MCP i centralit tuaj telefonik — API i veçantë i telefonisë
• Integrimet