Поля сделки

GET /v1/deals/fields

Возвращает полный список доступных полей, включая пользовательские (ufCrm*).

Примеры

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

curl "https://vibecode.bitrix24.tech/v1/deals/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

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

curl "https://vibecode.bitrix24.tech/v1/deals/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/deals/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Полей:', Object.keys(data.fields).length)

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/deals/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Поля ответа

Подписи полей label и description приходят на русском языке, а те, что платформа берёт напрямую с портала, — на языке портала. Заголовками запроса язык не переключается. У значений enum подпись label английская, русская — в labelRu.

Семь полей выше — leadId, quoteId, taxValue, originId, originatorId, additionalInfo и lastActivityBy — принимаются в filter и в сортировке, в том числе в GET /v1/deals, POST /v1/deals/search и POST /v1/deals/aggregate. У пяти из них (leadId, quoteId, originId, originatorId, additionalInfo) значение может прийти null, и у трёх строковых пустая строка от Битрикс24 приводится к null — сравнивайте с пустым значением, а не с "".

Шесть вычисляемых полей — isWon, isLose, isWork, hasProducts, receivedAmount, lostAmount — Битрикс24 считает только для списка, поиска или действия list общего пакета POST /v1/batch, где поле названо в select явно и без * (GET /v1/deals?select=id,isWon,receivedAmount, POST /v1/deals/search с select). Одиночный GET /v1/deals/{id}, список без select и действие list пакета сущности (его select — проекция, на портал не уходит) отдают по ним null — это не «пусто», а «не запрошено». Все шесть только для чтения: присланное значение отклоняется (создание и изменение — 400 READONLY_FIELD, импорт — 400 IMPORT_ITEM_VALIDATION, пакет сущности — 400 BATCH_ITEM_VALIDATION, общий пакет — READONLY_FIELD под вызовом). Четыре флага в filter не принимаются (400 UNKNOWN_FILTER_FIELD): булев фильтр уходит в Битрикс24 в форме Y/N, а эти флаги портал сравнивает только с булевым значением — по трём флагам стадии строка Y даёт обратный набор, по hasProducts не совпадает ни с одной записью; для стадии фильтруйте по stageSemanticId, для товаров замены нет. Сортировка по всем шести работает; receivedAmount и lostAmount принимаются и в sum/avg/min/max POST /v1/deals/aggregate — итог в учётной валюте портала, в отличие от sum(amount), который складывает суммы в валютах сделок как есть.

UTM-поля (utmSource, utmMedium, utmCampaign, utmContent, utmTerm) возвращаются при чтении, но ни в фильтре, ни в сортировке не принимаются. Запрос отклоняется кодом 400 UNKNOWN_FILTER_FIELD или 400 UNKNOWN_SORT_FIELD до обращения к Битрикс24, а причина по каждому полю приходит в его description в ответе этого же эндпоинта. Для контактов фильтруйте по contactId (основной контакт) или по contactIds (любой из привязанных).

Пользовательские поля (ufCrm*) также возвращаются в ответах и принимаются при создании/обновлении. У поля типа enumeration в ответе этого эндпоинта по пути data.fields.<имя поля>.items приходит массив вариантов вида { "ID": "3983", "VALUE": "warm" }. Это не ключ enum объявленных полей с элементами value и label: для записи в пользовательское поле берётся ID, а VALUE — подпись варианта для показа. Подпись, отправленная вместо идентификатора, теряется без ошибки. Подробнее — Формат значения по типам.

Доступные include

Эндпоинт GET /v1/deals/fields возвращает список доступных include: contact, company.

Пример использования: Получить deals.

Подробнее об include: Связанные данные.

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

{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "ID сделки", "description": "Уникальный числовой идентификатор сделки." },
      "title": { "type": "string", "readonly": false, "label": "Название", "description": "Название сделки." },
      "assignedById": { "type": "number", "readonly": false, "label": "Ответственный", "description": "ID ответственного пользователя. Список: GET /v1/users." },
      "stageSemanticId": { "type": "string", "readonly": true, "label": "Семантика стадии", "description": "Смысловая категория текущей стадии — коды расшифрованы в enum.", "enum": [{ "value": "P", "label": "In progress", "labelRu": "В работе" }, { "value": "S", "label": "Success", "labelRu": "Успех" }, { "value": "F", "label": "Failure", "labelRu": "Провал" }] }
    },
    "batch": ["create", "update", "delete"]
  }
}

Показаны 3 из множества полей. Полный список в таблице выше.

Ошибки

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

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

• Создать сделку
• Пользовательские поля
• Entity API
• Лимиты и оптимизация