საჯარო API და ვებჰუკები

REST API საშუალებას აძლევს თქვენს CRM-ს, საიტის ბექენდს ან საკუთარ ბოტს იმუშაოს cenaly.com-ის ლიდებთან და დიალოგებთან ისევე, როგორც ამას პანელი აკეთებს: წაიკითხოს ბარათები, შეცვალოს თვისებები, გაგზავნოს მოვლენები, უპასუხოს დიალოგებში. ვებჰუკები, პირიქით, თავად აცნობებენ თქვენს სერვერს ახალი ლიდების, მოვლენებისა და შეტყობინებების შესახებ.

რა არის საჭირო გაშვებისთვის#

ნაბიჯი 1. გასაღები და უფლებები#

1. გახსენით ინტეგრაციები და გვერდის თავში დააჭირეთ API და ვებჰუკები.
2. ჩანართზე გასაღებები დააჭირეთ გასაღების შექმნა, შეიყვანეთ სახელი („CRM“, „საიტის ბექენდი“, „Telegram-ბოტი“).
3. აირჩიეთ უფლებების ნაკრები ან მონიშნეთ უფლებები სათითაოდ, რამდენიმე ფილიალის შემთხვევაში — რომელ ფილიალებზეა გასაღები დაშვებული, და ვადა.
4. დააკოპირეთ საიდუმლო cnk_…. ის მხოლოდ ერთხელ ჩანს: ჩვენ მხოლოდ მისი ანაბეჭდი (SHA-256) ინახება.

ნაკრებები: CRM / ბექენდი (ლიდები, თვისებები, მოვლენები, დიალოგებისა და სეგმენტების კითხვა), საკუთარი ბოტი (კითხულობს ლიდებს, პასუხობს დიალოგებში, წერს ლიდებს), მხოლოდ კითხვა, ყველაფერი.

• უფლებები ცვლის გასაღების უფლებებსა და ფილიალებს მფრინავად — ინტეგრაცია აგრძელებს მუშაობას.
• ხელახლა გაცემა გასცემს ახალ საიდუმლოს; ძველი დაუყოვნებლივ წყვეტს მუშაობას, უფლებები და ჟურნალი რჩება.
• გაუქმება — დაუყოვნებლივ და სამუდამოდ, შემდეგი მოთხოვნა მიიღებს 401-ს.

გასაღები გადაეცემა Authorization: Bearer cnk_… სათაურით (ან X-Api-Key: cnk_…). შეინახეთ ის მხოლოდ სერვერზე — არა ბრაუზერში და არა მობილურ აპლიკაციაში.

ნაბიჯი 2. პირველი მოთხოვნები#

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"

პასუხი — ყოველთვის კონვერტი:

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

შემდეგი გვერდი — იგივე მოთხოვნა cursor=<meta.nextCursor>-ით; თუ nextCursor არ არის — გვერდები აღარ არის. შეცდომა — {"meta": {...}, "error": {"code": "…"}}.

ფილიალი. თუ გასაღებს ერთი ფილიალი აქვს ხელმისაწვდომი, მისი მითითება საჭირო არ არის. თუ რამდენიმე — დაამატეთ location=<ფილიალის id> (სია — GET /v1/locations), წინააღმდეგ შემთხვევაში პასუხი იქნება 400 location_required.

თვისებები და მოვლენები თქვენი user_id-ით. სულაც არ არის აუცილებელი ჩვენი ლიდის id-ის შენახვა: დაამატეთ ?by=user_id და მისამართი გახდება თქვენი მომხმარებლის იდენტიფიკატორი. თუ ასეთი user_id-ით ლიდი ჯერ არ არსებობს — ჩვენ შევქმნით.

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

ჩაწერა იმავე რიგში გადის, როგორც პანელიდან ცვლილებები: ცვლილებები წამებში გამოიყენება, ხოლო user_id-ით ჩაწერაზე პასუხია 202 pending-ით. ლიდის ბარათში ცვლილების ავტორი ჩანს როგორც „API: <გასაღების სახელი>“.

მეთოდები#

თითოეული მეთოდის ველები, მაგალითები და შეცდომის კოდები — ცნობარში.

ნაბიჯი 3. ვებჰუკები#

ვებჰუკები ფილიალზე იწყობა: ჩატი → პარამეტრები → ვებჰუკები — მისამართი https, მოვლენები და ხელმოწერის საიდუმლო. დიალოგის მოვლენებს (ახალი დიალოგი, ახალი შეტყობინება, სტატუსი, შეფასება, ნიშნები) დაემატა ლიდის მოვლენები:

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

ლიდის სახელი, ელფოსტა და ტელეფონი სხეულში მოხვდება მხოლოდ მაშინ, თუ ვებჰუკს ჩართული აქვს ნიშანი „სტუმრის კონტაქტების გადაცემა“. ხელმოწერის შემოწმება — სხეულის HMAC-SHA256 ვებჰუკის საიდუმლოთი:

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

უპასუხეთ 2xx 5 წამში — წინააღმდეგ შემთხვევაში მიწოდება განმეორდება; წარუმატებლობების გრძელი სერიის შემდეგ ვებჰუკი ითიშება და ეს პარამეტრებში ჩანს. დუბლიკატები გაფილტრეთ deliveryId-ით.

შეზღუდვები#

• 60 მოთხოვნა წუთში გასაღებზე; ზედმეტზე — 429 Retry-After თავსართით. ნაშთი — X-RateLimit-*-ში.
• გვერდზე 200-მდე ჩანაწერი (ნაგულისხმევად 50), პაკეტში 100-მდე მოვლენა, მოთხოვნაზე 250-მდე ოპერაცია თვისებებთან, ერთდროულად 30-მდე ტეგი.
• ანგარიშზე 20-მდე აქტიური გასაღები.
• გასაღების გამოძახებების ჟურნალი ინახება 30 დღე: დრო, მეთოდი, ბილიკის შაბლონი (id-ისა და სხეულის გარეშე), პასუხის კოდი, ხანგრძლივობა.
• API-ის მეშვეობით გაგზავნილი მოვლენები ხვდება ლიდის ბარათში (ლენტა, შეჯამება, სეგმენტები), მაგრამ არა ვიზიტების ანალიტიკის ნედლ ჟურნალში.
• ლიდს მიწერა შესაძლებელია მხოლოდ არსებულ დიალოგში: დიალოგი არ არის — პასუხი 409 no_conversation.

ხარვეზების აღმოფხვრა#

ყოველი მოთხოვნა ჩანს ჩანართზე გამოძახებების ჟურნალი — პასუხის კოდითა და გასაღების სახელით.

ხშირი კითხვები#

შეიძლება API-ის გამოძახება ბრაუზერიდან? არა: გასაღები წვდომას იძლევა ფილიალის ყველა ლიდზე. გამოიძახეთ API საკუთარი სერვერიდან.

რით განსხვავდება user_id ლიდის id-ისგან? ლიდის id — ჩვენი ბარათის იდენტიფიკატორი. user_id — თქვენი მომხმარებლის იდენტიფიკატორი (ნომერი CRM-ში, ანგარიშის id საიტზე); ?by=user_id-ით ბარათის მიმართვა შესაძლებელია მისით.

რა მოხდება მოვლენის ხელახლა გაგზავნისას? მოვლენა იმავე id-ით ჩაითვლება ერთხელ — შეგიძლიათ თამამად გაიმეოროთ მოთხოვნა ქსელური შეცდომისას.

საჭიროა ცალკე გასაღები თითოეული ფილიალისთვის? არა: ერთ გასაღებს შეუძლია რამდენიმე ფილიალთან მუშაობა, ფილიალი ირჩევა პარამეტრით location.

დაკავშირებული განყოფილებები#

• ჩატი სტუმრებთან — დიალოგები, ლიდები და ვებჰუკების პარამეტრები
• განაცხადები — ერთიანი შემომავალი ნაკადი
• საკუთარი სატელეფონო სადგურის API და MCP — ტელეფონიის ცალკე API
• ინტეგრაციები