Мәмілелердің ашық API-і және CRM вебхуктары

Chato мәмілелерін өз бағдарламаңыздан жүргізуге болады. Мысалы, сайт өтінім бойынша мәміле құрады, 1С төлемнен кейін оны жабады, қойма менеджерге тапсырма қояды. Кері бағытта Chato бағдарламаңызға CRM-де не болғанын хабарлайды: мәміле ауыстырылды, сәтті жабылды немесе жауапты ауысты.

Барлығы кабинетте бапталады: CRM → ⋯ → CRM баптаулары → API және вебхуктар. Қойындыны әкімші мен иесі көреді. Сол жерде барлық сұраулардың Swagger анықтамалығына сілтеме бар: https://chato.kz/api/v1/public/docs. OpenAPI пішіміндегі сипаттама https://chato.kz/api/v1/public/openapi.json мекенжайында жатыр.

API кілті

Жаңа кілт түймесін басып, оған атау беріңіз («Сайт», «1С») және құқықтарды белгілеңіз:

Кілт құру түймесін басыңыз. Кілт бір рет көрсетіледі, сондықтан оны бірден көшіріп алыңыз. Chato кілттің тек ізін сақтайды және оны қайта көрсете алмайды. Кілттер тізімінде кілтті кім шығарғаны және оны соңғы рет қашан пайдаланғаны көрінеді. Кері қайтару түймесін басқаннан кейін кілт бірден жұмысын тоқтатады, ал бағдарлама 401 алады.

Бағдарлама кілт арқылы істегеннің бәрі мәміле тарихына кілтті шығарған адамның атынан «API арқылы» белгісімен жазылады. Кілт өз авторынан артық істей алмайды: егер воронка қызметкерден жасырылса, оның кілтінен де жасырылады. Кілт авторы компаниядан кетсе, кілт жұмысын тоқтатады (401). Кезең автоматтандырулары, хабарландырулар және әріптестердегі тақтаның тірі жаңаруы кабинеттегідей іске қосылады.

Сұрауларды қалай жіберу керек

https://chato.kz/api/v1/public
Authorization: Bearer chato_sk_...
Content-Type: application/json

Кілтті X-Api-Key тақырыбында да беруге болады. Сәтті жауап әрқашан data өрісінде болады. Кілтті GET /me сұрауымен тексеруге болады: ол компанияны, кілттің id-ін және оның құқықтарын қайтарады.

{ "data": { "workspaceId": "cmulak1n90001295a8kf4ruhe", "keyId": "cmv2sreij000j293db87lukst", "scopes": ["deals:read", "deals:write"] } }

• Шектеу: бір кілтке минутына 120 сұрау. Әр кілттің өз есептегіші бар, сондықтан бір бағдарлама екіншісінің шектеуін жемейді. Әр жауапта X-RateLimit-Limit, X-RateLimit-Remaining және X-RateLimit-Reset (есептегіш неше секундтан кейін нөлденеді) тақырыптары бар. Шектеуден асса, Retry-After тақырыбымен 429 келеді: неше секундтан кейін қайталау керек. Егер бір IP-мекенжайдан бір минутта қате кілтпен 30 сұрау келсе, сол мекенжайдан келесі сұраулар минут соңына дейін 429 алады.
• Қайталаусыз қайта жіберу: POST сұрауына Idempotency-Key тақырыбын қосыңыз. 255 таңбаға дейінгі кез келген жол жарайды, мысалы, өз жүйеңіздегі өтінімнің id-і. Сол кілтпен тәулік ішіндегі қайталау бірінші жауапты Idempotent-Replayed: true тақырыбымен қайтарады және екінші мәміле құрмайды. Бірінші сұрау әлі орындалып жатқанда, қайталау 409 IDEMPOTENCY_IN_PROGRESS алады. Сол кілт басқа сұрау денесімен 422 IDEMPOTENCY_KEY_REUSED береді. Егер бірінші сұрау қатемен аяқталса, қайталау қайтадан орындалады.

Қателер

Қате әрқашан бір түрде келеді:

{
  "error": {
    "code": "REQUIRED_FIELDS",
    "message": "Заполните поля, чтобы перенести в «Договор подписан»",
    "textCode": "REQUIRED_FIELDS",
    "params": { "stage": "Договор подписан" },
    "details": {
      "stageId": "dmo_p1_s5",
      "stageName": "Договор подписан",
      "missing": [{ "id": "dmo_f4", "key": "data_dogovora", "label": "Дата договора", "type": "DATE", "options": [] }]
    }
  },
  "statusCode": 422
}

message әрқашан орыс тілінде келеді. Қатені басқа тілде көрсету үшін оны code немесе textCode бойынша аударыңыз.

Анықтамалықтар

curl https://chato.kz/api/v1/public/pipelines -H "Authorization: Bearer $CHATO_KEY"

Бұл сұрау кезеңдері бар воронкаларды қайтарады:

{
  "data": [
    {
      "id": "cmulbined000f29fg1na5uhw2",
      "name": "Продажи",
      "position": 0,
      "lossReasonRequired": true,
      "stages": [
        { "id": "cmulbinee000g29fg7o2ep8ev", "name": "Новая заявка", "color": "#3B82F6", "position": 0, "kind": "OPEN" },
        { "id": "cmulbinee000j29fgem0qk8ti", "name": "Успешно", "color": "#10B981", "position": 3, "kind": "WON" },
        { "id": "cmulbinee000k29fgkfdfjzdk", "name": "Отказ", "color": "#EF4444", "position": 4, "kind": "LOST" }
      ]
    }
  ]
}

kind — кезең түрі: OPEN — жұмыс кезеңі, WON — «Сәтті», LOST — «Бас тарту». lossReasonRequired: true — «Бас тарту» үшін себеп керек.

Қалған анықтамалықтар:

• GET /deal-fields — қосымша өрістер: key (өріс коды, мәндер сол бойынша жазылады), label, type, options ({id, label} нұсқалары), pipelineIds (өріс қай воронкаларда бар; бос тізім — барлығында), requiredStageIds (өріс қай кезеңдерде міндетті);
• GET /loss-reasons — бас тарту себептері {id, name};
• GET /users — қызметкерлер: id, name, email, role (users:read құқығы керек).

Мәмілелер

Құру

curl -X POST https://chato.kz/api/v1/public/deals \
  -H "Authorization: Bearer $CHATO_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: site-order-10542' \
  -d '{
    "pipelineId": "PIPELINE_ID",
    "title": "Заявка с сайта",
    "amount": 150000,
    "contact": { "name": "Айгерим", "phone": "+7 701 555 11 22", "email": "aigerim@example.com" },
    "tags": ["сайт"],
    "fields": { "gorod": "almaty", "obem": 40 }
  }'

201 жауабы:

{
  "data": {
    "id": "cmv2srw0l000l293dy0wyl3kk",
    "title": "Заявка с сайта",
    "amount": 150000,
    "currency": "KZT",
    "status": "open",
    "pipeline": { "id": "cmulbined000f29fg1na5uhw2", "name": "Продажи" },
    "stage": { "id": "cmulbinee000g29fg7o2ep8ev", "name": "Новая заявка", "kind": "OPEN" },
    "contact": { "id": "cmulm6bkt0007299yv6tep4fx", "name": "Айгерим", "phone": "77015551122", "email": "aigerim@example.com", "createdAt": "2026-09-28T19:01:56.381Z" },
    "responsible": { "id": "cmulak1n60000295aiftvjchb", "name": "Асхат", "email": "askhat@example.com" },
    "tags": ["сайт"],
    "fields": { "gorod": "almaty", "obem": 40 },
    "source": "api",
    "utm": null,
    "description": null,
    "lossReason": null,
    "lossComment": null,
    "conversationId": null,
    "channelId": null,
    "createdBy": { "id": "cmulak1n60000295aiftvjchb", "name": "Асхат", "email": "askhat@example.com" },
    "createdAt": "2026-10-10T19:38:45.333Z",
    "updatedAt": "2026-10-10T19:38:45.333Z",
    "closedAt": null,
    "deletedAt": null,
    "contactCreated": true
  }
}

Барлық сұраулардың жауабында мәміле осылай көрінеді. status — open, won, lost немесе unsorted (сұрыпталмаған).

Контакт contactId немесе contact өрісімен беріледі. contact бойынша Chato алдымен адамды іздейді: телефон бойынша (соңғы 10 цифр, пішімі кез келген), содан кейін e-mail бойынша (регистрге қарамай). Таппаса, жаңасын құрады. Табылған контактіде тек бос өрістер толтырылады. Жауаптағы contactCreated жаңа контакт құрылған-құрылмағанын көрсетеді.

pipelineId көрсетілмесе, мәміле бірінші воронкаға түседі. stageId көрсетілмесе, мәміле воронканың бірінші кезеңіне түседі. title болмаса, атауы «Сделка: <контакт аты>» болады. Әдепкі жауапты — кілт авторы; "responsibleUserId": null — жауаптысыз. description те беруге болады. Мәміле көзі — api.

Қосымша өрістер /deal-fields кодтары бойынша fields нысанымен беріледі. Тізім үшін нұсқаның id-ін, көп таңдау үшін id массивін, күн үшін 2026-09-28 түріндегі жолды, құсбелгі үшін true немесе false беріңіз. Қате мән өріс атауымен 400 қайтарады. Тегтерді 20-ға дейін беруге болады, әрқайсысы 40 таңбаға дейін.

Өзгерту

curl -X PATCH https://chato.kz/api/v1/public/deals/DEAL_ID \
  -H "Authorization: Bearer $CHATO_KEY" -H 'Content-Type: application/json' \
  -d '{"amount": 180000, "tags": ["сайт", "vip"], "fields": {"oplata": "invoice"}}'

Тек жіберілгені өзгереді: title, amount, responsibleUserId, description, tags, fields, source. tags бұрынғы тізімді ауыстырады. Өрістегі null оны тазартады. stageId те беруге болады (lossReasonId, lossComment бірге): сонда мәміле /move сияқты ережелермен кезеңге өтеді.

Ауыстыру, жабу

# кезеңге — тақтадағыдай ережелермен
curl -X POST https://chato.kz/api/v1/public/deals/DEAL_ID/move \
  -H "Authorization: Bearer $CHATO_KEY" -H 'Content-Type: application/json' \
  -d '{"stageId": "STAGE_ID", "fields": {"data_dogovora": "2026-09-28"}}'

# сәтті
curl -X POST https://chato.kz/api/v1/public/deals/DEAL_ID/close \
  -H "Authorization: Bearer $CHATO_KEY" -H 'Content-Type: application/json' \
  -d '{"result": "won"}'

# бас тартумен — /loss-reasons ішіндегі себеппен
curl -X POST https://chato.kz/api/v1/public/deals/DEAL_ID/close \
  -H "Authorization: Bearer $CHATO_KEY" -H 'Content-Type: application/json' \
  -d '{"result": "lost", "lossReasonId": "REASON_ID", "lossComment": "выбрали другого"}'

move, close және restore мәмілені 200 кодымен қайтарады. Егер кезеңде міндетті өрістер болса, ал мәміледе олар бос болса, өрістер тізімімен 422 REQUIRED_FIELDS келеді. Оларды fields ішіне қосып, сұрауды қайталаңыз. move арқылы «Бас тартуға» ауыстыру да lossReasonId және lossComment қабылдайды. close мәмілені оның воронкасындағы бірінші «Сәтті» немесе «Бас тарту» кезеңіне ауыстырады. Осы түрдегі басқа кезең керек болса, оның stageId-ін беріңіз.

Табу, оқу, жою

curl 'https://chato.kz/api/v1/public/deals?pipelineId=PIPELINE_ID&status=open&limit=50' \
  -H "Authorization: Bearer $CHATO_KEY"

Жауап: {"data": {"items": [...], "nextCursor": "..."}}. Жаңа мәмілелер бірінші тұрады. limit — 1-ден 100-ге дейін, әдепкі 50. Келесі бет — сол сұрау &cursor=<nextCursor> қосылып. nextCursor: null — беттер бітті.

Сүзгілер:

• pipelineId, stageId;
• status: open, won, lost, closed (сәтті және сәтсіз жабылғандар), unsorted немесе all (әдепкі; жойылғандардан басқасының бәрі);
• responsibleUserId (немесе none — жауаптысыз), contactId, tag;
• search — атауы, клиенттің аты немесе нөмірі бойынша;
• updatedSince және createdSince — ISO-күн. Синхрондауға ыңғайлы: «соңғы реттен бері не өзгерді».

Қалған сұраулар:

• GET /deals/DEAL_ID — бір мәміле;
• DELETE /deals/DEAL_ID — 30 күнге себетке (денесіз 204 жауабы); POST /deals/DEAL_ID/restore — себеттен қайтару.

Ескертпелер мен тапсырмалар

curl -X POST https://chato.kz/api/v1/public/deals/DEAL_ID/notes \
  -H "Authorization: Bearer $CHATO_KEY" -H 'Content-Type: application/json' \
  -d '{"text": "Оплата прошла в 1С"}'

curl -X POST https://chato.kz/api/v1/public/deals/DEAL_ID/tasks \
  -H "Authorization: Bearer $CHATO_KEY" -H 'Content-Type: application/json' \
  -d '{"kind": "CALL", "text": "Перезвонить", "dueAt": "2026-10-12T09:00:00+05:00"}'

curl -X POST https://chato.kz/api/v1/public/tasks/TASK_ID/complete \
  -H "Authorization: Bearer $CHATO_KEY" -H 'Content-Type: application/json' \
  -d '{"result": "Дозвонились"}'

Тапсырма құруға жауап:

{
  "data": {
    "id": "cmv2ssf3x000y293dabkcfivc",
    "dealId": "cmv2srw0l000l293dy0wyl3kk",
    "contactId": "cmulm6bkt0007299yv6tep4fx",
    "kind": "CALL",
    "customType": null,
    "text": "Перезвонить",
    "dueAt": "2026-10-12T04:00:00.000Z",
    "allDay": false,
    "responsible": { "id": "cmulak1n60000295aiftvjchb", "name": "Асхат", "email": "askhat@example.com" },
    "createdBy": { "id": "cmulak1n60000295aiftvjchb", "name": "Асхат", "email": "askhat@example.com" },
    "completedAt": null,
    "completedBy": null,
    "result": null,
    "createdAt": "2026-10-10T19:39:10.078Z"
  }
}

Тізімдер — GET /deals/DEAL_ID/notes және GET /deals/DEAL_ID/tasks. Ескертпе {id, dealId, text, author, pinned, createdAt} түрінде келеді.

Тапсырма өрістері:

• dueAt — мерзімі, міндетті;
• kind — тапсырма түрі: CALL (қоңырау, әдепкі), MEETING (кездесу), WRITE (жазу), OTHER немесе өз түріңіз (CUSTOM және customTypeId);
• allDay — күні бойғы тапсырма;
• responsibleUserId — орындаушы. Әдепкі бойынша тапсырманы мәміленің жауаптысы алады.

Контактілер

• GET /contacts?phone=87015551122 немесе ?email=... — табу, 20-ға дейін контакт қайтарылады. phone және email болмаса, 400 келеді;
• GET /contacts/CONTACT_ID — бір контакт;
• {name, phone, email} денесімен POST /contacts — құру. Адам бұрыннан бар болса, бар контакт қайтарылады (200, "created": false). Жаңа контакт 201 кодымен және "created": true белгісімен қайтарылады;
• PATCH /contacts/CONTACT_ID — атын, телефонын немесе e-mail-ін өзгерту.

Контакт: {id, name, phone, email, createdAt}.

Клиентке жазу

messages:send құқығы керек. Сұрау — POST /messages. Денесінде conversationId немесе phone көрсетіңіз, жаңа нөмір үшін қосымша channelId. text және/немесе fileUrl қосыңыз (fileName-мен бірге болады). Кіріс сілтеменің message әрекеті сияқты жұмыс істейді.

{ "data": { "status": "sent", "conversationId": "cmt9x1a2b0003o701abcd1234" } }

Бұл нөмірмен диалог жоқ болса және channelId берілмесе, 404 келеді.

Вебхуктар: мәміле оқиғалары сіздің мекенжайыңызға

Мекенжай қосу түймесін басып, https://… мекенжайын жазыңыз және оқиғаларды белгілеңіз. Сақтағаннан кейін мекенжайдың өз қолтаңба құпиясы пайда болады: оны «Көрсету» түймесімен көруге болады. Компанияда 10 мекенжайға дейін болуы мүмкін.

Сол мекенжайға чат оқиғаларын да алуға болады: message.received, conversation.closed және басқалар (Вебхуктар қараңыз). Чат оқиғаларында data ішінде ассистент мекенжайындағыдай өрістер жатады.

Chato мынадай денесі бар POST жібереді (мәміле қысқартылған):

{
  "id": "evt_28b44037b3de48b5b944430d9546c5c1",
  "event": "deal.stage_changed",
  "createdAt": "2026-09-29T04:46:42.196Z",
  "workspaceId": "cmulak1n90001295a8kf4ruhe",
  "data": {
    "deal": {
      "id": "cmulms3cp000r29eujik2dr1e",
      "title": "Заявка с сайта",
      "amount": 150000,
      "currency": "KZT",
      "status": "open",
      "pipeline": { "id": "...", "name": "Продажи" },
      "stage": { "id": "...", "name": "Счёт выставлен", "kind": "OPEN" },
      "contact": { "id": "...", "name": "Айгерим", "phone": "77015551122", "email": "aigerim@example.com", "createdAt": "2026-09-28T19:01:56.381Z" },
      "responsible": { "id": "...", "name": "Асхат", "email": "askhat@example.com" },
      "tags": ["сайт"],
      "fields": { "gorod": "almaty" },
      "closedAt": null
    },
    "changes": {
      "stage": {
        "from": { "id": "...", "name": "В работе", "kind": "OPEN" },
        "to": { "id": "...", "name": "Счёт выставлен", "kind": "OPEN" }
      }
    },
    "actor": { "type": "user", "userId": "cmulak1n60000295aiftvjchb" }
  }
}

data ішінде не жатады:

• deal — мәміленің толық суреті, API қайтаратын түрде;
• changes — не өзгергені, from → to түрінде. Кілттер: title, amount, tags, description, source, responsible, stage, fields.<код>;
• actor.type — өзгерісті кім жасады: user (кабинеттегі қызметкер), api, webhook, automation (онда жанында automationId бар) немесе system;
• reason — deal.deleted оқиғасында жою себебін түсіндіреді;
• task немесе note — task.* және note.created оқиғаларында deal жанында жатады.

Сұрау тақырыптары:

• X-Chato-Event — оқиға;
• X-Chato-Event-Id — барлық қайталауларда бірдей, дубльдерді сонымен алып тастаңыз;
• X-Chato-Delivery — жеткізу id-і;
• X-Chato-Timestamp — жіберу уақыты, Unix секундтары;
• X-Chato-Signature — қолтаңба;
• User-Agent: Chato-Webhooks/1.0.

Қолтаңбаны тексеру

X-Chato-Signature — бұл sha256= және мекенжай құпиясымен есептелген <X-Chato-Timestamp>.<шикі дене> жолының HMAC-SHA256 мәні (құпия whsec_ деп басталады). Қолтаңбаны JSON талданғанға дейін шикі дене бойынша есептеңіз. 5 минуттан ескі сұрауларды қабылдамаңыз.

Node.js (Express):

const crypto = require('node:crypto');
app.post('/chato', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-Chato-Timestamp');
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.CHATO_WEBHOOK_SECRET)
    .update(`${ts}.${req.body}`)
    .digest('hex');
  const given = req.get('X-Chato-Signature') || '';
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  if (!fresh || given.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body);
  res.sendStatus(200); // бірден жауап беріңіз, ауыр жұмыс — фонда
});

PHP:

$body = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_CHATO_TIMESTAMP'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, getenv('CHATO_WEBHOOK_SECRET'));
$given = $_SERVER['HTTP_X_CHATO_SIGNATURE'] ?? '';
if (abs(time() - (int) $ts) > 300 || !hash_equals($expected, $given)) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);
http_response_code(200);

Python (Flask):

import hmac, hashlib, os, time
from flask import request, abort

@app.post("/chato")
def chato():
    body = request.get_data()  # шикі байттар
    ts = request.headers.get("X-Chato-Timestamp", "")
    expected = "sha256=" + hmac.new(
        os.environ["CHATO_WEBHOOK_SECRET"].encode(), f"{ts}.".encode() + body, hashlib.sha256
    ).hexdigest()
    given = request.headers.get("X-Chato-Signature", "")
    if abs(time.time() - int(ts or 0)) > 300 or not hmac.compare_digest(expected, given):
        abort(401)
    event = request.get_json()
    return "", 200

Қайталаулар, журнал, өздігінен өшу

• Серверіңіз 10 секунд ішінде кез келген 2xx кодымен жауап берсе, жеткізу сәтті саналады. Әйтпесе Chato сұрауды 1 мин, 5 мин, 30 мин, 2 сағ және 6 сағаттан кейін қайталайды. Барлығы 8,5 сағатта алты әрекет. Қайта бағыттауларды (3xx) Chato орындамайды және сәтсіздік деп санайды.
• Әр мекенжайдың астында жеткізу журналы бар: мәртебе, жауап коды, әрекеттер саны, не жіберілгені және серверіңіз не жауап бергені. Қайта жіберу түймесі жеткізуді оқиғаның сол id-імен қайталайды. Журнал 30 күн сақталады.
• Қатарынан 25 әрекет өтпесе және сәтсіздіктер бір тәуліктен ұзаққа созылса, мекенжай өздігінен өшеді. Иесі мен әкімшілер хабарландыру алады. Қабылдағышты жөндеп, Қосу түймесін басыңыз.
• Тексеру data: {"message": "Проверка адреса вебхука Chato"} бар ping сынақ оқиғасын жібереді.
• Жаңа құпия жаңа қолтаңба құпиясын шығарады. Ескісі бірден жарамсыз болады.

Кіріс сілтеме арқылы мәмілелер

Егер ассистенттің кіріс сілтемесін пайдаланып жүрсеңіз, ол мәмілелермен де жұмыс істей алады. Ережелер API-дегідей, ал мәміле тарихында «вебхук арқылы» белгісі тұрады. Әрекеттер компания иесінің атынан орындалады.

{ "action": "deal.create", "contact": { "name": "Айгерим", "phone": "+77015551122" }, "deal": { "title": "Заказ из 1С", "amount": 77000 } }
{ "action": "deal.move", "dealId": "DEAL_ID", "stageId": "STAGE_ID" }
{ "action": "deal.note", "dealId": "DEAL_ID", "text": "Оплата прошла" }

Жауапта status (deal_created, deal_moved немесе note_added) және deal келеді, ал deal.note үшін қосымша note келеді.