Поля сделки

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 — сравнивайте с пустым значением, а не с "".

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

Пользовательские поля (ufCrm_*) также возвращаются в ответах и принимаются при создании/обновлении.

Доступные include

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

Пример использования: Получить 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
• Лимиты и оптимизация