Bitimlar uchun ochiq API va CRM vebxuklari

Chato bitimlarini o‘z dasturingizdan boshqarish mumkin: sayt ariza bo‘yicha bitim yaratadi, 1C to‘lovdan keyin uni yopadi, ombor menejerga vazifa qo‘yadi. Teskari yo‘nalishda Chato dasturingizga CRMda nima bo‘lganini xabar qiladi: bitim ko‘chirildi, yutildi, mas’ul o‘zgardi.

Kabinetda sozlanadi: Bitimlar → ⋯ → Sozlamalar → API va vebxuklar (administrator va egasi ko‘radi). U yerda barcha so‘rovlar ma’lumotnomasiga havola bor — Swagger: https://chato.kz/api/v1/public/docs, OpenAPI tavsifi — https://chato.kz/api/v1/public/openapi.json.

API kaliti

Yangi kalit tugmasini bosing, unga nom bering («Sayt», «1C») va huquqlarni belgilang:

Kalit bir marta ko‘rsatiladi — uni darhol nusxalab oling. Chato faqat uning izini saqlaydi va kalitni qayta ko‘rsata olmaydi. Ro‘yxatda kalitni kim chiqargani va oxirgi marta qachon ishlatilgani ko‘rinadi. Bekor qilish — kalit darhol ishlashdan to‘xtaydi, dastur 401 oladi.

Dastur kalit orqali qilgan hamma narsa bitim tarixiga kalitni chiqargan xodim nomidan «API orqali» belgisi bilan yoziladi. Kalit o‘z muallifidan ortiq qila olmaydi: agar xodimdan voronka yashirilgan bo‘lsa, uning kalitidan ham yashirilgan. Bosqich avtomatlashtirishlari, bildirishnomalar va hamkasblar doskasining jonli yangilanishi kabinetdagidek ishlaydi.

So‘rovlarni qanday yuborish kerak

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

Kalitni X-Api-Key sarlavhasi bilan ham berish mumkin. Muvaffaqiyatli javob har doim data maydonida bo‘ladi.

• Cheklov — bitta kalitga daqiqasiga 120 so‘rov. Undan oshsa — 429 va Retry-After sarlavhasi (necha soniyadan keyin takrorlash kerak). Qoldiq X-RateLimit-Remaining da. Har bir kalitning o‘z hisoblagichi bor: bir dastur boshqasining cheklovini yemaydi.
• Dublsiz takrorlash — POST so‘roviga Idempotency-Key sarlavhasini qo‘shing (255 belgigacha istalgan satr, masalan o‘zingizdagi ariza id si). Bir sutka ichida xuddi shu kalit bilan takrorlash birinchi javobni Idempotent-Replayed: true sarlavhasi bilan qaytaradi va ikkinchi bitim yaratmaydi. Xuddi shu kalit boshqa tana bilan — 422 IDEMPOTENCY_KEY_REUSED.

Xatolar

Xato har doim bir ko‘rinishda keladi (message rus tilida; textCode bo‘yicha tarjima qiling):

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

Ma’lumotnomalar

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

Bosqichli voronkalar (kind: OPEN — ishchi, WON — «Muvaffaqiyatli», LOST — «Rad etish»). Shuningdek:

• GET /deal-fields — qo‘shimcha maydonlar: key (qiymatlar yoziladigan maydon kodi), turi, variantlari, qaysi bosqichlarda majburiy;
• GET /loss-reasons — rad etish sabablari;
• GET /users — xodimlar (id, ism, pochta, rol).

Bitimlar

Yaratish

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

Kontakt — contactId yoki contact. contact bo‘yicha Chato avval odamni qidiradi: telefon bo‘yicha (oxirgi 10 raqam, istalgan formatda), keyin e-mail bo‘yicha (registrga qaramay); topmasa — yangisini yaratadi. Javobdagi contactCreated nima bo‘lganini ko‘rsatadi. pipelineId va stageId bo‘lmasa, bitim birinchi voronkaning birinchi bosqichiga tushadi. Standart mas’ul — kalit muallifi; "responsibleUserId": null — mas’ulsiz. Bitim manbai — «API».

Qo‘shimcha maydonlar — /deal-fields kodlari bo‘yicha fields obyekti: ro‘yxat uchun — variant id si, ko‘p tanlov uchun — massiv, sana uchun — 2026-09-28, belgi uchun — true/false. Noto‘g‘ri qiymat — maydon nomi bilan 400.

O‘zgartirish

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

Faqat yuborilgani o‘zgaradi. tags avvalgi ro‘yxatni almashtiradi, maydondagi null uni tozalaydi.

Ko‘chirish, yopish

# bosqichga — doskadagi kabi qoidalar bilan
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"}}'

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

# rad etish — /loss-reasons sababi bilan
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": "выбрали другого"}'

Agar bosqichda majburiy maydonlar bo‘lsa-yu, bitimda ular bo‘sh bo‘lsa, maydonlar ro‘yxati bilan 422 REQUIRED_FIELDS keladi — ularni fields ga qo‘shib, so‘rovni takrorlang. close bitim voronkasining birinchi «Muvaffaqiyatli» / «Rad etish» bosqichini oladi; boshqasi kerak bo‘lsa — uning stageId sini bering.

Topish, o‘qish, o‘chirish

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

Javob: {"data": {"items": [...], "nextCursor": "..."}}. Keyingi sahifa — xuddi shu so‘rov &cursor=<nextCursor> bilan; nextCursor: null — sahifalar tugadi. Filtrlar: pipelineId, stageId, status (open, won, lost, closed, unsorted), responsibleUserId (yoki none), contactId, tag, search (nomi, mijoz ismi yoki raqami), updatedSince va createdSince (ISO sana — «oxirgi martadan beri nima o‘zgardi» sinxronlash uchun qulay).

• GET /deals/DEAL_ID — bitta bitim;
• DELETE /deals/DEAL_ID — 30 kunga savatga (204); POST /deals/DEAL_ID/restore — qaytarish.

Izohlar va vazifalar

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 va GET /deals/DEAL_ID/tasks — ro‘yxatlar. Vazifa turlari: CALL, MEETING, WRITE, OTHER va o‘zingiznikilar (CUSTOM + customTypeId).

Kontaktlar

• GET /contacts?phone=87015551122 yoki ?email=... — topish (20 tagacha);
• POST /contacts {name, phone, email} — yaratish; odam allaqachon bo‘lsa, o‘sha qaytariladi (200, "created": false), yangisi — 201;
• PATCH /contacts/CONTACT_ID — ism, telefon, e-mailni o‘zgartirish.

Mijozga yozish

messages:send huquqi bilan: POST /messages — conversationId yoki phone (yangi raqam uchun qo‘shimcha channelId), text va/yoki fileUrl — kiruvchi havolaning message amali kabi.

Vebxuklar: bitim hodisalari manzilingizga

Manzil qo‘shish → https manzilini kiriting va hodisalarni belgilang. Saqlangandan keyin manzilning o‘z imzo siri paydo bo‘ladi («Ko‘rsatish» tugmasi).

Xuddi shu manzilga chat hodisalarini ham olish mumkin (message.received, conversation.closed va boshqalar — Vebxuklar ga qarang).

Chato POST yuboradi:

{
  "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 — bitimning API qaytaradigan ko‘rinishdagi surati. changes — nima o‘zgargani (from → to; qo‘shimcha maydonlar fields.<kod> ko‘rinishida). actor.type: user (kabinetdagi xodim), api, webhook, automation, system. task.* va note.created da deal yonida task / note turadi.

Sarlavhalar: X-Chato-Event (hodisa), X-Chato-Event-Id (takrorlarda bir xil — dublikatlarni shu bo‘yicha tashlang), X-Chato-Delivery, X-Chato-Timestamp, X-Chato-Signature.

Imzoni tekshirish

X-Chato-Signature — bu sha256= + manzil siri bilan <X-Chato-Timestamp>.<xom tana> satridan olingan HMAC-SHA256. Uni JSON tahlil qilinishidan oldin xom tana bo‘yicha hisoblang va 5 daqiqadan eski so‘rovlarni rad eting.

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); // darhol javob bering, og‘ir ish — fonda
});

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()  # xom baytlar
    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

Qayta yuborishlar, jurnal, avto-o‘chirish

• Muvaffaqiyat — 10 soniya ichidagi istalgan 2xx javob. Aks holda Chato 1 daq, 5 daq, 30 daq, 2 soat va 6 soatdan keyin qayta yuboradi — jami olti urinish. Yo‘naltirishlar (3xx) bajarilmaydi.
• Manzil ostidagi yetkazish jurnali: holat, javob kodi, urinishlar soni, nima yuborilgani va serveringiz nima javob bergani. Qayta yuborish — hodisaning o‘sha id si bilan qayta yetkazish. Jurnal 30 kun saqlanadi.
• Agar yetkazishlar ketma-ket ko‘p marta o‘tmasa (25 urinish), manzil o‘zi o‘chadi, egasi va administratorlar bildirishnoma oladi. Qabul qiluvchini tuzating va Yoqish ni bosing.
• Tekshirish — ping sinov hodisasini yuboradi. Yangi sir — eskisi darhol yaroqsiz bo‘ladi.

Kiruvchi havola orqali bitimlar

Agar assistentning kiruvchi havolasidan foydalansangiz, u bitimlar bilan ham ishlaydi — API dagi kabi qoidalar bilan, tarixda «vebxuk orqali» belgisi bilan:

{ "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": "Оплата прошла" }