Часто задаваемые вопросы¶

Как работать с несколькими юрлицами в API?¶

Как это устроено:

Пользователь (API Робот) - это параметры для авторизации username и password которые мы отправляем при заведении застройщика в платформу Сделка.РФ. Он может быть связан с несколькими сотрудниками, в т.ч. с сотрудниками из разных юрлиц.
Когда пользователь связан с несколькими сотрудниками, в интерфейсе сделка.рф появляется возможность переключаться между этими сотрудниками/юр.лицами. В API эта возможность также реализована. Чтобы выполнить действие в контексте конкретного сотрудника/юр. лица, нужно передать идентификатор сотрудника в заголовке x-member.
Получить список Юр. лиц привязанных к пользователю можно с помощью метода GET /legalEntity
Любая новая сущность (сделка, покупатель, объект недвижимости и т.д.) привязывается к тому юр. лицу, которое было указано в заголовке x-member для API.
Если заголовок не передан, то по умолчанию берётся первый созданный сотрудник.

Резюмируя всё это, для работы нужно:

Выгрузить список id сотрудников и юр.лиц для пользователя API.
В интерфейсе CRM давать выбор, в какое юр. лицо выгружать данные.
В API правильно заполнять заголовок x-member, чтобы он соответствовал юр. лицу. x-member это: apiRobotMemberId - у него будет отображено числовое значение.

apiRobot

Заголовок x-member может игнорироваться при попытке создать родительский объект в одном юр.лице, а дочерние - в другом. Например, объекты недвижимости estateObject всегда привязываются к тому же юр.лицу, что и родительская стройплощадка/ЖК buildingSite.

Зачем нужно поле version?¶

Поле version используется для защиты от параллельного редактирования одного и того же объекта при двухсторонней синхронизации.

Механика работы:

каждый объект содержит поле version, которое меняет значение после любого изменения данных объекта;
если нужно обновить объект, не затирая чужие изменения, то можно это сделать, используйте алгоритм:
выгрузить из Сделка.РФ данные объекта и запомнить version или заранее сохранить его в вашей системе;
передать version в запросе на изменение объекта;
если переданный version совпадёт с тем, что хранится внутри объекта, то запрос выполнится;
если не совпадёт - запрос выдаст ошибку и можно будет вновь синхронизировать данные, ничего не потеряв.

Что такое reference_id?¶

reference_id используется для хранения и поиска по оригинальным идентификаторам объектов из вашей системы. Это избавляет от необходимости запоминать сопоставление идентификаторов на вашей стороне.

Например:

В CRM есть контакт с id c-123. Этот контакт выгружается через API и в Сделка.рф ему присваивается идентификатор d14f7ea5-20e4-464d-92f0-4eee01cba78a. Обычно, нужно сохранять информацию о том, что id c-123 соответствует d14f7ea5-20e4-464d-92f0-4eee01cba78a в Сделка.рф. Но если заполнить reference_id и поместить туда ваш идентификатор c-123, то запоминать ничего не надо - можно искать по reference_id.

Особенности reference_id:

это произвольная строка;
значение не проверяется на уникальность, т.е. можно нескольким объектам задать одинаковое значение и потом получить весь список по reference_id.

Как и в каком порядке выгружать данные в API Сделка.рф?¶

Технически, данные можно выгружать в любом порядке, если удовлетворены зависимости между объектами согласно спецификации.

Основной порядок следующий:

Создать сделку. Для этого необходимо наличие хотя бы одного покупателя.
По мере появления данных обновлять сделку, добавляя объект недвижимости, документы, других покупателей или редактируя содержимое этих объектов.

Я выгрузил данные физ.лица-контакта в API, но не вижу это физ.лицо в Личном Кабинете Застройщика (ЛКЗ), почему?¶

В web-интерфейсе Сделка.РФ не показываются физ.лица, если они не прикреплены ни к одной сделке.

Кто будет продавцом в сделке, созданной через API?¶

Продавцом будет юр.лицо, от имени которого выполнял запрос пользователь API. Это либо юр. лицо из заголовка x-member или юр.лицо по умолчанию.

Как передать адреса?¶

Передать адреса в сущности Сделка.РФ можно 2мя способами:

Передайте адрес заполняя каждое свойство отдельно (region, area, city и тд.).
Передайте адрес одной строкой, используя – value.

Ознакомиться подробнее вы можете в разделе AddressInput.

Как расшифровать ответ в PossibleAction?¶

Это список из того, что заполнено/не заполнено. Пункты со знаком “+“ – заполнено, данные со знаком “-“ – не заполнено.