REST: crm.requisite (реквизиты)

Реквизиты в Битрикс24 — это отдельная сущность CRM, привязанная к контакту или компании и описывающая юридическое лицо: ИНН, КПП, наименование, банковские счета и адреса. Семейство методов crm.requisite.* позволяет управлять ими из внешних систем и корректно готовить данные для счетов и документов.

Зачем нужна отдельная сущность реквизитов

Исторически ИНН и КПП хранились прямо в карточке компании, но начиная с редакций Битрикс24 с шаблонами реквизитов данные вынесены в самостоятельную сущность. У одного контрагента может быть несколько реквизитов (например, юрлицо и ИП того же владельца), и каждый набор описывается своим шаблоном (пресетом).

Реквизит связан с родительской сущностью через два поля: ENTITY_TYPE_ID — тип владельца, и ENTITY_ID — его идентификатор. Тип владельца задаётся числовой константой CCrmOwnerType.

Состав семейства crm.requisite

Группа методов разбита на несколько уровней: сами реквизиты, их шаблоны, банковские реквизиты и связи.

• crm.requisite.fields — описание полей реквизита;
• crm.requisite.add / update / get / list / delete — CRUD;
• crm.requisite.preset.* — шаблоны реквизитов (пресеты);
• crm.requisite.preset.field.* — набор полей внутри пресета;
• crm.requisite.bankdetail.* — банковские реквизиты;
• crm.requisite.link.* — связь реквизита со сделкой/счётом (какой реквизит выбран в конкретном документе).

Адреса реквизита выделены в универсальную сущность и обслуживаются методами crm.address.*.

Шаблоны реквизитов: crm.requisite.preset

Прежде чем создавать реквизит, нужно знать его пресет: именно он определяет, какие поля будут заполнены (для российского юрлица это ИНН/КПП/ОГРН, для ИП — ИНН/ОГРНИП и т.д.). Получите список доступных шаблонов:

POST /rest/1/xxxxxxxx/crm.requisite.preset.list.json
{
  "select": ["ID", "NAME", "COUNTRY_ID", "ENTITY_TYPE_ID"]
}

В ответе придут идентификаторы пресетов. Чтобы узнать, какие именно поля активны в шаблоне, вызовите crm.requisite.preset.field.list с параметром preset:

POST /rest/1/xxxxxxxx/crm.requisite.preset.field.list.json
{ "preset": { "ID": 1 } }

Создание реквизита: crm.requisite.add

Минимальный набор для добавления — тип владельца, идентификатор владельца, пресет и название реквизита. Пример создания реквизита юрлица для компании с ID 77:

POST /rest/1/xxxxxxxx/crm.requisite.add.json
{
  "fields": {
    "ENTITY_TYPE_ID": 4,
    "ENTITY_ID": 77,
    "PRESET_ID": 1,
    "NAME": "ООО Ромашка (основной)",
    "RQ_COMPANY_NAME": "ООО Ромашка",
    "RQ_INN": "7701234567",
    "RQ_KPP": "770101001",
    "RQ_OGRN": "1234567890123"
  }
}

Метод вернёт числовой ID нового реквизита. Обновление выполняется симметрично через crm.requisite.update с передачей id и изменённых полей в fields. Названия полей вида RQ_* одинаковы у add/update, полный перечень — в crm.requisite.fields.

Банковские реквизиты и адреса

Расчётный счёт хранится не в самом реквизите, а в дочерней сущности «банковский реквизит». Она привязывается к реквизиту через ENTITY_ID (ID реквизита) и ENTITY_TYPE_ID, равный 8 (тип «Реквизит»).

POST /rest/1/xxxxxxxx/crm.requisite.bankdetail.add.json
{
  "fields": {
    "ENTITY_ID": 512,
    "ENTITY_TYPE_ID": 8,
    "NAME": "Расчётный счёт в Сбербанке",
    "RQ_BANK_NAME": "ПАО Сбербанк",
    "RQ_BIK": "044525225",
    "RQ_ACC_NUM": "40702810000000000001",
    "RQ_COR_ACC_NUM": "30101810400000000225"
  }
}

Адреса (юридический, фактический, доставки) добавляются методом crm.address.add с тем же ENTITY_TYPE_ID = 8 и указанием TYPE_ID — типа адреса. Перечень допустимых типов адреса вернёт crm.address.fields и crm.enum.addresstype.

• crm.requisite.bankdetail.list — все счета реквизита;
• crm.address.list — адреса, привязанные к реквизиту;
• crm.requisite.link.get — какой реквизит и банковский счёт выбраны в конкретной сделке или счёте.

Выборка и фильтрация реквизитов

Чтобы получить все реквизиты компании, используйте crm.requisite.list с фильтром по владельцу. Метод поддерживает постраничность через параметр start (шаг 50) и сортировку через order.

POST /rest/1/xxxxxxxx/crm.requisite.list.json
{
  "filter": { "ENTITY_TYPE_ID": 4, "ENTITY_ID": 77 },
  "select": ["ID", "NAME", "RQ_INN", "RQ_KPP", "PRESET_ID"],
  "order": { "ID": "ASC" }
}

Поиск по ИНН удобен для дедупликации контрагентов: передайте в фильтре RQ_INN. Учитывайте, что поле привязано к пресету — если реквизит создан по шаблону без ИНН, фильтр по нему ничего не вернёт.

Типичные ошибки интеграции

Большинство проблем с реквизитами связано не с самим методом, а с несоответствием данных пресету и типам сущностей.

Ещё одна частая ошибка — попытка обновить реквизит вебхуком без права crm. Убедитесь, что у вебхука или приложения выданы соответствующие права доступа.

Итог

Реквизиты в Битрикс24 — многоуровневая структура: сам реквизит (crm.requisite) привязан к контакту или компании, а к нему уже цепляются банковские реквизиты (тип 8) и адреса из общей сущности crm.address. Ключ к корректной интеграции — работа через пресеты: сначала выясняете доступные поля шаблона, потом заполняете только их. Такой подход исключает молчаливую потерю данных и дубли контрагентов при обмене с 1С.

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