# Значения полей CRM и основной контакт

Изменяйте одно значение без замены всего списка или выбирайте основной контакт из уже привязанных.

Битрикс24 API: `crm.<entity>.addfieldvalue`, `crm.<entity>.deletefieldvalue`, `crm.<entity>.setprimarycontact`
Скоуп: `crm`

> Операции требуют включённого флага `crm-rest-v3` и обновления Битрикс24 после `crm 26.2200.0` с включённой возможностью `RestV3CrudDeal`. До включения API возвращает `422 METHOD_NOT_YET_AVAILABLE` с `error.release`.

## Операции

- [Добавить значение](./crm-field-values/add.md) — `POST /v1/deals/:id/fields/:field/values`
- [Удалить значение](./crm-field-values/delete.md) — `DELETE /v1/deals/:id/fields/:field/values`
- [Установить основной контакт](./crm-field-values/primary-contact.md) — `PUT /v1/deals/:id/primary-contact`

## Ресурсы

| Ресурс | Изменение значения | Основной контакт |
|---|---|---|
| `/v1/deals` | POST / DELETE | PUT |
| `/v1/leads` | POST / DELETE | PUT |
| `/v1/contacts` | POST / DELETE | — |
| `/v1/companies` | POST / DELETE | — |
| `/v1/quotes` | POST / DELETE | PUT |
| `/v1/invoices` | POST / DELETE | PUT |
| `/v1/items/:entityTypeId` | POST / DELETE | PUT |

## Ключевые поля

Имя поля в пути `:field` использует написание REST v3.

| Поле | Описание |
|---|---|
| `phone`, `email`, `web`, `im` | Мультиполя. Значение — объект `{valueTypeId,value}`. |
| `contactsId` | Связь с контактом. Значение — ID из [списка контактов](/docs/entities/contacts/list). |
| `companiesId` | Связь с компанией. Значение — ID из [списка компаний](/docs/entities/companies/list). |
| `observersId` | Наблюдатель. Значение — ID из [списка сотрудников](/docs/entities/users/list). |
| `UF_CRM_*` | Пользовательское поле по точному имени. Значение — одно значение его типа. При добавлении файла принимается ID файла или объект загрузки, при удалении указывается сохранённое значение. |
| `contactId` | Поле тела операции основного контакта — ID уже привязанного контакта из [списка контактов](/docs/entities/contacts/list). |

Допустимость поля и значения проверяет Битрикс24.

## Что нужно знать перед работой

Все операции требуют ключ с правом записи `READWRITE`. ID записи берите из списка соответствующего ресурса, ID контакта — из [Контактов](/docs/entities/contacts/list), ID типа смарт-процесса — из [Смарт-процессов](/docs/entities/smart-processes/list).

Для своей компании используйте ресурс `companies` с `?isMyCompany=true`. По умолчанию — `false`. Параметр выбирает права работы со своей компанией без изменения типа записи. Для счетов и смарт-процессов операция основного контакта доступна только при поддержке привязок контактов.

Успешная операция отвечает `204 No Content` без тела. После тайм-аута или неоднозначного сбоя прочитайте запись перед повтором.

## Типичный сценарий

1. Найдите запись в списке её ресурса, например в [списке сделок](/docs/entities/deals/list). Для смарт-процесса возьмите `entityTypeId` из [списка типов смарт-процессов](/docs/entities/smart-processes/list).
2. Добавьте значение: [`POST /v1/deals/:id/fields/:field/values`](./crm-field-values/add.md).
3. Удалите прежнее значение, передав сохранённое значение: [`DELETE /v1/deals/:id/fields/:field/values`](./crm-field-values/delete.md).
4. Выберите основной контакт из привязанных: [`PUT /v1/deals/:id/primary-contact`](./crm-field-values/primary-contact.md).
5. Проверьте результат чтением записи, например [`GET /v1/deals/:id`](/docs/entities/deals/get).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Значений за вызов | Одно. Тело содержит только `value`, у основного контакта — только `contactId` |
| Параметры строки запроса | Только `isMyCompany` и только у ресурса `companies`. Остальные отклоняются с `400 UNKNOWN_FILTER_FIELD` |
| Частота запросов | общая для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [CRM](/docs/entity-api)
- [Ошибки](/docs/errors)