# Компании контакта

Привязывает компании к контакту, заменяет их состав целиком, читает список и отвязывает по одной или все сразу. Связь хранит порядок компании в списке и признак основной компании. Сами компании при отвязке остаются в CRM.

У контакта с компаниями всегда одна основная компания. Её ID приходит в поле контакта `companyId`, ID всех привязанных компаний — в поле `companyIds` в порядке `sort`. Поле `companyIds` доступно для записи: [`PATCH /v1/contacts/:id`](/docs/entities/contacts/update) с ним заменяет весь состав компаний так же, как [`PUT /v1/contacts/:id/companies`](./companies-set.md). Компании, которых нет в массиве, отвязываются.

Битрикс24 API: `crm.contact.company.items.get`, `crm.contact.company.add`, `crm.contact.company.items.set`, `crm.contact.company.delete`, `crm.contact.company.items.delete`
Скоуп: `crm`

## Операции

- [Список компаний контакта](./companies-list.md) — `GET /v1/contacts/:id/companies`
- [Заменить компании контакта](./companies-set.md) — `PUT /v1/contacts/:id/companies`
- [Привязать компанию к контакту](./companies-create.md) — `POST /v1/contacts/:id/companies`
- [Отвязать компанию от контакта](./companies-delete-delete.md) — `DELETE /v1/contacts/:id/companies/:relatedId`
- [Отвязать все компании от контакта](./companies-delete.md) — `DELETE /v1/contacts/:id/companies`

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

Поля одной связи контакта с компанией. Они приходят в каждом элементе `data`, а `companyId`, `isPrimary` и `sort` можно передать при привязке и замене.

| Поле | Описание |
|------|----------|
| `companyId` | ID компании. Список: [`GET /v1/companies`](/docs/entities/companies/list) |
| `isPrimary` | Основная компания контакта. `true` ровно у одной связи |
| `sort` | Порядок компании в списке. Список связей приходит отсортированным по этому полю |
| `roleId` | Роль связи. `roleId` из запроса не сохраняется, в ответе — `0` |

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

1. **У контакта с компаниями всегда есть основная.** Первая привязанная компания становится основной, даже если передан `isPrimary: false`. `isPrimary: true` в привязке или замене переносит признак на эту компанию. При замене без `true` основной становится первый элемент массива `items`, даже если у него не наименьший `sort`. Если `true` у нескольких элементов, основной становится первый из них. Если отвязать основную компанию, основной становится первая из оставшихся в порядке `sort`.
2. **Существование компании не проверяется.** Привязка и замена принимают ID, которого нет среди компаний, отвечают `200` и сохраняют такую связь. Проверяйте ID через [`GET /v1/companies/:id`](/docs/entities/companies/get) до привязки.
3. **Список не проверяет контакт.** Для ID, которого нет среди контактов, список отвечает `200` с пустым `data`, как для контакта без компаний. Привязка, замена и обе отвязки для такого ID отвечают `404 ENTITY_NOT_FOUND`.
4. **Повторы ведут себя по-разному.** Повторная привязка той же компании отвечает `409 RELATION_ALREADY_EXISTS`, повторная отвязка одной компании — `404 ENTITY_NOT_FOUND`, повторная отвязка всех — снова `204`.
5. **Ответы методов записи.** Привязка и замена возвращают весь список связей после изменения, обе отвязки — `204 No Content` с пустым телом.

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

1. Найти компанию: [`GET /v1/companies`](/docs/entities/companies/list) с фильтром по полям компании.
2. Посмотреть, какие компании уже привязаны к контакту: [`GET /v1/contacts/:id/companies`](./companies-list.md).
3. Привязать компанию и при необходимости сделать её основной: [`POST /v1/contacts/:id/companies`](./companies-create.md) с `isPrimary: true`.
4. Задать состав целиком, например при синхронизации с внешней системой: [`PUT /v1/contacts/:id/companies`](./companies-set.md) со всеми нужными компаниями в `items`.
5. Прочитать контакт вместе с полными записями компаний: [`GET /v1/contacts/:id?include=companyBinding`](/docs/entities/contacts/get), компании — в `data._included.companyBindings`. С `include=company` приходит только основная компания, в `data._included.company`.

## Лимиты

| Лимит | Значение |
|-------|----------|
| Пагинация списка | Нет: [`GET /v1/contacts/:id/companies`](./companies-list.md) возвращает все связи контакта за один вызов |
| Частота чтения списка | Маршрутный лимит: 300 запросов в минуту на портал, все API-ключи портала делят один лимит. Действующее значение маршрутного лимита — в заголовке `x-ratelimit-limit` |
| Частота записи | Общие лимиты API — [Лимиты и оптимизация](/docs/optimization) |
| Компаний за одну привязку | Одна. Несколько компаний сразу — [`PUT /v1/contacts/:id/companies`](./companies-set.md), в его `items` передайте весь нужный состав: не переданные компании отвяжутся |

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

- [Контакты](/docs/entities/contacts)
- [Получить контакт](/docs/entities/contacts/get)
- [Поля контакта](/docs/entities/contacts/fields)
- [Компании](/docs/entities/companies)
- [Контакты компании](/docs/entities/companies/contacts)
- [Лимиты и оптимизация](/docs/optimization)
