Контактная информация БСП: устройство подсистемы, API и поиск по адресам

Контактная информация БСП — это подсистема Библиотеки стандартных подсистем, которая даёт единый способ хранить адреса, телефоны, почту и другие контакты у любых объектов: контрагентов, физлиц, организаций, документов. Данные лежат в табличной части КонтактнаяИнформация самого объекта, у каждой строки есть тип, вид, человекочитаемое представление и полное значение в формате JSON. Читать и писать их правильно через функции общего модуля УправлениеКонтактнойИнформацией, а не напрямую.

Ниже — устройство подсистемы, основные функции API с примерами и то, что нужно учитывать, если по контактной информации надо искать.

Устройство подсистемы

Что входит в подсистему:

Вид определяет, что именно хранится: тип, обязательность, можно ли несколько значений, проверять ли адрес по классификатору. Виды группируются по объектам — у справочника «Контрагенты» своя группа видов, у «Физических лиц» своя.

Колонки табличной части

• Тип — значение перечисления ТипыКонтактнойИнформации.
• Вид — ссылка на ВидыКонтактнойИнформации.
• Представление — строка, как её видит пользователь.
• Значение — полное описание в JSON (адрес по уровням, код страны и города телефона и т. д.).
• ЗначенияПолей — то же описание в XML по схеме XDTO; используется в старых версиях и для совместимости.
• Служебные колонки для поиска: страна, регион, город у адресов, адрес почты и домен, номер телефона. Их состав зависит от версии БСП — проверьте по своей конфигурации.

Подключение контактной информации к объекту

Порядок внедрения подробно описан в документации к БСП на ИТС, и он меняется от версии к версии. В общих чертах:

1. Добавить объекту табличную часть КонтактнаяИнформация со стандартным набором колонок.
2. Включить объект в состав подсистемы и в типы владельцев вида контактной информации.
3. Описать виды — в актуальных версиях через процедуры начального заполнения: параметры вида получаются функцией УправлениеКонтактнойИнформацией.ПараметрыВидаКонтактнойИнформации, а применяются процедурой УстановитьСвойстваВидаКонтактнойИнформации.
4. В форме объекта вызвать обработчики подсистемы в ПриСозданииНаСервере, ПриЧтенииНаСервере, ОбработкаПроверкиЗаполненияНаСервере, ПередЗаписьюНаСервере и добавить клиентские обработчики-«подключаемые» для элементов, которые подсистема создаёт на форме.

Самая частая ошибка при ручном внедрении — пропущенный вызов в ПередЗаписьюНаСервере: поля на форме заполняются, а в табличную часть ничего не попадает.

Чтение контактной информации из кода

Пакетное чтение для набора объектов — функция КонтактнаяИнформацияОбъектов. Она возвращает таблицу значений с колонками объекта, типа, вида, представления и значения.

// Возвращает соответствие «контрагент — основной телефон».
Функция ТелефоныКонтрагентов(СписокКонтрагентов) Экспорт

	ТипыКИ = Новый Массив;
	ТипыКИ.Добавить(Перечисления.ТипыКонтактнойИнформации.Телефон);

	ТаблицаКИ = УправлениеКонтактнойИнформацией.КонтактнаяИнформацияОбъектов(СписокКонтрагентов, ТипыКИ);

	Результат = Новый Соответствие;
	Для Каждого СтрокаКИ Из ТаблицаКИ Цикл
		// Берём первый найденный телефон каждого контрагента
		Если Результат[СтрокаКИ.Объект] = Неопределено Тогда
			Результат.Вставить(СтрокаКИ.Объект, СтрокаКИ.Представление);
		КонецЕсли;
	КонецЦикла;

	Возврат Результат;

КонецФункции

Для одного значения конкретного вида удобнее ПредставлениеКонтактнойИнформацииОбъекта:

ВидКИ = Справочники.ВидыКонтактнойИнформации.ЮрАдресКонтрагента;
ЮрАдрес = УправлениеКонтактнойИнформацией.ПредставлениеКонтактнойИнформацииОбъекта(Контрагент, ВидКИ);

Имя предопределённого вида (ЮрАдресКонтрагента в примере) в каждой конфигурации своё — посмотрите его в справочнике видов в конфигураторе. Для видов, созданных пользователями, предопределённого элемента нет: их ищут по наименованию или выносят в настройку.

Запись контактной информации

Прямая запись строки в табличную часть — плохая идея: представление будет, а корректного значения JSON — нет, и форма, печать, обмен покажут разное. Подсистема умеет сама строить значение по представлению.

// Записывает электронную почту контрагента, заменяя прежнее значение того же вида.
Процедура ЗаписатьПочтуКонтрагента(КонтрагентСсылка, АдресПочты) Экспорт

	ВидКИ = Справочники.ВидыКонтактнойИнформации.EmailКонтрагенты;

	КонтрагентОбъект = КонтрагентСсылка.ПолучитьОбъект();
	УправлениеКонтактнойИнформацией.ДобавитьКонтактнуюИнформацию(КонтрагентОбъект, АдресПочты, ВидКИ, , Истина);
	КонтрагентОбъект.Записать();

КонецПроцедуры

Последний параметр Истина заменяет существующее значение этого вида, а не добавляет второе. Имя предопределённого вида почты в примере условное — уточните его в своей конфигурации. Если из внешней системы пришла строка адреса, её можно превратить в значение функцией КонтактнаяИнформацияПоПредставлению и уже его передать в ДобавитьКонтактнуюИнформацию. Разбор свободной строки адреса — эвристика: проверяйте результат на реальных данных.

Если на объект нужна блокировка или запись в транзакции с другими данными, оборачивайте это как обычную запись объекта — подсистема не делает ничего особого.

Поиск по контактной информации

Структура «одна строка — одно значение с JSON внутри» универсальна и удобна для обмена, но запросы вида «все контрагенты с одинаковым домом на улице» по ней писать неудобно и медленно: нужные части адреса лежат внутри строки.

Варианты решения по возрастанию трудоёмкости:

1. Искать по служебным колонкам. Телефон, почта, регион и город обычно вынесены в отдельные колонки табличной части — по ним нормальный запрос работает.
2. Разбирать адрес кодом. Модуль РаботаСАдресами (подсистема адресного классификатора) умеет вернуть сведения об адресе — регион, город, улицу, дом, корпус — в виде структуры. Годится для разовой обработки, но не для поиска по всей базе.
3. Дублировать нужные поля. Если поиск по дому или улице нужен регулярно, заведите регистр сведений с разобранными частями адреса и заполняйте его при записи объекта.

Пример поиска контрагента по телефону через служебную колонку:

ВЫБРАТЬ РАЗЛИЧНЫЕ
	КонтактнаяИнформация.Ссылка КАК Контрагент
ИЗ
	Справочник.Контрагенты.КонтактнаяИнформация КАК КонтактнаяИнформация
ГДЕ
	КонтактнаяИнформация.Тип = ЗНАЧЕНИЕ(Перечисление.ТипыКонтактнойИнформации.Телефон)
	И КонтактнаяИнформация.НомерТелефона ПОДОБНО &ШаблонНомера

Номера телефонов хранятся в разных форматах, поэтому перед сравнением нормализуйте искомый номер: оставьте только цифры и сравнивайте по последним десяти.

Коды адресных элементов

Внутри адреса части дома и помещения кодируются числовыми типами по классификации ФНС. Пригодятся, если разбираете значение вручную:

Типичные ошибки

• Запись в табличную часть напрямую. Представление и значение расходятся, обмен передаёт пустой адрес.
• Поиск подстрокой по представлению. «ул. Ленина» и «Ленина ул» не совпадут. Используйте служебные колонки или разобранные данные.
• Жёсткая привязка к XML-полю ЗначенияПолей. В новых версиях основное значение — JSON в колонке Значение; код, читающий только XML, после обновления БСП начинает возвращать пустоту.
• Вызов служебных модулей подсистемы. Модули с суффиксом «Служебный» — не программный интерфейс, их функции меняются без предупреждения. Используйте процедуры из основного модуля.
• Один вид на всё. Если завести один вид «Адрес» для всех целей, потом не отличить юридический адрес от адреса доставки.

Контактная информация БСП рассчитана на хранение и обмен, а не на аналитику. Если по адресам нужно искать и группировать, заложите отдельное хранение разобранных полей сразу.

Встраивание подсистем БСП в собственные конфигурации и доработки типовых форм делаю в рамках разработки конфигураций 1С и доработки 1С. Если контакты гуляют между базами, стоит заранее проверить, как их передаёт обмен между базами 1С.

Итог

• Контактная информация БСП хранится в табличной части КонтактнаяИнформация объекта: тип, вид, представление и значение в JSON.
• Читайте данные через КонтактнаяИнформацияОбъектов и ПредставлениеКонтактнойИнформацииОбъекта.
• Пишите через ДобавитьКонтактнуюИнформацию, а не прямой записью строк.
• Для поиска используйте служебные колонки или дублируйте разобранные части адреса в отдельном хранилище.
• Порядок внедрения и имена процедур сверяйте с документацией своей версии БСП.