Genel API ve Web Kancaları

REST API, CRM'nizin, sitenizin arka ucunun veya kendi botunuzun cenaly.com'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. Web kancaları 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 web kancaları 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 botunuz (potansiyel müşterileri okur, diyaloglarda yanıtlar, potansiyel müşterilere yazar), Yalnızca okuma, Tümü.

• Yetkiler 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.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"

Yanıt her zaman bir zarf biçimindedir:

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

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 sırrı. 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": 45 } }
}

Potansiyel müşterinin adı, e-postası ve telefonu gövdeye yalnızca webhook'ta "Misafir kişilerini ilet" onay kutusu işaretliyse eklenir. İmza doğrulama — gövdenin webhook sırrı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.

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.
• Anahtarın çağrı günlüğü 30 gün saklanır: zaman, metot, yol şablonu (id ve gövde olmadan), yanıt kodu, süre.
• 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 Çağrı 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