Herkese açık API ve webhook’lar

REST API, CRM'nizin, sitenizin arka ucunun veya kendi botunuzun cenaly.ge'deki potansiyel müşteriler ve diyaloglarla panelin yaptığı gibi çalışmasını sağlar: kartları okumak, özellikleri değiştirmek, olay göndermek, diyaloglarda yanıtlamak. Webhook’lar ise tam tersine, yeni potansiyel müşteriler, olaylar ve mesajlar hakkında sunucunuza kendileri bildirir.

Başlamak için neler gerekir#

Adım 1. Anahtar ve yetkiler#

1. Entegrasyonlar bölümünü açın ve sayfanın üst kısmındaki API ve webhook’lar seçeneğine tıklayın.
2. Anahtarlar sekmesinde Anahtar oluştur seçeneğine tıklayın ve bir ad girin ("CRM", "Sitenin arka ucu", "Telegram botu").
3. Bir yetki grubu seçin veya yetkileri tek tek işaretleyin; birden fazla şube varsa anahtarın hangi şubelere erişebileceğini ve süresini belirtin.
4. cnk_… gizli anahtarını kopyalayın. Bu yalnızca bir kez gösterilir: bizde yalnızca parmak izi (SHA-256) saklanır.

Gruplar: CRM / arka uç (potansiyel müşteriler, özellikler, olaylar, diyalogları ve segmentleri okuma), Kendi bot (potansiyel müşterileri okur, diyaloglarda yanıtlar, potansiyel müşterilere yazar), Salt okunur, Her şey.

• İzinler anahtarın yetkilerini ve şubelerini anında değiştirir — entegrasyon çalışmaya devam eder.
• Yeniden oluştur yeni bir gizli anahtar verir; eski anahtar hemen çalışmayı durdurur, yetkiler ve günlük kalır.
• İptal et — hemen ve kalıcı olarak; sonraki istek 401 alır.

Anahtar Authorization: Bearer cnk_… başlığıyla (veya X-Api-Key: cnk_…) iletilir. Anahtarı yalnızca sunucuda saklayın — tarayıcıda veya mobil uygulamada değil.

Adım 2. İlk istekler#

KEY=cnk_ваш_ключ
API=https://api.cenaly.ge/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"

Yanıt her zaman aynı üst yapıyı kullanır:

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

Sonraki sayfa — cursor=<meta.nextCursor> ile aynı istek; nextCursor yoksa başka sayfa yoktur. Hata — {"meta": {...}, "error": {"code": "…"}}.

Şube. Anahtarın erişebildiği tek şube varsa belirtmeniz gerekmez. Birden fazla varsa location=<şube id> ekleyin (liste — GET /v1/locations), aksi halde yanıt 400 location_required olur.

Kendi user_id'nizle özellikler ve olaylar. Potansiyel müşterinin bizdeki id'sini saklamanız gerekmez: ?by=user_id ekleyin, adres olarak kendi kullanıcı tanımlayıcınız kullanılır. Bu user_id ile bir potansiyel müşteri yoksa onu biz oluştururuz.

# свойства: операции 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":1450,"currency":"RUB"}}]}' \
  "$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"

Kayıt, panelden yapılan düzenlemelerle aynı kuyruktan geçer: değişiklikler saniyeler içinde uygulanır ve user_id ile yapılan kayda yanıt pending ile birlikte 202 olur. Potansiyel müşteri kartında düzenlemeyi yapan kişi "API: <anahtar adı>" olarak görünür.

Metotlar#

Her metodun alanları, örnekleri ve hata kodları başvuru kılavuzunda.

Adım 3. Webhook’lar#

Webhook’lar şubede yapılandırılır: Sohbet → Ayarlar → Webhook’lar — https adresi, olaylar ve imza anahtarı. Görüşme olaylarına (yeni görüşme, yeni mesaj, durum, değerlendirme, etiketler) potansiyel müşteri olayları eklendi:

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

Potansiyel müşterinin adı, e-postası ve telefonu gövdeye yalnızca webhook'ta "Misafirin iletişim bilgilerini gönder" onay kutusu işaretliyse eklenir. İmza doğrulama — gövdenin webhook anahtarıyla HMAC-SHA256'sı:

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

5 saniye içinde 2xx yanıtı verin — aksi halde teslimat tekrarlanır; uzun bir başarısızlık serisinden sonra webhook kapatılır ve bu ayarlarda görünür. Yinelenenleri deliveryId ile ayıklayın.

İstek günlüğünü kontrol etme#

Entegrasyon veri alamıyorsa «Entegrasyonlar» → «API ve webhook’lar» → «İstek günlüğü» yolunu açıp anahtarı ve dönemi seçin. Son 14 gün gösterilir; hızlı kontrol için 1, 3 veya 7 gün seçebilirsiniz.

Kayıtta zaman, anahtar, HTTP metodu, kimlikleri içermeyen yol, yanıt kodu, varsa hata ve milisaniye cinsinden süre görünür. IP adresi, istek sonucunun üzerine geldiğinizde açılan ipucundadır. İstek ve yanıt gövdeleri günlüğe alınmaz; böylece kart içerikleri ve kişisel veriler teknik geçmişte tekrar saklanmaz. Günlükten çağrının sonucunu kontrol edebilirsiniz, ancak tüm veri alışverişini yeniden oluşturamazsınız.

Aradığınız kayıt yoksa seçili anahtarı kontrol edin ve dönemi 14 güne genişletin. Daha eski çağrılar bu pencerede gösterilmez.

Satışları harici bir BI sistemine aktarma#

Moskova ve Kazan'da şubeleri olan bir işletmenin yöneticisi satışları kendi analiz sistemine aktarmak istiyor. Herkese açık API anahtarı satış verilerini sağlamaz: yetkiler yalnızca potansiyel müşteriler, onların olayları, görüşmeler, mesajlar ve segmentler içindir. «Her şey» yetki grubu da sipariş ve fiş metotları eklemez.

Yeni sipariş olaylarını aktarmak için bir senaryo oluşturun:

1. «Ayarlar» → «Durum otomasyonu» → «Senaryolar (Flow)» yolunu açıp «Senaryo ekle» düğmesine basın.
2. «Ne zaman» alanında «Sipariş ödendi» olayını seçin. Diğer işler için «Sipariş oluşturuldu», «Sipariş durumu değişti» ve «Sipariş iptal edildi» olayları da vardır.
3. «O zaman» bölümüne «Webhook çağır» eylemini ekleyip entegrasyonunuzun olayları alacağı adresi belirtin. Gerekirse koşullar ekleyin.
4. «Kaydedildi» durumunu bekleyin, koşulları karşılayan bir test siparişi oluşturun ve olayın alıcı sisteminize ulaştığını kontrol edin.

Uygun bir olay gerçekleştiğinde belirttiğiniz adrese istek gönderilir. BI sistemine yüklemeyi ve alan eşleştirmesini entegrasyonu yapan kişi ayarlar; senaryo geçmişteki tüm kayıtların dışa aktarılmasının yerini tutmaz. Olay ulaşmadıysa senaryonun açık olduğunu, olayın ve tüm koşulların eşleştiğini ve alıcı adresinin doğru olduğunu kontrol edin. Herkese açık API günlüğü, anahtarlarla yapılan gelen çağrıları gösterir; bu giden webhook'un teslimini alıcı sistemde kontrol edin.

Tek seferlik analiz için sipariş listesini «CSV dışa aktar» ile indirin veya bir veri arşivi hazırlayın. Bunlar elle yapılan işlemlerdir; BI sisteminin belirli aralıklarla otomatik güncelleneceği anlamına gelmez.

Sınırlamalar#

• Anahtar başına dakikada 60 istek; üzeri — Retry-After başlıklı 429. Kalan — X-RateLimit-* içinde.
• Sayfa başına 200'e kadar kayıt (varsayılan 50), pakette 100'e kadar olay, istek başına 250'ye kadar özellik işlemi, tek seferde 30'a kadar etiket.
• Hesap başına 20'ye kadar etkin anahtar.
• «İstek günlüğü» son 14 günü gösterir. İstek ve yanıt gövdeleri saklanmaz. Metot, kimlikleri içermeyen yol, sonuç, hata, süre ve IP bilgileriyle kart içeriklerini kopyalamadan sorunu inceleyebilirsiniz.
• API üzerinden gönderilen olaylar potansiyel müşteri kartına (akış, özet, segmentler) kaydedilir, ancak ham ziyaret analitiği günlüğüne kaydedilmez.
• Potansiyel müşteriye yalnızca mevcut bir görüşmede yazılabilir: görüşme yoksa yanıt 409 no_conversation.

Sorun giderme#

Her istek İstek günlüğü sekmesinde görünür — yanıt kodu ve anahtar adıyla.

Sık sorulan sorular#

API'yi tarayıcıdan çağırabilir miyim? Hayır: anahtar şubenin tüm potansiyel müşterilerine erişim sağlar. API'yi kendi sunucunuzdan çağırın.

user_id'nin potansiyel müşteri id'sinden farkı nedir? Potansiyel müşteri id'si kartın bizdeki tanımlayıcısıdır. user_id sizin kullanıcı tanımlayıcınızdır (CRM'deki numara, sitedeki hesap id'si); ?by=user_id ile kart bu tanımlayıcıyla adreslenebilir.

Bir olay tekrar gönderilirse ne olur? Aynı id ile gelen olay bir kez sayılır — ağ hatasında isteği güvenle tekrarlayabilirsiniz.

Her şube için ayrı anahtar gerekli mi? Hayır: bir anahtar birden fazla şubeyle çalışabilir, şube location parametresiyle seçilir.

İlgili bölümler#

• Misafirlerle sohbet — görüşmeler, potansiyel müşteriler ve webhook ayarları
• Talepler — tek gelen akışı
• Kendi santralinizin API'si ve MCP'si — ayrı telefon API'si
• Entegrasyonlar