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

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

რა გჭირდებათ დასაწყებად#

ნაბიჯი 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.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"

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

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

ჩაწერა იმავე რიგით მიდის, რომლითაც პანელის შესწორებები: ცვლილებები წამებში გამოიყენება, ხოლო 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": 1450 } }
}

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

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

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

გამოძახებების ჟურნალის შემოწმება#

თუ ინტეგრაციამ მონაცემების მიღება შეწყვიტა, გახსენით „ინტეგრაციები“ → „API და ვებჰუკები“ → „გამოძახებების ჟურნალი“, აირჩიეთ გასაღები და პერიოდი. ხელმისაწვდომია ბოლო 14 დღე; სწრაფი შემოწმებისთვის შეგიძლიათ აირჩიოთ 1, 3 ან 7 დღე.

ჩანაწერში ჩანს დრო და გასაღები, HTTP მეთოდი, გზა იდენტიფიკატორების გარეშე, პასუხის კოდი, შეცდომა არსებობისას და ხანგრძლივობა მილიწამებში. IP ნაჩვენებია მინიშნებაში, მოთხოვნის შედეგზე მაუსის მიტანისას. მოთხოვნებისა და პასუხების სხეულები ჟურნალში არ არის: ასე ბარათების შიგთავსი და პერსონალური მონაცემები ტექნიკურ ისტორიაში არ დუბლირდება. ჟურნალით შეიძლება გამოძახების შედეგის შემოწმება, მაგრამ შეტყობინებების სრული გაცვლის აღდგენა შეუძლებელია.

თუ საჭირო ჩანაწერი არ არის, შეამოწმეთ არჩეული გასაღები და პერიოდი 14 დღემდე გაზარდეთ. უფრო ძველი გამოძახებები ამ ფანჯარაში არ ჩანს.

გაყიდვები გარე BI-სისტემაში მჭირდება#

ქსელის მმართველს მოსკოვი–ყაზანის გაყიდვების საკუთარ ანალიტიკაში გადაცემა სურს. საჯარო API-ის გასაღები გაყიდვებს არ გასცემს: უფლებები მხოლოდ ლიდებზე, ლიდების მოვლენებზე, დიალოგებზე, შეტყობინებებსა და სეგმენტებზე ვრცელდება. „ყველაფრის“ ნაკრებიც შეკვეთებისა და ქვითრების მეთოდებს არ ამატებს.

ახალი შეკვეთის მოვლენების გადასაცემად სცენარი მოაწყვეთ:

1. გახსენით „პარამეტრები“ → „სტატუსების ავტომატიზაცია“ → „სცენარები (Flow)“ და დააჭირეთ „სცენარის დამატებას“.
2. „როდის“-ში აირჩიეთ „შეკვეთა გადახდილია“. სხვა ამოცანებისთვის არის „შეკვეთა გაფორმდა“, „შეკვეთის სტატუსი შეიცვალა“ და „შეკვეთა გაუქმდა“.
3. „მაშინ“-ში დაამატეთ „ვებჰუკის გამოძახება“ და მიუთითეთ თქვენი ინტეგრაციის დამმუშავებლის მისამართი. საჭიროებისას პირობებიც დააყენეთ.
4. დაელოდეთ „შენახულია“-ს, გაატარეთ შესაფერისი სატესტო შეკვეთა და დამმუშავებლის მხარეს მოვლენის მიღება შეამოწმეთ.

შედეგია თქვენი დამმუშავებლის გამოძახება შესაბამისი მოვლენისას. BI-ში ჩატვირთვასა და ველების შეჯერებას ინტეგრატორი აწყობს; სცენარი მთელი წარსული ისტორიის ექსპორტს არ ცვლის. თუ მოვლენა არ მოვიდა, შეამოწმეთ, ჩართულია თუ არა სცენარი, ემთხვევა თუ არა მოვლენა და ყველა პირობა და სწორია თუ არა დამმუშავებლის მისამართი. საჯარო API-ის ჟურნალი გასაღებებით შესრულებულ შემომავალ გამოძახებებს აჩვენებს; ამ გამავალი ვებჰუკის მიწოდება მიმღებ მხარეს შეამოწმეთ.

ერთჯერადი ანალიზისთვის შეკვეთების სია „CSV-ის ექსპორტით“ ჩამოტვირთეთ ან მონაცემთა არქივი მოამზადეთ. ეს ხელით შესასრულებელი გზებია და BI-ის განრიგით ავტომატურ განახლებას არ გპირდებათ.

შეზღუდვები#

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

პრობლემების მოგვარება#

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

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

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

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

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

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

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

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