# CRM Автоматизация

Запускайте CRM-триггеры и бизнес-процессы через API. Автоматизируйте воронку продаж, переводите сделки по стадиям, запускайте цепочки согласований программно.

**Скоуп:** `crm` (триггеры), `bizproc` (бизнес-процессы) | **Базовый URL:** `https://vibecode.bitrix24.tech/v1` | **Авторизация:** `X-Api-Key`

## Разделы документации

- [Триггеры](/docs/automation/triggers) — активация CRM-триггеров для сущностей (2 эндпоинта).
- [Бизнес-процессы](/docs/automation/workflows) — запуск, мониторинг и управление бизнес-процессами (5 эндпоинтов).

## Быстрый старт

### Активировать CRM-триггер

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/triggers/fire \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "deal",
    "entityId": 100,
    "triggerId": "payment_received"
  }'
```

Ответ:

```json
{
  "success": true,
  "data": true
}
```

Полная документация параметров и кодов ошибок: [`POST /v1/triggers/fire`](/docs/automation/triggers/fire)

### Запустить бизнес-процесс

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/workflows/start \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": 15,
    "entityType": "deal",
    "entityId": 100,
    "parameters": {
      "approver": 1,
      "comment": "Согласование скидки 15%"
    }
  }'
```

Ответ:

```json
{
  "success": true,
  "data": {
    "workflowId": "67a1b2c3d4e5f6"
  }
}
```

Полная документация параметров и кодов ошибок: [`POST /v1/workflows/start`](/docs/automation/workflows/start)

## Полный пример

Сценарий: сделка перешла в стадию «Оплачено» — активируем CRM-триггер, затем запускаем бизнес-процесс подготовки документов, отправляем событие для продолжения приостановленного процесса, завершаем ненужный экземпляр.

```javascript
const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.tech/v1'

async function api(method, path, body = null) {
  const opts = {
    method,
    headers: { 'X-Api-Key': VIBE_KEY }
  }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  return res.json()
}

const dealId = 100

// 1. Сделка оплачена — активируем CRM-триггер
await api('POST', '/triggers/fire', {
  entityType: 'deal',
  entityId: dealId,
  triggerId: 'payment_received'
})
console.log('Триггер "Оплата получена" активирован')

// 2. Запускаем бизнес-процесс подготовки документов
const { data: wf } = await api('POST', '/workflows/start', {
  templateId: 22,
  entityType: 'deal',
  entityId: dealId,
  parameters: {
    docType: 'act',
    sendToClient: true
  }
})
console.log('Бизнес-процесс запущен:', wf.workflowId)

// 3. Просматриваем запущенные экземпляры по шаблону
const { data: instances, meta } = await api('GET', '/workflows?templateId=22')
console.log(`Активных процессов по шаблону 22: ${meta.total}`)
for (const instance of instances) {
  console.log(`  ${instance.ID}: started=${instance.STARTED}`)
}

// 4. Отправляем событие в приостановленный процесс
// eventToken приходит на handler зарегистрированной активити из B24-callback
// (см. /docs/entities/bizproc-activities), здесь — иллюстративное значение
await api('POST', '/workflows/event', {
  eventToken: '55c1dc1c3f0d75.67',
  returnValues: { approved: true },
  logMessage: 'Автоматическое подтверждение — сумма в пределах лимита'
})
console.log('Событие отправлено, процесс продолжен')

// 5. Завершаем ненужный экземпляр
await fetch(`${BASE}/workflows/${wf.workflowId}`, {
  method: 'DELETE',
  headers: { 'X-Api-Key': VIBE_KEY }
})
console.log('Процесс завершён')
```

## Справочник эндпоинтов

| Метод | Путь | Bitrix24 метод | Скоуп | Описание |
|-------|------|---------------|-------|---------|
| POST | [`/v1/triggers/fire`](/docs/automation/triggers/fire) | crm.automation.trigger | crm | Активировать CRM-триггер |
| GET | [`/v1/triggers`](/docs/automation/triggers/list) | crm.automation.trigger.list | crm | Список триггеров портала |
| POST | [`/v1/workflows/start`](/docs/automation/workflows/start) | bizproc.workflow.start | bizproc | Запустить бизнес-процесс |
| GET | [`/v1/workflows`](/docs/automation/workflows/list) | bizproc.workflow.instances | bizproc | Список запущенных процессов |
| DELETE | [`/v1/workflows/:id`](/docs/automation/workflows/terminate) | bizproc.workflow.terminate / kill | bizproc | Завершить бизнес-процесс |
| POST | [`/v1/workflows/event`](/docs/automation/workflows/event) | bizproc.event.send | bizproc | Отправить событие в процесс |
| POST | [`/v1/workflows/activity-log`](/docs/automation/workflows/activity-log) | bizproc.activity.log | bizproc | Записать в журнал процесса |

## Коды ошибок

### Ошибки автоматизации

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_ENTITY_TYPE` | Неизвестный тип сущности в `entityType`. Поддерживаются: `deal`, `lead`, `contact`, `company`, `quote`, `invoice` |
| 400 | `MISSING_PARAMS` | Не переданы обязательные параметры (указаны в поле `message` ответа) |
| 400 | `INVALID_PARAMS` | Некорректное значение параметра (возвращается Битрикс24) |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов Битрикс24 |
| 403 | `SCOPE_DENIED` | API-ключ не имеет нужного скоупа: `crm` для триггеров, `bizproc` для бизнес-процессов |
| 403 | `BITRIX_ACCESS_DENIED` | Портал Битрикс24 отклонил операцию — недостаточно прав на стороне портала |
| 404 | `ENTITY_NOT_FOUND` | Сущность или шаблон с указанным ID не найден |
| 422 | `BITRIX_ERROR` | Ошибка Битрикс24 REST API (подробности в поле `message`) |
| 429 | `RATE_LIMITED` | Превышен лимит запросов. Подождите 1–2 секунды и повторите |
| 429 | `QUEUE_TIMEOUT` | Запрос к Битрикс24 ожидал в очереди дольше 30 секунд. Запрос не был отправлен в Битрикс24 — безопасно повторить (`Retry-After`) |
| 500 | `INTERNAL_ERROR` | Внутренняя ошибка сервера |
| 502 | `BITRIX_UNAVAILABLE` | Портал Битрикс24 недоступен |
| 503 | `BITRIX_TIMEOUT` | Битрикс24 принял запрос, но не ответил за 15 секунд. Для write-операций — сначала перечитайте сущность, изменение могло примениться |

Полный справочник общих ошибок — [Ошибки](/docs/errors).

## Смотрите также

- [Сделки](/docs/entities/deals)
- [Лиды](/docs/entities/leads)
- [Шаблоны бизнес-процессов](/docs/entities/bizproc-templates)
- [Действия бизнес-процессов](/docs/entities/bizproc-activities)
- [Роботы](/docs/entities/bizproc-robots)
- [Ошибки](/docs/errors)