Publiczne API i webhooki

REST API pozwala Twojemu CRM, backendowi strony lub własnemu botowi pracować z leadami i dialogami cenaly.com tak samo, jak robi to panel: czytać karty, zmieniać właściwości, wysyłać zdarzenia, odpowiadać w dialogach. Webhooki natomiast same informują Twój serwer o nowych leadach, zdarzeniach i wiadomościach.

Co jest potrzebne do startu#

Krok 1. Klucz i uprawnienia#

1. Otwórz Integracje i kliknij API i webhooki w nagłówku strony.
2. Na zakładce Klucze kliknij Utwórz klucz, wpisz nazwę („CRM”, „Backend strony”, „Bot Telegram”).
3. Wybierz zestaw uprawnień lub zaznacz uprawnienia pojedynczo, przy kilku placówkach — do których placówek klucz ma dostęp, oraz termin.
4. Skopiuj sekret cnk_…. Jest pokazywany tylko raz: przechowujemy wyłącznie jego odcisk (SHA-256).

Zestawy: CRM / backend (leady, właściwości, zdarzenia, odczyt dialogów i segmentów), Własny bot (czyta leady, odpowiada w dialogach, pisze do leadów), Tylko odczyt, Wszystko.

• Uprawnienia zmieniają uprawnienia i placówki klucza w locie — integracja działa dalej.
• Wygeneruj ponownie wydaje nowy sekret; stary przestaje działać natychmiast, uprawnienia i dziennik pozostają.
• Odwołaj — natychmiast i na zawsze, następne żądanie otrzyma 401.

Klucz przekazuje się nagłówkiem Authorization: Bearer cnk_… (lub X-Api-Key: cnk_…). Przechowuj go wyłącznie na serwerze — nie w przeglądarce i nie w aplikacji mobilnej.

Krok 2. Pierwsze żądania#

KEY=cnk_ваш_ключ
API=https://api.cenaly.com/public-api/v1

# co potrafi klucz: uprawnienia, placówki, limit
curl -H "Authorization: Bearer $KEY" "$API/me"

# leady, najnowsze na górze (20 na stronę)
curl -H "Authorization: Bearer $KEY" "$API/contacts?limit=20"

# wyszukiwanie po imieniu, e-mailu lub telefonie
curl -H "Authorization: Bearer $KEY" "$API/contacts?q=anna"

Odpowiedź to zawsze koperta:

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

Następna strona — to samo żądanie z cursor=<meta.nextCursor>; brak nextCursor — nie ma więcej stron. Błąd — {"meta": {...}, "error": {"code": "…"}}.

Placówka. Jeśli klucz ma dostęp do jednej placówki, nie trzeba jej podawać. Jeśli do kilku — dodaj location=<id placówki> (lista — GET /v1/locations), inaczej odpowiedź 400 location_required.

Właściwości i zdarzenia po Twoim user_id. Nie musisz przechowywać naszego id leada: dodaj ?by=user_id, a adresem stanie się Twój identyfikator użytkownika. Jeśli leada z takim user_id jeszcze nie ma — utworzymy go.

# właściwości: operacje 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"

# zdarzenia paczką (do 100), powtórzenie z tym samym id liczy się raz
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"

# odpowiedź w dialogu i zmiana statusu
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"

Zapis przechodzi przez tę samą kolejkę co zmiany z panelu: zmiany są stosowane w ciągu sekund, a odpowiedź na zapis po user_id — 202 z pending. W karcie leada autor zmiany jest widoczny jako „API: ”.

Metody#

Pola, przykłady i kody błędów każdej metody — w dokumentacji.

Krok 3. Webhooki#

Webhooki konfiguruje się przy placówce: Czat → Ustawienia → Webhooki — adres https, zdarzenia i sekret podpisu. Do zdarzeń rozmowy (nowa rozmowa, nowa wiadomość, status, ocena, etykiety) doszły zdarzenia leada:

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

Imię, e-mail i telefon leada trafiają do treści tylko wtedy, gdy w webhooku jest zaznaczona opcja „Przekazuj kontakty gościa”. Weryfikacja podpisu — HMAC-SHA256 treści sekretem webhooka:

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

Odpowiedz 2xx w ciągu 5 sekund — inaczej dostarczenie zostanie powtórzone; po długiej serii niepowodzeń webhook zostaje wyłączony i widać to w ustawieniach. Duplikaty odrzucaj po deliveryId.

Ograniczenia#

• 60 żądań na minutę na klucz; powyżej — 429 z nagłówkiem Retry-After. Pozostały limit — w X-RateLimit-*.
• Do 200 rekordów na stronę (domyślnie 50), do 100 zdarzeń w paczce, do 250 operacji na właściwościach na żądanie, do 30 tagów naraz.
• Do 20 aktywnych kluczy na konto.
• Dziennik wywołań klucza jest przechowywany 30 dni: czas, metoda, wzorzec ścieżki (bez id i treści), kod odpowiedzi, czas trwania.
• Zdarzenia wysłane przez API trafiają do karty leada (strumień, podsumowanie, segmenty), ale nie do surowego dziennika analityki odwiedzin.
• Napisać do leada można tylko w istniejącej rozmowie: brak rozmowy — odpowiedź 409 no_conversation.

Rozwiązywanie problemów#

Każde żądanie jest widoczne na zakładce Dziennik wywołań — z kodem odpowiedzi i nazwą klucza.

Częste pytania#

Czy można wywoływać API z przeglądarki? Nie: klucz daje dostęp do wszystkich leadów placówki. Wywołuj API ze swojego serwera.

Czym user_id różni się od id leada? id leada — nasz identyfikator karty. user_id — Twój identyfikator użytkownika (numer w CRM, id konta na stronie); z ?by=user_id kartę można adresować nim.

Co się stanie przy ponownym wysłaniu zdarzenia? Zdarzenie z tym samym id jest liczone raz — można śmiało powtarzać żądanie przy błędzie sieci.

Czy potrzebny jest osobny klucz na każdą placówkę? Nie: jeden klucz może pracować z kilkoma placówkami, placówkę wybiera się parametrem location.

Powiązane sekcje#

• Czat z gośćmi — rozmowy, leady i ustawienia webhooków
• Zgłoszenia — jednolity strumień przychodzący
• API i MCP własnej centrali — osobne API telefonii
• Integracje