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

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

Признак `isPrimary` у связи значит, что эта компания основная у контакта: её ID приходит в поле контакта `companyId`. Привязка и замена делают компанию основной у каждого переданного контакта. ID всех привязанных контактов приходят в поле компании `contactIds`.

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

## Операции

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

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

Поля одной связи компании с контактом. Они приходят в каждом элементе ответа списка, привязки и замены, а `contactId` и `sort` передаются и в запросах привязки и замены.

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

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

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

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

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

## Лимиты

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

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

- [Компании](/docs/entities/companies)
- [Получить компанию](/docs/entities/companies/get)
- [Контакты](/docs/entities/contacts)
- [Компании контакта](/docs/entities/contacts/companies)
- [Связанные данные (include)](/docs/includes)
- [Лимиты и оптимизация](/docs/optimization)
