Якорь
------crm4dev1575 ------crm4dev1575

Инструкция: структура фида Обмен с

...

сайтами 

Якорь

Назначение

Документ описывает, как в CRM 4DEV формируется JSON-фид для сайта через механизм Дев_ОбменССайтомОнлайн, какие поля попадают в структуру и откуда они берутся в 1С.

...

Важно: в origin/release, коммит f68bf6a61 CRM4DEV-1575, на момент проверки поле ceiling_height еще отличается: в JSON-ключе есть пробел в конце ("ceiling_height "). В origin/develop это исправлено на "ceiling_height".

Якорь
-- --

Где находится код

Основная логика формирования фида:

...

• ПолучитьДанные_ОбменССайтомОнлайн(Запрос) - проверяет name, token, вызывает формирование данных и возвращает HTTP-ответ.
• ВыполнитьФормированиеДанных_ОбменССайтомОнлайн(УзелОбмена) - собирает итоговую JSON-структуру.
• ПодготовитьДанныеДляВыгрузки_ОбменССайтомОнлайн(Параметры) - получает данные через СКД и дополнительные пакетные запросы.
• ДобавитьЗапросыВПакет(ТекстЗапроса, Параметры) - добавляет к основному СКД-запросу выборки цен, скидок, доп. свойств, файлов и итогового дерева.
• ПолучитьСтруктуру_Район, ПолучитьСтруктуру_Объект, ПолучитьСтруктуру_Секция, ПолучитьСтруктуру_ОН, ПолучитьСтруктуру_Балкон, ПолучитьСтруктуру_Цены, ПолучитьСтруктуру_Скидка, ПолучитьСтруктуру_Свойства - задают состав JSON-объектов.

Якорь
endpoint endpoint

Endpoint

HTTP-сервис: RestApi.

URL-шаблон: /feeds/{ИмяМетода}.

...

Для получения фида используется:

GET /feeds/feeds?name=<НаименованиеУзлаОбмена>
token: <ТокенУзлаОбмена>

Параметры:

Ответ всегда оборачивается через СтрокаОтвета:

{
  "data": {},
  "success": true,
  "err_msg": ""
}

При ошибках:

Дальше в документе описана структура внутри data.

Якорь
--json --json

Общая структура JSON

{
  "data": {
    "complexes": [
      {
        "id": "...",
        "name": "...",
        "company": "...",
        "city": "...",
        "images": ["..."],
        "buildings": [
          {
            "id": "...",
            "name": "...",
            "address": "...",
            "floor_cnt": 0,
            "commissioning_period": "2026-12-31T00:00:00",
            "construction_completion": "2026-09-30T00:00:00",
            "sections": [
              {
                "id": "...",
                "name": "Секция 2",
                "flats": [
                  {
                    "id": "...",
                    "name": "...",
                    "section": "...",
                    "building": "...",
                    "complexe": "...",
                    "prices": [],
                    "discounts": [],
                    "additional_properties": []
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "success": true,
  "err_msg": ""
}

...

1. complexes[] - районы строительства.
2. complexes[].buildings[] - объекты строительства внутри района.
3. complexes[].buildings[].sections[] - секции объекта строительства.
4. complexes[].buildings[].sections[].flats[] - лоты / объекты недвижимости.

Якорь
-- --

Как выбираются данные

Основной набор данных строится через СКД СхемаВыгрузкиДанных плана обмена Дев_ОбменССайтомОнлайн.

...

• доп. свойства из табличной части узла обмена ДополнительныеРеквизитыСведения и значений объекта недвижимости;
• присоединенные файлы объектов недвижимости;
• присоединенные файлы районов строительства;
• скидки/наценки;
• связанные объекты;
• все фактические цены по объекту недвижимости;
• итоговое дерево Район -> Объект -> Секция -> ОбъектНедвижимости.

Якорь
complexes-- complexes--

complexes[]: район строительства

Источник уровня: СтрокаРайон из итогового дерева ДеревоДанных.

Якорь
buildings---- buildings----

buildings[]: объект строительства / корпус

Источник уровня: СтрокаОбъект из итогового дерева.

Якорь
-commissioningperiod--constructioncompletion -commissioningperiod--constructioncompletion

Разница commissioning_period и construction_completion

commissioning_period = реквизит объекта строительства СрокВводаВЭксплуатацию.

...

Отдельно: в другом описательном API в коде встречается поле construction_completion_date, но в данном фиде используется именно construction_completion.

Якорь
sections- sections-

sections[]: секция

Источник уровня: СтрокаСекция из итогового дерева.

Отдельного поля с номером секции в текущей структуре нет. Сейчас сайт может получить номер только из name, например из строки Секция 2. Это хрупко: если наименование станет 2 секция, Блок А, Секция 2А, парсинг на сайте сломается.

Рекомендация: добавить в ПолучитьСтруктуру_Секция() отдельное поле, например number, и заполнять его из отдельного реквизита секции, если такой реквизит есть в справочнике секций. Если отдельного реквизита нет, лучше добавить его в 1С, а не парсить номер из наименования.

Якорь
flats---- flats----

flats[]: объект недвижимости / лот

Источник уровня: СтрокаОН из итогового дерева.

Якорь
balconies balconies

Balconies[]

Источник: табличная часть объекта недвижимости Балконы.

Якорь
prices prices

prices[]

Источник: РегистрСведений.УПДК_ФактическиеЦеныНедвижимости.

В массив попадают все цены по объекту недвижимости, где вид цены не помечен на удаление.

Важно по корневым полям price и cost лота: они заполняются не первой ценой из массива, а только той строкой, где ФактическаяЦена.ВидЦены = УПДК_ЦенообразованиеПовтИсп.ПолучитьОсновнойВидЦены(). Если такого вида цены нет среди фактических цен, корневые price и cost останутся пустыми, но массив prices[] может быть заполнен.

Якорь
discounts discounts

discounts[]

Источник: РегистрСведений.УПДК_ФактическиеСкидкиНаценки.СрезПоследних(&Дата, ).

...

• берется последний проведенный документ УПДК_РасчетФактическихСкидокНаценок;
• не выгружаются скидки/наценки с признаком СкидкаНаценка.НеВыгружатьНаСайт;
• блок работает, если включена константа ИспользоватьУправляемыеСкидкиНаценки.

Якорь
additionalproperties additionalproperties

additional_properties[]

Это не резерв “на будущее”. Массив реально заполняется текущим кодом.

...

1. В узле плана обмена Дев_ОбменССайтомОнлайн есть табличная часть ДополнительныеРеквизитыСведения с синонимом Дополнительные свойства.
2. В этой табличной части выбираются свойства из плана видов характеристик ДополнительныеРеквизитыИСведения.
3. При формировании фида код берет только те свойства, которые указаны в этом узле обмена.
4. Значения берутся из двух источников: - Справочник.УПДК_ОбъектыНедвижимости.ДополнительныеРеквизиты, если свойство является дополнительным реквизитом; - РегистрСведений.ДополнительныеСведения, если свойство является дополнительным сведением.
5. В фид попадает строковое представление значения: Строка(ОписаниеСвойства.Значение).

Структура элемента:

Пример:

{
  "additional_properties": [
    {
      "type": "Число",
      "id": "...",
      "name": "Площадь террасы",
      "value": "12,5"
    },
    {
      "type": "Булево",
      "id": "...",
      "name": "Терраса",
      "value": "Да"
    }
  ]
}

Следствие для сайтовиков: состав additional_properties[] не фиксированный в коде. Он зависит от настройки конкретного узла обмена. Если в узел добавили свойство Погреб, Теплый балкон, Номер парковки, Площадь террасы и у лота есть значение, оно попадет в этот массив. Если свойство не добавлено в узел обмена, оно не выгрузится, даже если заполнено в карточке объекта недвижимости.

Якорь
---crm4dev1575 ---crm4dev1575

Что изменено по CRM4DEV-1575

По смыслу изменения задачи:

...

Технически в origin/develop эти поля берутся из ВремНедвижимость.ОбъектНедвижимости.<Реквизит>, то есть из реквизитов объекта недвижимости, а не из старого отдельного раздела “Новые параметры”.

Якорь
-- --

Важные нюансы контракта

1. complexe написано с буквой e на конце. Это текущее имя поля в фиде. Если сайт ожидает complex, потребуется отдельное изменение контракта.
2. Balconies начинается с заглавной буквы. Это текущее имя поля в фиде.
3. В sections[] нет отдельного номера секции. Есть только id и name.
4. additional_properties[] динамический и зависит от настройки узла обмена.
5. Часть числовых значений может сериализоваться как число, а часть как строка, потому что в коде местами используется XMLСтрока(...) или Строка(...).
6. Даты commissioning_period и construction_completion сериализуются через ЗаписатьДатуJSON(..., ФорматДатыJSON.ISO).
7. description, address, images и часть файлов ограничиваются ПОДСТРОКА(..., 1, 1000) в запросах.

Якорь
--- ---

Ответы на вопросы сайтовиков

Якорь
1-commissioningperiod--constructioncompletion--- 1-commissioningperiod--constructioncompletion---

1. commissioning_period и construction_completion: в чем разница?

commissioning_period - срок ввода объекта строительства в эксплуатацию, источник ОбъектСтроительства.СрокВводаВЭксплуатацию.

...

Если сайт определяет “квартал сдачи корпуса”, нужно согласовать бизнес-смысл: ввод в эксплуатацию или окончание строительства. По названию “срок сдачи/окончание строительства” чаще подходит construction_completion, но текущие сайты уже могут использовать commissioning_period, поэтому менять интерпретацию без миграции нельзя.

Якорь
2------- 2-------

2. Можно ли получать номер секции отдельным полем?

В текущем фиде отдельного поля номера секции нет. Есть только:

{
  "id": "...",
  "name": "Секция 2",
  "flats": []
}

Получать номер из name технически можно, но это ненадежно. Рекомендуемое изменение: добавить в секцию поле number, например:

{
  "id": "...",
  "name": "Секция 2",
  "number": "2",
  "flats": []
}

Источник должен быть отдельным реквизитом секции. Если такого реквизита нет, его лучше добавить в 1С. Парсинг из наименования лучше не использовать как постоянное решение.

Якорь
3-----additionalproperties-- 3-----additionalproperties--

3. Что может попадать в additional_properties у лота?

В additional_properties попадают только свойства, настроенные в конкретном узле обмена в табличной части Дополнительные свойства (ДополнительныеРеквизитыСведения). Значения берутся из дополнительных реквизитов/сведений объекта недвижимости.

Это массив для динамических полей, которые не являются фиксированной частью JSON-контракта. Например, туда могут попадать Погреб, Терраса, Площадь террасы, Теплый балкон, Номер парковки, если они заведены как дополнительные реквизиты/сведения, добавлены в узел обмена и заполнены у объекта недвижимости.

...

Минимальный набор проверок:

1. Вызвать GET /feeds/feeds?name=<узел> с корректным токеном и проверить success = true.
2. Проверить, что data.complexes[] содержит только районы из табличной части Районы выбранного узла обмена.
3. Проверить, что у корпуса одновременно присутствуют commissioning_period и construction_completion, и значения соответствуют реквизитам объекта строительства.
4. Проверить, что в sections[] нет отдельного number, если изменение еще не реализовано.
5. Проверить, что у лота есть ключ ceiling_height без пробела на конце. Это критично после переноса фикса из develop в release.
6. Проверить, что wardrobes, view_from_the_windows, side берутся из карточки объекта недвижимости, раздел “Параметры”.
7. Добавить в узел обмена тестовое дополнительное свойство, заполнить его у объекта недвижимости и проверить появление в additional_properties[].
8. Удалить/не добавлять это свойство из узла обмена и проверить, что оно не попадает в additional_properties[].
9. Проверить лот без цен основного вида: prices[] может быть заполнен, а корневые price/cost останутся пустыми.
10. Проверить регрессию по старым ключам: complexe, Balconies, additional_properties, prices, discounts не должны переименоваться без согласования с сайтами.

...

.