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

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

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

API кілті

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

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

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

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

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

Кілтті X-Api-Key тақырыбымен де беруге болады. Сәтті жауап әрқашан data өрісінде болады.

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

Қателер

Қате әрқашан бір түрде келеді (message орыс тілінде; textCode бойынша аударыңыз):

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

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

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

Кезеңдері бар воронкалар (kind: OPEN — жұмыс, WON — «Сәтті», LOST — «Бас тарту»). Сондай-ақ:

• GET /deal-fields — қосымша өрістер: key (мәндер жазылатын өріс коды), түрі, нұсқалары, қай кезеңдерде міндетті;
• GET /loss-reasons — бас тарту себептері;
• GET /users — қызметкерлер (id, аты, поштасы, рөлі).

Мәмілелер

Құру

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 }
  }'

Контакт — contactId немесе contact. contact бойынша Chato алдымен адамды іздейді: телефон бойынша (соңғы 10 цифр, кез келген пішімде), содан кейін e-mail бойынша (регистрге қарамай); таппаса — жаңасын құрады. Жауаптағы contactCreated не болғанын көрсетеді. pipelineId және stageId болмаса, мәміле бірінші воронканың бірінші кезеңіне түседі. Әдепкі жауапты — кілт авторы; "responsibleUserId": null — жауапсыз. Мәміле көзі — «API».

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

Өзгерту

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

Тек жіберілгені өзгереді. tags бұрынғы тізімді ауыстырады, өрістегі null оны тазартады.

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

# кезеңге — тақтадағыдай ережелермен
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": "выбрали другого"}'

Егер кезеңде міндетті өрістер болса, ал мәміледе олар бос болса, өрістер тізімімен 422 REQUIRED_FIELDS келеді — оларды fields ішіне қосып, сұрауды қайталаңыз. 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": "..."}}. Келесі бет — сол сұрау &cursor=<nextCursor> қосылып; nextCursor: null — беттер бітті. Сүзгілер: pipelineId, stageId, status (open, won, lost, closed, unsorted), 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-01T09: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": "Дозвонились"}'

GET /deals/DEAL_ID/notes және GET /deals/DEAL_ID/tasks — тізімдер. Тапсырма түрлері: CALL, MEETING, WRITE, OTHER және өзіңіздікі (CUSTOM + customTypeId).

Контактілер

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

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

messages:send құқығымен: POST /messages — conversationId немесе phone (жаңа нөмір үшін қосымша channelId), text және/немесе fileUrl — кіріс сілтеменің message әрекеті сияқты.

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

Мекенжай қосу → https мекенжайын енгізіп, оқиғаларды белгілеңіз. Сақтағаннан кейін мекенжайдың өз қолтаңба құпиясы пайда болады («Көрсету» батырмасы).

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

Chato POST жібереді:

{
  "id": "evt_3f2a9c...",
  "event": "deal.won",
  "createdAt": "2026-09-28T10:15:00.000Z",
  "workspaceId": "cmr4sk0ya0001o701hl7ghbqk",
  "data": {
    "deal": {
      "id": "cmulms3cp000r29eujik2dr1e",
      "title": "Заявка с сайта",
      "amount": 150000,
      "currency": "KZT",
      "status": "won",
      "pipeline": { "id": "...", "name": "Продажи" },
      "stage": { "id": "...", "name": "Успешно", "kind": "WON" },
      "contact": { "id": "...", "name": "Айгерим", "phone": "77015551122", "email": "aigerim@example.com" },
      "responsible": { "id": "...", "name": "Асхат", "email": "askhat@example.com" },
      "tags": ["сайт"],
      "fields": { "gorod": "almaty" },
      "closedAt": "2026-09-28T10:15:00.000Z"
    },
    "changes": {
      "stage": {
        "from": { "id": "...", "name": "Счёт выставлен", "kind": "OPEN" },
        "to": { "id": "...", "name": "Успешно", "kind": "WON" }
      }
    },
    "actor": { "type": "api", "userId": "..." }
  }
}

deal — мәміленің API қайтаратын түрдегі суреті. changes — не өзгергені (from → to; қосымша өрістер fields.<код> түрінде). actor.type: user (кабинеттегі қызметкер), api, webhook, automation, system. task.* және note.created оқиғаларында deal жанында task / note жатады.

Тақырыптар: X-Chato-Event (оқиға), X-Chato-Event-Id (қайталауларда бірдей — дубльдерді сонымен алып тастаңыз), X-Chato-Delivery, X-Chato-Timestamp, X-Chato-Signature.

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

X-Chato-Signature — бұл sha256= + мекенжай құпиясымен <X-Chato-Timestamp>.<шикі дене> жолынан алынған HMAC-SHA256. Оны 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 сағаттан кейін қайталайды — барлығы алты әрекет. Қайта бағыттаулар (3xx) орындалмайды.
• Мекенжай астындағы жеткізу журналы: мәртебе, жауап коды, әрекеттер саны, не жіберілгені және сервер не жауап бергені. Қайта жіберу — оқиғаның сол id-імен қайта жеткізу. Журнал 30 күн сақталады.
• Жеткізулер қатарынан көп рет өтпесе (25 әрекет), мекенжай өздігінен өшеді, ал иесі мен әкімшілер хабарландыру алады. Қабылдағышты жөндеп, Қосу басыңыз.
• Тексеру — 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": "Оплата прошла" }