REST: контакты и компании

Контакты и компании — это клиентская база CRM Битрикс24. Контакт описывает физлицо, компания — организацию, а методы crm.contact.* и crm.company.* позволяют вести их из внешних систем и корректно связывать между собой.

Две сущности и их связь

Контакт (entityTypeId 3) и компания (entityTypeId 4) — самостоятельные сущности с симметричным набором CRUD-методов: add, get, list, update, delete, fields.

Связь между ними — многие-ко-многим: у контакта может быть несколько компаний и наоборот. Для управления связкой есть отдельные под-семейства crm.company.contact.* и crm.contact.company.*.

Создание контакта

Пример crm.contact.add:

{ "fields": { "NAME": "Иван", "SECOND_NAME": "Сергеевич", "LAST_NAME": "Петров", "POST": "Директор", "OPENED": "Y", "ASSIGNED_BY_ID": 1, "PHONE": [ { "VALUE": "+79001234567", "VALUE_TYPE": "WORK" } ], "EMAIL": [ { "VALUE": "ivan@example.ru", "VALUE_TYPE": "WORK" } ] } }

• NAME, LAST_NAME, SECOND_NAME — имя, фамилия, отчество;
• POST — должность;
• OPENED — доступность контакта для всех сотрудников;
• TYPE_ID, SOURCE_ID — тип и источник (справочники).

Поле COMPANY_ID при создании сразу привязывает контакт к основной организации. Ответственного задаёт ASSIGNED_BY_ID; если его не передать, ответственным станет пользователь, от имени которого работает вебхук. Как и у лида, контактные данные — множественные поля, поэтому телефон и почту передают массивом объектов, а не строкой.

Создание компании

Метод crm.company.add использует поле TITLE (обязательное) как название организации:

{ "fields": { "TITLE": "ООО Ромашка", "COMPANY_TYPE": "CUSTOMER", "INDUSTRY": "MANUFACTURING", "EMPLOYEES": "EMPLOYEES_2", "REVENUE": 5000000, "CURRENCY_ID": "RUB", "PHONE": [ { "VALUE": "+74950000000", "VALUE_TYPE": "WORK" } ] } }

Поля COMPANY_TYPE, INDUSTRY, EMPLOYEES — списочные; их допустимые значения смотрите через crm.company.fields в блоке items либо через crm.status.list.

Обратите внимание: у компании нет полей имени и фамилии — только TITLE. Оборот REVENUE задаётся числом вместе с валютой CURRENCY_ID. При загрузке организаций из 1С удобно хранить в UF_* или ORIGIN_ID внешний идентификатор — это упрощает последующую синхронизацию и поиск уже созданных записей.

Привязка контактов к компаниям

Для связи используйте под-семейство crm.company.contact.*:

Пример: { "id": 12, "items": [ { "CONTACT_ID": 45 }, { "CONTACT_ID": 46 } ] } для crm.company.contact.items.set.

Метод items.set заменяет весь список связей компании целиком, поэтому для точечного добавления одного сотрудника используйте crm.company.contact.add. Зеркальное семейство crm.contact.company.* делает то же самое со стороны контакта. Обе стороны работают с одной и той же таблицей связей, так что достаточно вызвать любой из наборов методов.

Множественные поля и мессенджеры

Телефоны, почты, сайты и мессенджеры и у контакта, и у компании — множественные поля. Передаются массивом объектов { VALUE, VALUE_TYPE }.

• PHONE — телефоны;
• EMAIL — адреса почты;
• WEB — сайты;
• IM — мессенджеры (типы TELEGRAM, WHATSAPP и др.).

Тип значения (VALUE_TYPE) влияет на то, как Битрикс24 использует контакт: рабочий телефон подхватывается телефонией, мобильный — SMS-рассылками. Поэтому при загрузке из внешней системы стоит переносить и тип, а не только сам номер. Полный набор допустимых типов для конкретного поля виден в ответе crm.contact.fields в секции соответствующего мультиполя.

Реквизиты и поиск дублей

Юридические реквизиты (ИНН, КПП, банк) хранятся не в самих полях компании, а в отдельной сущности — семейство crm.requisite.*. Реквизит привязывается к владельцу через ENTITY_TYPE_ID и ENTITY_ID.

Перед созданием контакта или компании из внешней системы проверяйте дубли:

• crm.duplicate.findbycomm — поиск по телефону или e-mail (type: PHONE|EMAIL, entity_type);
• анализ ответа: массив ID найденных сущностей.

Сам справочник реквизитов настраивается методами crm.requisite.preset.* (шаблоны для юрлиц и физлиц) и crm.requisite.fields. Банковские реквизиты хранятся отдельно — в crm.requisite.bankdetail.*. Такое разделение позволяет одной компании иметь несколько наборов реквизитов и расчётных счетов, что важно при выставлении счетов и обмене документами с 1С.

Итог

Методы crm.contact.* и crm.company.* ведут клиентскую базу, а под-семейства привязок и реквизитов позволяют строить корректную структуру «организация — сотрудники — документы». Дисциплина по multifield и обязательная проверка дублей сохраняют базу чистой.

Мы в B2Bsite синхронизируем контрагентов между сайтом, Битрикс24 и 1С, настраиваем контроль дублей и обмен реквизитами. Если ваша клиентская база растёт из нескольких источников — поможем свести её в единую непротиворечивую систему.