Поля сделки

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 — подпись варианта для показа. Подпись, отправленная вместо идентификатора, теряется без ошибки. Подробнее — Формат значения по типам.

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

{
  "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": "Провал" }] }
    },
    "relations": {
      "contact": { "type": "many", "entity": "contacts", "operations": ["list", "add", "remove", "set", "clear"] },
      "company": { "type": "one", "entity": "companies", "includable": true }
    },
    "activities": { "operations": ["list", "create"], "types": ["call", "meeting", "email", "task"] },
    "actions": {
      "move": { "description": "Change deal stage", "method": "POST", "path": "/v1/deals/{id}/move", "params": { "stageId": { "type": "string", "required": true }, "categoryId": { "type": "string", "required": false } } }
    },
    "aggregatable": ["amount", "stageId", "stageSemanticId", "categoryId", "assignedById", "sourceId"],
    "batch": ["create", "update", "delete"],
    "import": { "method": "POST", "path": "/v1/deals/import", "maxItems": 100 },
    "include": ["contact", "company"]
  }
}

Показаны четыре поля из data.fields и остальные ключи data. Блок data.products в примере опущен, полный состав полей — в таблицах выше.

Что делать с именами из data.include, разобрано на странице Получить сделку. Подробнее о параметре include — Связанные данные.

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

403 — у ключа нет скоупа crm:

{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope",
    "hint": "This request needs the 'crm' scope, which the calling key does not carry. Add 'crm' to this key in the developer cabinet (or through the management API), then repeat the call.",
    "cause": "key_scope_missing",
    "requiredScope": "crm",
    "keyScopes": ["task", "im"],
    "fix": { "action": "edit_key_scopes", "via": "cabinet" },
    "userMessage": "Ключу приложения не хватает права «CRM». Добавить его можно в настройках ключа в кабинете разработчика."
  }
}

Ошибки

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

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

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