Создать элемент смарт-процесса

POST /v1/items/:entityTypeId

Создаёт новый элемент в указанном смарт-процессе. Параметр entityTypeId определяет тип смарт-процесса. Узнать доступные типы: GET /v1/smart-processes.

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

Параметр Тип Описание
title string Название
xmlId string Внешний код
stageId string Стадия. Формат: DT{typeId}_{catId}:{stage}. Список: GET /v1/statuses?filter[entityId]=DYNAMIC_{entityTypeId}_STAGE_{categoryId}
categoryId number ID воронки. Список: GET /v1/categories/:entityTypeId
contactId number ID контакта. Поиск: GET /v1/contacts
companyId number ID компании. Поиск: GET /v1/companies
mycompanyId number ID своей компании
assignedById number Ответственный. Список: GET /v1/users
opportunity number Сумма
currencyId string Валюта. Список: GET /v1/currencies
opened boolean Доступен для всех
begindate datetime Дата начала. Принимает ISO 8601, но сохраняется только дата — время отбрасывается
closedate datetime Дата завершения. Принимает ISO 8601, но сохраняется только дата — время отбрасывается
sourceId string Источник
observers array ID наблюдателей

Полный список полей: GET /v1/items/:entityTypeId/fields. Пользовательские поля (ufCrmN_*) также принимаются.

Примеры

В примерах entityTypeId = 156 — замените на ID вашего смарт-процесса.

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/items/156 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Новый договор",
    "categoryId": 41,
    "assignedById": 1,
    "companyId": 15,
    "opportunity": 500000,
    "currencyId": "RUB"
  }'

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/items/156 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Новый договор",
    "categoryId": 41,
    "assignedById": 1,
    "companyId": 15,
    "opportunity": 500000,
    "currencyId": "RUB"
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/items/156', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Новый договор',
    categoryId: 41,
    assignedById: 1,
    companyId: 15,
    opportunity: 500000,
    currencyId: 'RUB',
  }),
})

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

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/items/156', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Новый договор',
    categoryId: 41,
    assignedById: 1,
    companyId: 15,
    opportunity: 500000,
    currencyId: 'RUB',
  }),
})

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

Поля ответа

Поле Тип Описание
id number ID элемента
title string Название
stageId string Стадия
categoryId number ID воронки
companyId number ID компании
contactId number ID контакта
opportunity number Сумма
currencyId string Валюта
assignedById number Ответственный
createdBy number Создатель
createdTime datetime Дата создания
updatedTime datetime Дата изменения

Ответ содержит все поля элемента, включая пользовательские (ufCrmN_*).

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

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

<entityTypeId> — ID типа смарт-процесса (тот же, что в пути запроса). <portal> — домен портала. Если смарт-процесс вынесен в отдельный раздел портала, Битрикс24 откроет карточку по соответствующему пути. Доступ ограничен правами сотрудника в Битрикс24.

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

JSON 
{
  "success": true,
  "data": {
    "id": 783,
    "title": "Новый договор",
    "stageId": "DT156_41:NEW",
    "categoryId": 41,
    "companyId": 15,
    "contactId": null,
    "opportunity": 500000,
    "currencyId": "RUB",
    "assignedById": 1,
    "createdBy": 1,
    "createdTime": "2026-04-15T14:30:00+03:00",
    "updatedTime": "2026-04-15T14:30:00+03:00"
  }
}

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

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

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

Ошибки

HTTP Код Описание
400 INVALID_DYNAMIC_PARAM entityTypeId не является положительным целым или является зарезервированным (1, 2, 3, 4, 7, 31)
400 READONLY_FIELD В теле передано поле только для чтения (id, createdTime, updatedTime и другие)
422 BITRIX_ERROR Ошибка валидации полей от Битрикс24. Конкретная причина — в поле message
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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