API public și webhook-uri

API-ul REST permite CRM-ului dumneavoastră, backend-ului site-ului sau propriului bot să lucreze cu lead-uri și conversații cenaly.com exact așa cum o face panoul: să citească fișe, să modifice proprietăți, să trimită evenimente, să răspundă în conversații. Webhook-urile, dimpotrivă, informează ele însele serverul dumneavoastră despre lead-uri, evenimente și mesaje noi.

Ce este necesar pentru lansare#

Pasul 1. Cheia și drepturile#

1. Deschideți Integrări și apăsați API și webhook-uri în antetul paginii.
2. În fila Chei apăsați Creează cheie, introduceți un nume („CRM”, „Backend-ul site-ului”, „Bot Telegram”).
3. Alegeți un set de drepturi sau bifați drepturile unul câte unul, iar dacă aveți mai multe puncte de lucru — la ce puncte de lucru are acces cheia, și termenul.
4. Copiați secretul cnk_…. El se afișează o singură dată: la noi se păstrează doar amprenta lui (SHA-256).

Seturi: CRM / backend (lead-uri, proprietăți, evenimente, citirea conversațiilor și segmentelor), Bot propriu (citește lead-uri, răspunde în conversații, scrie lead-urilor), Doar citire, Tot.

• Drepturi schimbă drepturile și punctele de lucru ale cheii din mers — integrarea continuă să funcționeze.
• Reemite eliberează un secret nou; cel vechi încetează să funcționeze imediat, drepturile și jurnalul rămân.
• Revocă — imediat și pentru totdeauna, următoarea cerere va primi 401.

Cheia se transmite prin antetul Authorization: Bearer cnk_… (sau X-Api-Key: cnk_…). Păstrați-o doar pe server — nu în browser și nu în aplicația mobilă.

Pasul 2. Primele cereri#

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"

Răspunsul este întotdeauna un plic:

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

Pagina următoare — aceeași cerere cu cursor=<meta.nextCursor>; dacă nu există nextCursor — nu mai sunt pagini. Eroare — {"meta": {...}, "error": {"code": "…"}}.

Punctul de lucru. Dacă cheii îi este accesibil un singur punct de lucru, nu este nevoie să îl indicați. Dacă sunt mai multe — adăugați location=<id punct de lucru> (lista — GET /v1/locations), altfel răspunsul este 400 location_required.

Proprietăți și evenimente după user_id-ul dumneavoastră. Nu este obligatoriu să păstrați id-ul nostru al lead-ului: adăugați ?by=user_id, și adresa va deveni identificatorul dumneavoastră de utilizator. Dacă un lead cu un astfel de user_id încă nu există — îl vom crea.

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

Scrierea trece prin aceeași coadă ca modificările din panou: schimbările se aplică în câteva secunde, iar răspunsul la o scriere după user_id — 202 cu pending. În fișa lead-ului, autorul modificării apare ca „API: ”.

Metode#

Câmpurile, exemplele și codurile de eroare ale fiecărei metode — în referință.

Pasul 3. Webhook-uri#

Webhook-urile se configurează la punctul de lucru: Chat → Setări → Webhook-uri — adresa https, evenimentele și secretul semnăturii. La evenimentele conversației (conversație nouă, mesaj nou, status, evaluare, etichete) s-au adăugat evenimentele lead-ului:

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

Numele, e-mailul și telefonul lead-ului ajung în corp doar dacă webhook-ul are bifa „Transmite contactele vizitatorului” activată. Verificarea semnăturii — HMAC-SHA256 al corpului cu secretul webhook-ului:

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

Răspundeți 2xx în 5 secunde — altfel livrarea se repetă; după o serie lungă de eșecuri webhook-ul se dezactivează, iar acest lucru se vede în setări. Duplicatele se elimină după deliveryId.

Limitări#

• 60 de cereri pe minut per cheie; peste — 429 cu antetul Retry-After. Restul — în X-RateLimit-*.
• Până la 200 de înregistrări pe pagină (implicit 50), până la 100 de evenimente per pachet, până la 250 de operații cu proprietăți per cerere, până la 30 de etichete o dată.
• Până la 20 de chei active per cont.
• Jurnalul apelurilor cheii se păstrează 30 de zile: ora, metoda, șablonul căii (fără id și corp), codul răspunsului, durata.
• Evenimentele trimise prin API ajung în fișa lead-ului (flux, rezumat, segmente), dar nu în jurnalul brut al analiticii vizitelor.
• Lead-ului i se poate scrie doar într-o conversație existentă: nu există conversație — răspuns 409 no_conversation.

Depanare#

Fiecare cerere se vede în fila Jurnal apeluri — cu codul răspunsului și numele cheii.

Întrebări frecvente#

Se poate apela API-ul din browser? Nu: cheia dă acces la toate lead-urile punctului de lucru. Apelați API-ul de pe serverul dumneavoastră.

Prin ce diferă user_id de id-ul lead-ului? id-ul lead-ului este identificatorul nostru al fișei. user_id este identificatorul dumneavoastră al utilizatorului (numărul în CRM, id-ul contului de pe site); cu ?by=user_id fișa poate fi adresată prin el.

Ce se întâmplă la retrimiterea unui eveniment? Evenimentul cu același id se contorizează o singură dată — puteți repeta liniștit cererea la o eroare de rețea.

E nevoie de o cheie separată pentru fiecare punct de lucru? Nu: o singură cheie poate lucra cu mai multe puncte de lucru, punctul se alege prin parametrul location.

Secțiuni conexe#

• Chat cu vizitatori — conversații, lead-uri și setările webhook-urilor
• Solicitări — flux unic de intrare
• API și MCP ale propriei centrale telefonice — API separat de telefonie
• Integrări