Воронки

Воронки продаж и их стадии — структура канбан-доски, по которой перемещаются сделки. Через API вы читаете список воронок, создаёте и обновляете воронку вместе со стадиями одним запросом, удаляете воронку и получаете Kanban-доску со сделками, сгруппированными по стадиям.

Поля воронки

У воронки есть поля name (до 255 символов), description (до 2000 символов, может быть null) и status (draft, active, paused или archived).

Стадии

Стадии создаются и обновляются вместе с воронкой одним запросом; каждая стадия несёт name, type (new, in_progress, success или failed), color (до 16 символов) и order.

Доска воронки

Доска воронки (/board) отдаёт до 50 карточек-сделок по каждой стадии вместе с агрегатами стадии (deals_count, total_amount); для дозагрузки конкретной колонки используйте постраничный эндпоинт стадии (perPage по умолчанию 50).

С 2026-09-26 доска (GET /funnels/{funnel}/board) требует права deal.view, как и постраничный эндпоинт стадии (без права — 403). Карточка сделки видна всем, но цитата последнего сообщения (last_message_preview) пустеет, если это сообщение лежит в канале, закрытом для пользователя правилами channel_access; last_message_at и иконка канала остаются.

Карточка сделки на доске и в постраничном эндпоинте стадии (GET /funnels/{funnel}/stages/{stage}/deals) дополнительно отдаёт сигналы для канбана: contact_id, channel_id (канал последнего диалога), responsible_user_id, awaiting_reply_since (ISO-время, с которого клиент ждёт ответа, либо null), next_task — ближайшая открытая задача {id, type, title, due_at, is_overdue} либо null — и active_ai_agent — {id, name} включённого в диалоге ИИ-агента либо null. Важно: awaiting_reply_since на доске считается по последним 30 сообщениям диалога и только для 200 самых свежих карточек на запрос, у остальных он null, даже если клиент ждёт ответа.

Карточка сделки (доска, постраничный эндпоинт стадии и список GET /funnels/{funnel}/deals) содержит funnel_stage_id — id стадии, в которой лежит сделка; по нему список вне колонок доски понимает, где сделка находится.

Список сделок воронки

GET /funnels/{funnel}/deals — серверный список сделок одной воронки (карточки в том же формате, что на доске). Параметры, все необязательные: page (≥1), perPage — строго 25, 50 или 100, sort — updated_at (по умолчанию), amount, expected_close_date, next_task_due_at, created_at или title, dir — asc/desc, stage_id (стадия этой же воронки, иначе 422), responsible_user_id[] (до 50 id; значение 0 означает «не назначен»), status[] (open, won, lost), stale (boolean: только «застоявшиеся» либо только свежие, по правилу стадии stale_after_days), search (до 100 символов: по названию сделки и имени контакта). Ответ: {"data": {"items": [...], "pagination": {"page", "perPage", "total", "lastPage"}, "has_stage_automations": boolean}}; has_stage_automations — есть ли в компании активные автоматизации по событиям сделок (клиент предупреждает о них перед массовым действием). Нужно право deal.view; токен встраиваемого виджета (embed) получает 403; чужая или несуществующая воронка — 404; лимит — 120 запросов в минуту на пользователя (плюс общий лимит тяжёлых запросов для Bearer-токенов), сверх лимита — 429.

Конверсия воронки

GET /funnels/{funnel}/conversion — сводка за последние 30 дней (window_days) для заголовков колонок доски и полосы воронки в списке сделок. Право — deal.view, embed-токен (iframe) получает 403, воронка другой компании — 404; лимит 60 запросов в минуту на пользователя, результат кэшируется на 5 минут (computed_at — момент расчёта). Выборка — сделки воронки, созданные или переходившие между стадиями за окно (total_deals); пока их меньше min_deals (20), show_conversion равен false, а все проценты (conversion_to_next, funnel_conversion) — null. Поля стадии: stage_id, deals_count, total_amount_by_currency (объект «валюта → сумма»), conversion_to_next (доля 0..1: сколько побывавших на стадии дошли до более поздней; для финальных стадий null). won — {count, amount_by_currency} выигранных за окно; funnel_conversion — доля выигранных среди закрытых за окно won / (won + lost), 0..1, либо null.

«Неразобранное»

С 2026-09-29 у каждой воронки есть виртуальная первая колонка «Неразобранное» — авто-лиды, созданные в режиме auto_lead_mode: unsorted и ещё не принятые (подробно — в группе «Сделки»). Такой лид формально стоит на первой стадии воронки, но не входит ни в одну колонку доски, ни в deals_count/total_amount стадий, ни в постраничную загрузку стадии. Доска отдаёт только счётчик — ключ unsorted: {count} рядом с funnel; сами карточки — GET /funnels/{funnel}/unsorted.

GET /funnels/{funnel}/unsorted — право deal.view (колонку видят и операторы, разбирают её менеджеры и администраторы), воронка другой компании — 404. Параметры page и perPage (5–50, по умолчанию 20), ответ — data.items + data.pagination, новые лиды сверху (по unsorted_at). Каждый элемент — карточка доски (те же поля и то же правило скрытия last_message_preview по channel_access) плюс contact_id, source, unsorted_at, lead_conversation_id, contact_has_closed_deals (у клиента уже были закрытые сделки — пометка «Повторное»), contact_phone (основной телефон контакта; null, если у вызывающего нет права contact.view) и last_inbound_missed_call (последнее сообщение карточки — входящий звонок, на который не ответили). Лимит — 60 запросов в минуту на пользователя.

Эндпоинты

Метод	Путь	Описание
GET	`/v1/funnels` Список воронок компании	Список воронок компании
POST	`/v1/funnels` Создание воронки (со стадиями)	Создание воронки (со стадиями)
POST	`/v1/funnels/{funnel}` Обновление воронки	Обновление воронки
DELETE	`/v1/funnels/{funnel}` Удаление воронки	Удаление воронки
GET	`/v1/funnels/{funnel}/board` Kanban-доска воронки со сделками по стадиям	Kanban-доска воронки со сделками по стадиям
GET	`/v1/funnels/{funnel}/conversion` Конверсия воронки за 30 дней: сделки и суммы по стадиям, конверсия в следующую стадию, выигранные и общая конверсия	Конверсия воронки за 30 дней: сделки и суммы по стадиям, конверсия в следующую стадию, выигранные и общая конверсия
GET	`/v1/funnels/{funnel}/stages/{stage}/deals` Постраничная загрузка сделок конкретной стадии	Постраничная загрузка сделок конкретной стадии
GET	`/v1/funnels/{funnel}/deals` Серверный список сделок воронки (режим «Список»): фильтры stage_id, responsible_user_id[], status[], stale, search, сортировка sort/dir, постраничность page/perPage (25\|50\|100)	Серверный список сделок воронки (режим «Список»): фильтры stage_id, responsible_user_id[], status[], stale, search, сортировка sort/dir, постраничность page/perPage (25\|50\|100)
GET	`/v1/funnels/{funnel}/unsorted` «Неразобранное» воронки — постраничный список ещё не принятых авто-лидов (perPage 5–50)	«Неразобранное» воронки — постраничный список ещё не принятых авто-лидов (perPage 5–50)

Примеры

Список сделок воронки с фильтрами

Запрос

bash

curl -X GET "https://api.aisar.app/v1/funnels/3/deals?perPage=25&sort=amount&dir=desc&status[]=open&responsible_user_id[]=0&responsible_user_id[]=5" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Ответ

json

{
  "data": {
    "items": [
      {
        "id": 501,
        "title": "Ремонт кухни",
        "status": "open",
        "amount": "450000.00",
        "currency": "KZT",
        "funnel_stage_id": 12,
        "contact_id": 123,
        "responsible_user_id": 5,
        "...": "..."
      }
    ],
    "pagination": { "page": 1, "perPage": 25, "total": 1, "lastPage": 1 },
    "has_stage_automations": false
  }
}

Конверсия воронки за 30 дней

Запрос

bash

curl -X GET https://api.aisar.app/v1/funnels/3/conversion \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Ответ

json

{
  "data": {
    "funnel_id": 3,
    "window_days": 30,
    "min_deals": 20,
    "total_deals": 46,
    "show_conversion": true,
    "stages": [
      { "stage_id": 11, "deals_count": 14, "total_amount_by_currency": { "KZT": 2800000 }, "conversion_to_next": 0.62 },
      { "stage_id": 12, "deals_count": 9, "total_amount_by_currency": { "KZT": 1950000 }, "conversion_to_next": 0.41 },
      { "stage_id": 13, "deals_count": 6, "total_amount_by_currency": { "KZT": 1200000 }, "conversion_to_next": null }
    ],
    "won": { "count": 6, "amount_by_currency": { "KZT": 1200000 } },
    "funnel_conversion": 0.4,
    "computed_at": "2026-10-08T07:30:00+00:00"
  }
}

Создание воронки со стадиями

Запрос

bash

curl -X POST https://api.aisar.app/v1/funnels \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales",
    "description": "Primary sales pipeline",
    "status": "active",
    "stages": [
      { "name": "Lead", "type": "new", "color": "#3B82F6", "order": 1 },
      { "name": "Negotiation", "type": "in_progress", "color": "#F59E0B", "order": 2 },
      { "name": "Won", "type": "success", "color": "#22C55E", "order": 3 }
    ]
  }'

Ответ

json

{
  "data": {
    "message": "Funnel created.",
    "funnel": {
      "id": 1,
      "company_id": 1,
      "name": "Sales",
      "slug": "sales",
      "description": "Primary sales pipeline",
      "steps": 3,
      "updated_at": "2026-03-15T10:00:00.000000Z",
      "stages": [
        { "id": 1, "funnel_id": 1, "name": "Lead", "type": "new", "order": 1, "color": "#3B82F6", "stale_after_days": null, "wip_limit": null },
        { "id": 2, "funnel_id": 1, "name": "Negotiation", "type": "in_progress", "order": 2, "color": "#F59E0B", "stale_after_days": null, "wip_limit": null },
        { "id": 3, "funnel_id": 1, "name": "Won", "type": "success", "order": 3, "color": "#22C55E", "stale_after_days": null, "wip_limit": null }
      ]
    }
  }
}

Kanban-доска воронки

Запрос

bash

curl https://api.aisar.app/v1/funnels/1/board \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json

{
  "data": {
    "funnel": { "id": 1, "name": "Sales" },
    "unsorted": { "count": 3 },
    "stages": [
      {
        "id": 1,
        "name": "Lead",
        "type": "new",
        "order": 1,
        "color": "#3B82F6",
        "stale_after_days": null,
        "wip_limit": null,
        "deals_count": 1,
        "total_amount": "5000.00",
        "deals": [
          {
            "id": 501,
            "title": "Office renovation",
            "amount": "5000.00",
            "currency": "KZT",
            "status": "open",
            "expected_close_date": null,
            "stage_changed_at": "2026-03-15T10:00:00.000000Z",
            "age_days": 3,
            "is_stale": false,
            "channel": "whatsapp",
            "contact_name": "Aigerim Bekova",
            "contact_avatar": null,
            "responsible_user_name": "Aidos",
            "last_message_preview": "Hello, can we schedule a call?",
            "last_message_at": "2026-03-15T09:40:00.000000Z",
            "conversations_count": 2,
            "contact_id": 301,
            "channel_id": 12,
            "responsible_user_id": 5,
            "awaiting_reply_since": "2026-03-15T09:40:00.000000Z",
            "next_task": { "id": 77, "type": "call", "title": "Call back", "due_at": "2026-03-16T10:00:00.000000Z", "is_overdue": false },
            "active_ai_agent": null
          }
        ]
      }
    ]
  }
}

Постраничная загрузка сделок стадии

Запрос

bash

curl "https://api.aisar.app/v1/funnels/1/stages/1/deals?page=2&perPage=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json

{
  "data": {
    "items": [
      {
        "id": 542,
        "title": "Warehouse lease",
        "amount": "12000.00",
        "currency": "KZT",
        "status": "open",
        "expected_close_date": "2026-04-01",
        "stage_changed_at": "2026-03-14T08:00:00.000000Z",
        "age_days": 4,
        "is_stale": false,
        "channel": "telegram",
        "contact_name": "Marat Ospanov",
        "contact_avatar": null,
        "responsible_user_name": "Aidos",
        "last_message_preview": null,
        "last_message_at": null,
        "conversations_count": 1
      }
    ],
    "pagination": { "page": 2, "perPage": 50, "total": 120, "lastPage": 3 }
  }
}

«Неразобранное» воронки

Запрос

bash

curl "https://api.aisar.app/v1/funnels/1/unsorted?perPage=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json

{
  "data": {
    "items": [
      {
        "id": 640,
        "title": "Dana S.",
        "amount": null,
        "currency": "KZT",
        "status": "open",
        "expected_close_date": null,
        "stage_changed_at": "2026-09-29T15:40:00.000000Z",
        "age_days": 0,
        "is_stale": false,
        "channel": "whatsapp",
        "contact_name": "Dana S.",
        "contact_avatar": null,
        "responsible_user_name": null,
        "last_message_preview": "Здравствуйте, сколько стоит доставка?",
        "last_message_at": "2026-09-29T15:40:00.000000Z",
        "conversations_count": 1,
        "contact_id": 318,
        "source": "whatsapp",
        "unsorted_at": "2026-09-29T15:40:00.000000Z",
        "lead_conversation_id": 9120,
        "contact_has_closed_deals": false,
        "contact_phone": "+12025550143",
        "last_inbound_missed_call": false
      }
    ],
    "pagination": { "page": 1, "perPage": 20, "total": 3, "lastPage": 1 }
  }
}