Ommaviy API va vebhuklar

REST API sizning CRM, sayt backend yoki shaxsiy botingizga cenaly.com lidlari va suhbatlari bilan xuddi panel kabi ishlash imkonini beradi: kartochkalarni o'qish, xususiyatlarni o'zgartirish, hodisalarni yuborish, suhbatlarda javob berish. Vebhuklar esa aksincha, yangi lidlar, hodisalar va xabarlar haqida sizning serveringizga o'zi xabar beradi.

Ishga tushirish uchun nima kerak#

1-qadam. Kalit va huquqlar#

1. Integratsiyalar ni oching va sahifa sarlavhasidagi API va vebhuklar tugmasini bosing.
2. Kalitlar yorlig'ida Kalit yaratish tugmasini bosing, nom kiriting ("CRM", "Sayt backend", "Telegram-bot").
3. Huquqlar to'plamini tanlang yoki huquqlarni birma-bir belgilang, bir nechta filial bo'lsa — kalit qaysi filiallarga ruxsat etilganini va muddatni ko'rsating.
4. cnk_… maxfiy kalitini nusxalab oling. U faqat bir marta ko'rsatiladi: bizda faqat uning izi (SHA-256) saqlanadi.

To'plamlar: CRM / backend (lidlar, xususiyatlar, hodisalar, suhbatlar va segmentlarni o'qish), Shaxsiy bot (lidlarni o'qiydi, suhbatlarda javob beradi, lidlarga yozadi), Faqat o'qish, Hammasi.

• Huquqlar kalitning huquqlari va filiallarini darhol o'zgartiradi — integratsiya ishlashda davom etadi.
• Qayta chiqarish yangi maxfiy kalit beradi; eskisi darhol ishlashdan to'xtaydi, huquqlar va jurnal saqlanib qoladi.
• Bekor qilish — darhol va butunlay, keyingi so'rov 401 oladi.

Kalit Authorization: Bearer cnk_… sarlavhasi (yoki X-Api-Key: cnk_…) orqali uzatiladi. Uni faqat serverda saqlang — brauzerda ham, mobil ilovada ham emas.

2-qadam. Birinchi so'rovlar#

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"

Javob — har doim konvert:

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

Keyingi sahifa — cursor=<meta.nextCursor> bilan xuddi shu so'rov; nextCursor bo'lmasa — boshqa sahifa yo'q. Xato — {"meta": {...}, "error": {"code": "…"}}.

Filial. Agar kalitga bitta filial ruxsat etilgan bo'lsa, uni ko'rsatish shart emas. Agar bir nechta bo'lsa — location=<filial id> qo'shing (ro'yxat — GET /v1/locations), aks holda javob 400 location_required.

Xususiyatlar va hodisalar sizning user_id bo'yicha. Bizning lid id sini saqlash shart emas: ?by=user_id qo'shing, manzil sizning foydalanuvchi identifikatoringizga aylanadi. Bunday user_id bilan lid hali yo'q bo'lsa — biz uni yaratamiz.

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

Yozuv paneldagi tahrirlar bilan bir xil navbat orqali amalga oshiriladi: o'zgarishlar bir necha soniyada qo'llanadi, user_id bo'yicha yozuvga javob esa pending bilan 202 bo'ladi. Lid kartochkasida tahrir muallifi "API: " sifatida ko'rinadi.

Metodlar#

Har bir metodning maydonlari, misollari va xato kodlari — maʼlumotnomada.

3-qadam. Vebhuklar#

Vebhuklar filialda sozlanadi: Chat → Sozlamalar → Vebhuklar — https manzil, voqealar va imzo siri. Suhbat voqealariga (yangi suhbat, yangi xabar, holat, baho, belgilar) lid voqealari qoʻshildi:

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

Lidning ismi, pochtasi va telefoni tanaga faqat vebhukda «Mehmon kontaktlarini uzatish» belgisi yoqilgan boʻlsa tushadi. Imzoni tekshirish — tanani vebhuk siri bilan HMAC-SHA256:

# sarlavha X-Meni-Signature: sha256=<hex>
echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET"

5 soniya ichida 2xx bilan javob bering — aks holda yetkazish takrorlanadi; uzoq muvaffaqiyatsizliklar seriyasidan soʻng vebhuk oʻchiriladi va bu sozlamalarda koʻrinadi. Dublikatlarni deliveryId boʻyicha ajratib oling.

Cheklovlar#

• Kalit uchun daqiqada 60 soʻrov; ortiqchasi — Retry-After sarlavhasi bilan 429. Qoldiq — X-RateLimit-*da.
• Sahifada 200 tagacha yozuv (sukut boʻyicha 50), paketda 100 tagacha voqea, soʻrovda 250 tagacha xossa amali, bir martada 30 tagacha teg.
• Hisobda 20 tagacha tirik kalit.
• Kalit chaqiruvlari jurnali 30 kun saqlanadi: vaqt, metod, yoʻl shabloni (id va tanasiz), javob kodi, davomiylik.
• API orqali yuborilgan voqealar lid kartasiga tushadi (lenta, xulosa, segmentlar), lekin tashriflar analitikasining xom jurnaliga emas.
• Lidga faqat mavjud suhbatga yozish mumkin: suhbat boʻlmasa — 409 no_conversation javobi.

Muammolarni bartaraf etish#

Har bir soʻrov Chaqiruvlar jurnali varagʻida koʻrinadi — javob kodi va kalit nomi bilan.

Koʻp beriladigan savollar#

API ni brauzerdan chaqirish mumkinmi? Yoʻq: kalit filialning barcha lidlariga kirish huquqini beradi. API ni oʻz serveringizdan chaqiring.

user_id lid id sidan nimasi bilan farq qiladi? Lid id — kartaning bizning identifikatorimiz. user_id — sizning foydalanuvchi identifikatoringiz (CRM dagi raqam, saytdagi hisob id); ?by=user_id bilan kartani shu bilan murojaat qilish mumkin.

Voqea qayta yuborilsa nima boʻladi? Bir xil id li voqea bir marta hisoblanadi — tarmoq xatosida soʻrovni bemalol takrorlash mumkin.

Har bir filial uchun alohida kalit kerakmi? Yoʻq: bitta kalit bir nechta filial bilan ishlashi mumkin, filial location parametri bilan tanlanadi.

Tegishli boʻlimlar#

• Mehmonlar bilan chat — suhbatlar, lidlar va vebhuk sozlamalari
• Zayavkalar — yagona kiruvchi oqim
• Oʻz ATC ingizning API va MCP si — alohida telefoniya API si
• Integratsiyalar