Ажәларбжьаратә API авебхукқәеи

REST API аԥхьаҩ аизгара, саит аԥшьаҭ, ма бот шәара иаҵанакуа алидқәеи адиалогқәеи cenaly.com аҟны рзы апанель иаԥҵашьа иашьҭаху аус азырҵарц: акарточкақәа рыԥхьара, аԥҵарақәа рыԥсахра, аҭыԥқәа рышьҭра, адиалогқәа рҟны аҭакра. Авебхукқәа, насгьы, шәаратә сервер аҿы алид ҿыцқәа, аҭыԥқәеи аҿаԥшьқәеи рыԥхьаӡа иаҳәоит.

Алагара азы иаҭаху#

Аҩбатәи ашьаҟа. Аключ азинқәеи#

1. Интеграциақәа аарты, нас аԥхьаҟа API авебхукқәеи ақәыӷәӷәа.
2. Аключқәа атаб аҟны Аключ аԥҵара ақәыӷәӷәа, ахьӡ аҭа («CRM», «Саит аԥшьаҭ», «Telegram-бот»).
3. Азинқәа рнабор аалышә, ма азинқәа еиԥш-еиԥш рықәырԥш, афилиалқәа хәыҷык иҟоу аҟны — аключ иаҭаху афилиалқәеи аамҭеи.
4. Асекрет cnk_… акопиа ааԥштәуп. Уи акә-аԥшьара ааԥшуеит: ҳара ҳаҟны уи аотпечаток (SHA-256) ауп.

Анаборқәа: CRM / аԥшьаҭ (алидқәа, аԥҵарақәа, аҭыԥқәа, адиалогқәеи асегментқәеи рыԥхьара), Шәаратә бот (алидқәа иԥхьоит, адиалогқәа рҟны аҭак иҭоит, алидқәа рахь иҩуеит), Аԥхьара мацара, Зегьы.

• Азинқәа аключ азинқәеи афилиалқәеи рнаҭа аҟны рыԥсахуеит — аинтеграциа аус азыруа иацҵоит.
• Аԥсахра асекрет ҿыц иҭоит; ажәытәӡатәи аус аура иаԥыргоит, азинқәеи ажурнали аҟоуп.
• Аԥыхра — иаразнаки насгьы даҽаԥсарада: анаҩстәи аҳәара 401 иауеит.

Аключ азаголовок Authorization: Bearer cnk_… (ма X-Api-Key: cnk_…) ала ишьҭуеит. Уи сервер аҟны мацара шәыԥхьаӡа — браузер аҟны ма мобилтә приложение аҟны шәыҭаӡом.

Ахԥатәи ашьаҟа. Аҳәарақәа раԥхьатәи#

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
• Аинтеграциақәа