Поля счёта

GET /v1/invoices/fields

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

Примеры

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

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

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

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

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/invoices/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/invoices/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Поля ответа

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

Стандартные поля счёта

Пользовательские поля (ufCrm_*) возвращаются в ответе наравне со стандартными и доступны для записи. Их состав и количество зависят от портала, поэтому в таблице их нет — читайте живой ответ.

Не всякое поле из таблицы принимается в filter и order. Двенадцать полей — taxValue, observers, contactIds, locationId, webformId, lastActivityBy, lastActivityTime, utmSource, utmMedium, utmCampaign, utmContent, utmTerm — приходят в ответе, но в фильтре дают 400 UNKNOWN_FILTER_FIELD, а в сортировке 400 UNKNOWN_SORT_FIELD; так же отклоняется и невозвращаемое contacts. В select первые семь работают на всех дверях чтения; пять utm* приходят только в полной записи (без select) и в GET /v1/invoices/{id} — в явном select списка и поиска Битрикс24 игнорирует их имена, и ключей в строках не будет. Поля связей parentId2 и parentId7 фильтруются, но не сортируются. Брать имена для этих двух осей нужно не из таблицы выше, а из текста самой ошибки: он перечисляет допустимые.

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

{
  "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." }
    },
    "relations": {
      "contact": { "type": "one", "entity": "contacts", "includable": true },
      "company": { "type": "one", "entity": "companies", "includable": true },
      "deal": { "type": "one", "entity": "deals", "includable": true }
    },
    "aggregatable": ["opportunity", "stageId", "assignedById"],
    "batch": ["create", "update", "delete"],
    "import": { "method": "POST", "path": "/v1/invoices/import", "maxItems": 100 },
    "include": ["contact", "company", "deal"]
  }
}

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

Связь deal читает ID сделки из динамического поля счёта parentId2. Поле приходит из живых метаданных портала и при предупреждении fields_partial может отсутствовать в data.fields.

Что делать с именами из data.include, разобрано на странице Получить счёт.

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

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

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

Ошибки

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

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

• Создать счёт
• Список счетов
• Entity API