Publik API və vebhuklar

REST API sizin CRM-inizə, saytın backendinə və ya öz botunuza cenaly.com liderləri və dialoqları ilə panelin etdiyi kimi işləməyə imkan verir: kartları oxumaq, xassələri dəyişmək, hadisələr göndərmək, dialoqlarda cavab vermək. Vebhuklar isə əksinə, yeni liderlər, hadisələr və mesajlar barədə özünüzün serverinə məlumat verir.

Başlamaq üçün nə lazımdır#

Nə	Harada
Rol	hesab sahibi — açar onun adından işləyir; əməkdaşlar açarları görmür
Bölmə	aktiv çat (liderlər və dialoqlar orada yaşayır)
Açar	İnteqrasiyalar → API və vebhuklar → Açarlar → Açar yarat
API ünvanı	`https://api.cenaly.com/public-api/v1`
Metodlar üzrə məlumat kitabı	api.cenaly.com/public-api/v1/docs
OpenAPI 3.1	api.cenaly.com/public-api/v1/openapi.json

Addım 1. Açar və hüquqlar#

İnteqrasiyalar bölməsini açın və səhifənin başlığında API və vebhuklar düyməsini basın.
Açarlar sekmesinde Açar yarat düyməsini basın, ad daxil edin («CRM», «Saytın backendı», «Telegram botu»).
Hüquqlar dəstini seçin və ya hüquqları bir-bir qeyd edin, bir neçə filial olduqda — açarın hansı filiallara icazəli olduğunu və müddəti göstərin.
cnk_… sirrini kopyalayın. O yalnız bir dəfə göstərilir: bizdə yalnız onun izi (SHA-256) saxlanılır.

Hüquq	Nə verir
`contacts:read`	liderin siyahısı, axtarışı və kartı, xassələr
`contacts:write`	xassələri və teqləri dəyişmək, birləşdirmək, subyektin sorğusu ilə silmək
`events:read`	liderin hadisələr lenti
`events:write`	hadisələr göndərmək (alış, qeydiyyat, hər hansı öz hadisəniz)
`conversations:read`	dialoqlar və mesajlar
`conversations:write`	operatorun cavabı, qeyd, status, məsul şəxs, işarələr
`messages:send`	lidərə onun son dialoqunda mesaj göndərmək
`segments:read`	saxlanılmış seqmentlər və onların iştirakçıları

Dəstlər: CRM / backend (liderlər, xassələr, hadisələr, dialoqların və seqmentlərin oxunması), Öz botunuz (liderləri oxuyur, dialoqlarda cavab verir, liderlərə yazır), Yalnız oxuma, Hamısı.

Hüquqlar açarın hüquqlarını və filiallarını dərhal dəyişir — inteqrasiya işləməyə davam edir.
Yenidən burax yeni sirr verir; köhnəsi dərhal işləməyi dayandırır, hüquqlar və jurnal qalır.
Ləğv et — dərhal və birdəfəlik, növbəti sorğu 401 alacaq.

Açar Authorization: Bearer cnk_… başlığı ilə (və ya X-Api-Key: cnk_…) ötürülür. Onu yalnız serverdə saxlayın — brauzerdə və mobil tətbiqdə yox.

Addım 2. İlk sorğular#

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"

Cavab həmişə konvertdir:

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

Növbəti səhifə — cursor=<meta.nextCursor> ilə eyni sorğudur; nextCursor yoxdursa — artıq səhifə yoxdur. Xəta — {"meta": {...}, "error": {"code": "…"}}.

Filial. Əgər açar üçün bir filial əlçatandırsa, onu göstərmək lazım deyil. Bir neçədirsə — location=<filialın id-si> əlavə edin (siyahı — GET /v1/locations), əks halda cavab 400 location_required olacaq.

Xassələr və hadisələr sizin user_id ilə. Liderin bizim id-sini saxlamaq vacib deyil: ?by=user_id əlavə edin və ünvan sizin istifadəçi identifikatorunuz olacaq. Bu user_id ilə lider hələ yoxdursa — biz onu yaradacağıq.

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

Yazma panelin düzəlişləri ilə eyni növbədən keçir: dəyişikliklər saniyələr içində tətbiq olunur, user_id ilə yazma cavabı isə 202 və pending olur. Liderin kartında düzəlişin müəllifi «API: <açarın adı>» kimi görünür.

Metodlar#

Metod	Nə edir	İcazə
`GET /v1/me`, `GET /v1/locations`	açar, icazələr, filiallar	—
`GET /v1/contacts`	lidlər: `status` (`anon`, `lead`, `user`), `q`, `limit`, `cursor`	`contacts:read`
`GET /v1/contacts/{id}`	kart: xassələr, teqlər, hadisələrin xülasəsi	`contacts:read`
`POST /v1/contacts/{id}/props`	xassələr əməliyyatlarla (250-ə qədər) və ya `{"props":{…}}`	`contacts:write`
`POST` / `DELETE /v1/contacts/{id}/tags`	lidin teqləri	`contacts:write`
`POST /v1/contacts/merge`	iki kartın birləşdirilməsi: önizləmə, sonra `"apply": true`	`contacts:write`
`POST /v1/contacts/{id}/erase`	subyektin tələbi ilə silinmə (`"confirm": true`)	`contacts:write`
`GET /v1/contacts/{id}/events`	lidin hadisələr lenti	`events:read`
`POST /v1/contacts/{id}/events`, `POST /v1/events`	hadisələr (bir dəfəyə 100-ə qədər)	`events:write`
`GET /v1/contacts/{id}/conversations`	lidin dialoqları	`conversations:read`
`POST /v1/contacts/{id}/messages`	lidə onun son dialoqunda yazmaq	`messages:send`
`GET /v1/conversations`, `/{id}`, `/{id}/messages`	dialoqlar və mesajlar	`conversations:read`
`POST /v1/conversations/{id}/reply`	operatorun cavabı və ya qeyd (`"type": "note"`)	`conversations:write`
`POST /v1/conversations/{id}/status`, `/assign`, `/tags`	status, məsul şəxs, işarələr	`conversations:write`
`GET /v1/segments`, `GET /v1/segments/{id}/contacts`	seqmentlər və onların iştirakçıları	`segments:read`

Hər metodun sahələri, nümunələri və xəta kodları — məlumat kitabçasında.

Addım 3. Vebhuklar#

Vebhuklar filial üzrə qurulur: Çat → Parametrlər → Vebhuklar — https ünvanı, hadisələr və imza sirri. Dialoq hadisələrinə (yeni dialoq, yeni mesaj, status, qiymətləndirmə, işarələr) lid hadisələri də əlavə olundu:

Hadisə	Nə vaxt gəlir
`lead.created`	yeni lid yaranıb (kontakt çatda, formada qalıb və ya API vasitəsilə yaradılıb)
`lead.props_changed`	lidin xassələri dəyişib — açarların siyahısı `changedProps`-da
`lead.event_tracked`	liddə hadisə var; standart olaraq sistem hadisələri (`$…`) olmadan bütün hadisələriniz, adların siyahısı «Hansı hadisələr göndərilsin» sahəsi ilə verilir
`message.goal_reached`	lid mesajın məqsədinə çatıb (pop-ap, göndəriş)

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

Lidin adı, e-poçtu və telefonu gövdəyə yalnız vebhukda «Qonağın kontaktlarını ötür» işarəsi aktiv olduqda düşür. İmzanın yoxlanılması — gövdənin vebhuk sirri ilə HMAC-SHA256:

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

5 saniyə ərzində 2xx cavabı verin — əks halda çatdırılma təkrarlanacaq; uzun uğursuzluq seriyasından sonra vebhuk söndürülür və bu parametrlərdə görünür. Dublikatları deliveryId ilə ayırd edin.

Məhdudiyyətlər#

Açar başına dəqiqədə 60 sorğu; artıq olduqda — Retry-After başlığı ilə 429. Qalıq — X-RateLimit-*-da.
Səhifə başına 200-ə qədər qeyd (standart olaraq 50), paketdə 100-ə qədər hadisə, sorğu başına xassələrlə 250-ə qədər əməliyyat, bir dəfəyə 30-a qədər teq.
Hesab başına 20-yə qədər aktiv açar.
Açarın çağırış jurnalı 30 gün saxlanılır: vaxt, metod, yol şablonu (id və gövdə olmadan), cavab kodu, müddət.
API vasitəsilə göndərilən hadisələr lidin kartına (lent, xülasə, seqmentlər) düşür, lakin ziyarətlərin analitikasının xam jurnalına düşmür.
Lidə yalnız mövcud dialoqa yazmaq olar: dialoq yoxdursa — 409 no_conversation cavabı.

Nasazlıqların aradan qaldırılması#

Cavab	Nə deməkdir	Nə etməli
`401 api_key_missing` / `api_key_invalid`	sorğuda açar yoxdur, ya da o yanlışdır, ləğv edilib və ya müddəti bitib	başlığı yoxlayın; lazım gələrsə açarı yenidən buraxın
`403 scope_required`	açarın lazımi icazəsi yoxdur	Açarın İcazələri — icazə əlavə edin
`400 location_required`	açar üçün bir neçə filial əlçatandır	`location=<id>` əlavə edin
`404 location_not_found`	açarın filialları arasında belə filial yoxdur	`GET /v1/locations` ilə tutuşdurun
`404 not_found`	lid və ya dialoq yoxdur	öz id-ləriniz üçün `?by=user_id` istifadə edin
`429 rate_limited`	dəqiqədə 60 sorğudan çox	`Retry-After` saniyə gözləyin, hadisələri paketlərlə qruplaşdırın
`502 upstream_error`	müvəqqəti nasazlıq	sorğunu sonra təkrarlayın

Hər sorğu Çağırış jurnalı vərəqində görünür — cavab kodu və açarın adı ilə.

Tez-tez verilən suallar#

API-ni brauzerdən çağırmaq olar? Xeyr: açar filialın bütün lidlərinə giriş verir. API-ni öz serverinizdən çağırın.

user_id lidin id-dən nə ilə fərqlənir? Lidin id-si — kartın bizim identifikatorumuzdur. user_id — istifadəçinin sizin identifikatorunuzdur (CRM-də nömrə, saytda hesabın id-si); ?by=user_id ilə kartı onunla ünvanlamaq olar.

Hadisə təkrar göndərilərsə nə olacaq? Eyni id-li hadisə bir dəfə sayılır — şəbəkə xətası zamanı sorğunu cəsarətlə təkrarlaya bilərsiniz.

Hər filial üçün ayrı açar lazımdır? Xeyr: bir açar bir neçə filialla işləyə bilər, filial location parametri ilə seçilir.

Əlaqəli bölmələr#

Qonaqlarla çat — dialoqlar, lidlər və vebhuk parametrləri
Müraciətlər — vahid gələn axını
Öz ATS-nizin API və MCP-si — ayrı telefon API-si
İnteqrasiyalar