Для AI-агентов: markdown этой страницы — /docs-content/entities/deals/create.md индекс документации — /llms.txt

Создать сделку

POST /v1/deals

Создаёт новую сделку в CRM.

Поля запроса (body)

Параметр Тип Описание
title string Название сделки
amount number Сумма
currency string Валюта. Список: GET /v1/currencies
stageId string Стадия воронки. Стандартные: NEW, PREPARATION, PREPAYMENT_INVOICE, EXECUTING, FINAL_INVOICE, WON, LOSE. Портал может иметь свои — список: GET /v1/statuses?filter[entityId]=DEAL_STAGE (для другой воронки — DEAL_STAGE_{categoryId}, стадии там с префиксом C{categoryId}:). Перед записью сверяется со справочником буквально — стадия, которой в воронке нет, отклоняется кодом UNKNOWN_STAGE, запись не создаётся. Пустое значение не проверяется: сделка ложится на стадию по умолчанию
categoryId number ID воронки (0 = основная). Список: GET /v1/deal-categories
companyId number ID компании. Поиск: GET /v1/companies
contactId number ID основного контакта. Поиск: GET /v1/contacts
assignedById number ID ответственного. Список сотрудников: GET /v1/users
sourceId string Источник. Список: GET /v1/statuses?filter[entityId]=SOURCE
sourceDescription string Описание источника
comments string Комментарий
opened boolean Доступна для всех
closedAt datetime Дата закрытия
probability number Вероятность успеха (%)
observers number[] Массив ID наблюдателей. Список сотрудников: GET /v1/users
ufCrm* по схеме поля Пользовательское поле портала, например ufCrmProjectCode. Рабочее имя и тип — в схеме GET /v1/deals/fields, формат значения по типам — Пользовательские поля (UF). В поле типа enumeration записывается ID варианта из массива items этого поля в схеме, в множественное поле — массив таких ID. Подпись VALUE на месте ID теряется: поле с одним значением получает 0. Число, которого нет среди вариантов, сохраняется как есть. Ни подпись, ни несуществующий ID не дают ошибки, ответ приходит с кодом 201, поэтому сопоставляйте подпись с ID на своей стороне и сверяйте сохранённое значение по этому полю в data ответа

Полный список полей: GET /v1/deals/fields.

Примеры

curl — личный ключ

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/deals \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Поставка оборудования",
    "amount": 50000,
    "currency": "RUB",
    "stageId": "NEW",
    "categoryId": 0,
    "assignedById": 1
  }'

curl — OAuth-приложение

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/deals \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Поставка оборудования",
    "amount": 50000,
    "currency": "RUB",
    "stageId": "NEW",
    "categoryId": 0,
    "assignedById": 1
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/deals', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Поставка оборудования',
    amount: 50000,
    currency: 'RUB',
    stageId: 'NEW',
    categoryId: 0,
    assignedById: 1,
  }),
})

const { success, data } = await res.json()
console.log('Deal ID:', data.id)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/deals', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Поставка оборудования',
    amount: 50000,
    currency: 'RUB',
    stageId: 'NEW',
    categoryId: 0,
    assignedById: 1,
  }),
})

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
id number ID созданной сделки
title string Название
amount number Сумма
currency string Валюта
stageId string Стадия
categoryId number ID воронки
assignedById number Ответственный
createdBy number Создатель
createdAt datetime Дата создания
updatedAt datetime Дата изменения

Ответ содержит все поля сделки, включая пользовательские (ufCrm*). Выше показаны основные.

URL карточки сделки в Битрикс24 строится из id:

https://<portal>.bitrix24.ru/crm/deal/details/<id>/

<portal> — домен портала. Доступ ограничен правами сотрудника в Битрикс24.

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "id": 7689,
    "title": "Поставка оборудования",
    "amount": 50000,
    "currency": "RUB",
    "stageId": "NEW",
    "categoryId": 0,
    "assignedById": 1,
    "createdBy": 1,
    "createdAt": "2026-04-14T08:43:59.000Z",
    "updatedAt": "2026-04-14T08:43:59.000Z",
    "companyId": 0,
    "contactId": 0,
    "opened": true,
    "closed": false,
    "typeId": "SALE",
    "observers": [],
    "contactIds": []
  }
}

Пример ответа при ошибке

403 — нет скоупа:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа crm
403 WRITE_BLOCKED_READONLY_KEY Ключ только для чтения — см. права доступа
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
400 INVALID_PARAMS Значение поля не того типа или формата
400 READONLY_FIELD В теле передано поле только для чтения, например isWon. Такие поля отмечены в колонке RO на странице Поля сделки
400 UNKNOWN_STAGE stageId не из справочника стадий воронки categoryId (без него — основной): опечатка, другой регистр, стадия другой воронки без её categoryId. Запись не создаётся; message подсказывает точное написание или нужный categoryId, details.knownStages перечисляет стадии справочника

Полный список общих ошибок API — Ошибки.

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