MACRO

Методы API для прямых интеграций с агрегаторами

Набор методов для интеграций с агрегаторами и партнёрскими системами. Они могут не только отправить заявку покупателя, но и передать в MACRO полную структуру партнёрского канала.

Такая схема уменьшает ручной разбор заявок. Вашим сотрудникам проще увидеть источник партнёрского обращения, администраторам системы — выдать доступ только к нужным действиям API, а разработчикам агрегаторов — построить единый сценарий интеграции для разных застройщиков.

#Кому будут полезны API-методы?

#Сотрудники застройщика, ответственные за посредников

Заявки от агрегаторов можно учитывать через связи с контактами агрегатора, агентства и агента, а не только через рекламные метки или текст в комментарии. Это помогает контролировать партнёрский канал, разбирать спорные обращения и готовить актуальную аналитику по посредникам.

#Администраторы MACRO

Для каждого агрегатора можно создать отдельное API-приложение, выдать ему только нужные права и при необходимости быстро отключить доступ. В правах приложения предусмотрены действия для создания контактов, создания заявок, поиска агента и управления аккредитацией агента или агентства.

#Разработчики сайта застройщика и внутренних интеграций

API позволяет принимать партнёрские заявки напрямую: найти или создать контакт агента/агентства, проверить его роль, затем создать заявку с корректными связями в системе MACRO.

#Разработчики ПО агрегаторов

Агрегатор может хранить для каждого застройщика отдельные реквизиты API-приложения, команды API в зависимости от сервера MACRO и свой ID (contacts_aggregator_id) в базе этого застройщика. Один и тот же внешний сервис сможет работать по общей логике, но с раздельными доступами и идентификаторами для каждой компании.

#Как выглядит процесс интеграции

  1. Вы запрашиваете в поддержке MACRO API-ключ для агрегатора.
  2. Вы сообщаете агрегатору реквизиты подключения (адрес API системы MACRO и API-ключ) и его contacts_aggregator_id — ID контакта юридического лица с ролью «Агрегатор».
  3. Перед отправкой агентской заявки агрегатор проверяет API-запросом /contacts/findAgent, есть ли в MACRO нужный агент или агентство недвижимости, за которым он хочет зафиксировать заявку:
    • Если контакта нет, агрегатор создаёт его через API с помощью специализированных методов /contacts/createAgent и /contacts/createAgency, которые создадут контакт с нужно ролью «Агент» и «Агентство недвижимости» соответственно
    • При необходимости отдельным запросом /contacts/accreditateAgent можно установить аккредитацию агента или агентства, чтобы в будущем они самостоятельно могли зайти в личный кабинет агента
  4. При создании заявки с помощью метода API estateBuy/create агрегатор указывает свой ID contacts_aggregator_id, ID агентства недвижимости contacts_agency_id (опционально) и агента contacts_mediator_id.
  5. Заявка создаётся в системе MACRO уже с проставленной связью с агрегатором, агентством и агентом.

В результате в систему MACRO попадает не просто обращение с внешнего источника, а заявка с понятной структурой партнёрского участия.

#Технические уточнения по методам API

При отправке заявки агрегатор должен использовать нижеперечисленные методы API, чтобы получить исчерпывающую информацию об агенте и агентстве недвижимости и верно учесть её в заявке. Ссылки приведены на примере macroserver.ru. Если Ваша система располагается на другом сервере, то или подставьте адрес своего сервера, или запросите ссылку MACRO API в поддержке.

#contacts/findAgent

Метод поиска агентов и агентств недвижимостиПереход на внешний сайтhttps://api.macroserver.ru/docs/api/v2/#tag/Contacts/operation/contacts/findAgent поможет агрегатору проверить контакт до создания заявки.

В запросе обязательно передаётся roles — строка с одним из допустимых значений:

  • agent — для поиск агента,
  • agent_org — для поиска агентства недвижимости.

Дополнительно необходимо передать один из поисковых параметров:

  • phone — телефон, который будет нормализован перед поиском. Обязателен, если не передан commInn,
  • commInn — ИНН для поиска юридического лица. Обязателен, если не передан phone.

Альтернативный способ поиска — по id контакта агента или агентства, в этом случае другие параметры поиска не требуются.

При поиске агента в ответе приходит параметр groupContactsId — это идентификатор агентства, к которому привязан агент в базе контактов застройщика. Если связь имеется, то при создании заявки можно не передавать contacts_agency_id (за исключением случаев, когда конкретную заявку требуется учесть за агентством, отличным от того, с которым сейчас связан агент — тогда в contacts_agency_id нужно передать id требуемого агентства. Передавать во всех заявках contacts_agency_id , даже если он совпадает с текущим связанным агентством агента, не является ошибкой и не влияет на аналитику застройщика, но это нецелесообразно.

#contacts/createAgent

Метод создания агентаПереход на внешний сайтhttps://api.macroserver.ru/docs/api/v2/#tag/Contacts/operation/contacts/createAgent используется, когда агрегатору нужно завести агента перед созданием заявки, а метод /contacts/findAgent контакт не нашёл. Создаёт контакт физического лица, роль agent проставляется автоматически — передавать её не нужно.

Обязательные поля:

  • name — ФИО агента,
  • phones — непустой массив телефонов (в каждом номере минимум 3 цифры).

Дополнительно можно передать:

  • roles — массив дополнительных ролей: buyer (покупатель), partnyor (партнёр), uchastnik_tenderov (участник тендеров). Основную роль agent передавать не нужно,
  • emails — массив адресов эл. почты,
  • nameFull — ассоциации (ключевые слова для поиска, показываются в скобках после имени),
  • nameFirst, nameLast, nameMiddle — имя, фамилия, отчество,
  • dob — дата рождения (формат ГГГГ-ММ-ДД или ДД.ММ.ГГГГ),
  • sex — пол (1 — мужской, 2 — женский),
  • flInn — ИНН физлица (12 цифр),
  • snils — СНИЛС,
  • passportType — тип документа (пусто — паспорт РФ, foreign — паспорт иностранца, birth — свидетельство о рождении, residency — вид на жительство, idcard — удостоверение личности), passportNum, passportDate, passportOrgan, passportOrganCode, passportBirthplace, passportAddress,
  • description — заметка.

#contacts/createAgency

Метод создания агентстваПереход на внешний сайтhttps://api.macroserver.ru/docs/api/v2/#tag/Contacts/operation/contacts/createAgency используйте, когда нужно завести агентство недвижимости, а метод /contacts/findAgent контакт не нашёл. Создаёт только контакт юридического лица, роль agent_org (агентство недвижимости) проставляется автоматически.

Обязательные поля:

  • name — название агентства,
  • commInn — ИНН (10 цифр для агентств-юр.лиц, 12 цифр для агентств-ИП).

Дополнительно можно передать:

  • roles — массив дополнительных ролей: buyer, partnyor, uchastnik_tenderov. Основную роль agent_org передавать не нужно,
  • emails — массив адресов эл. почты,
  • phones — непустой массив телефонов (в каждом номере минимум 3 цифры),
  • nameFull — ассоциации (ключевые слова для поиска),
  • commFullTitle — краткое название организации,
  • commOgrn — ОГРН (13 цифр),
  • commKpp — КПП (9 цифр),
  • commAddress — юридический адрес,
  • description — заметка.

#contacts/create

Использовать для создания контактов допустимо и более универсальный методПереход на внешний сайтhttps://api.macroserver.ru/docs/api/v2/#tag/Contacts/operation/contacts/create, если агрегатору выданы соответствующие права. Если в методе /contacts/findAgent не был найден контакт агента или агентства недвижимости, используйте /contacts/create.

В запрос можно передать roles — непустой массив ролей. Допустимые значения:

  • agent — агент,
  • agent_org — агентство недвижимости,
  • buyer — покупатель,
  • partnyor — партнёр,
  • uchastnik_tenderov — участник тендеров.

Для юридических лиц добавлены поля:

  • comm_full_title — полное или официальное название,
  • comm_inn — ИНН (10 цифр для агентств-юр.лиц, 12 цифр для агентств-ИП),
  • comm_ogrn — ОГРН,
  • comm_kpp — КПП,
  • comm_address — юридический адрес.

Метод ищет или создаёт контакт в пределах доступных компаний застройщика и его партнёров. Если переданы роли, API валидирует их и записывает в контакт только разрешённые значения.

#contacts/linkAgentToAgency

Метод для связывания агента с агентствомПереход на внешний сайтhttps://api.macroserver.ru/docs/api/v2/#tag/Contacts/operation/contacts/linkAgentToAgency, в котором он работает. Используйте, если при поиске агента в параметре groupContactsId пришло пустое значение или если вы создали нового агента, и вам нужно привязать его к агентству. Через этот метод нельзя изменить уже существующую связь.

Обязательные поля:

  • agentId — идентификатор контакта агента,
  • agencyId — идентификатор контакта агентства недвижимости.

#estateBuy/create

Метод для создания заявкиПереход на внешний сайтhttps://api.macroserver.ru/docs/api/v2/#tag/EstateBuy/operation/estateBuy/create используется для передачи потенциальной заявки на покупку в базу данных застройщика.

Обязательные поля:

  • phones — непустой массив телефонов клиента (в каждом номере минимум 10 цифр),
  • name — имя клиента.

Для корректного учета заявки за агрегатором, агентом и агентством также необходимо передать:

  • contacts_aggregator_id — ID контакта юридического лица с ролью «Агрегатор», который инициирует создание заявки.
  • contacts_agency_id — ID контакта юридического лица с ролью «Агентство недвижимости» (опционально, когда у агента нет связи с агентством в groupContactsId или когда конкретную заявку требуется учесть за агентством, отличным от того, с которым сейчас связан агент). Передавать во всех заявках contacts_agency_id , даже если он совпадает с текущим связанным агентством агента, не является ошибкой и не повлияет на аналитику застройщика, но это нецелесообразно.
  • contacts_mediator_id — ID контакта физического лица с ролью «Агент».

Если передан агент contacts_mediator_id, агентство contacts_agency_id или агрегатор contacts_aggregator_id, то заявке присвоится тип источника (channel_type) «Агенты».

Если одно из этих полей передано, система MACRO проверяет, что контакт существует в компании застройщика, не удалён, имеет подходящий тип и нужную роль. Так агент не попадёт в поле агентства, агентство — в поле агрегатора, а неверный или удалённый контакт не создаст некорректную связь в заявке.

По запросу застройщика в заявке также можно передавать:

#Анкета покупателя

Описание полей анкеты и правил их проверки применяется после установки соответствующего обновления MACRO на сервер компании.

В запрос estateBuy/create дополнительно можно передать:

  • dob — дату рождения: ГГГГ-ММ-ДД или ДД.ММ.ГГГГ. Дата должна существовать в календаре; ограничений по возрасту нет.
  • marital_status — семейное положение: unmarried — не состоит в браке, married — состоит в браке, divorced — в разводе, widow — вдовец/вдова.
  • estate_familyComposition — количество членов семьи: 1, 2, 3, 4, 5 (пять и более). Можно передать число или числовую строку.
  • estate_client_aim — цель покупки: for_self=12317, for_children=12318, for_parents=12319, for_relatives=13408, for_friends=13471, investment=12320, rent_out=12321, housing_upgrade=13409, relocation=13410, unknown=13472, clarifying=13473, other=12322. Передавайте имя или соответствующий код — числом либо строкой.
  • estate_living_buy_clause — источники денег: mortgage=1 (ипотека), cash=2 (наличные), property_sale=3 (продажа имущества), maternity_capital=4 (маткапитал), trade_in=5 (обмен), other_subsidies=6 (другие субсидии), offset=7 (зачёт), installment=8 (рассрочка). Можно передать одно значение или список имён/кодов, например ["mortgage", "cash"]. Коды принимаются числами и строками. Непустой список заменяет прежний набор целиком.

Дата рождения и семейное положение записываются только при создании нового контакта клиента. У найденного контакта, в том числе партнёрского, эти поля не меняются, даже если ранее не были заполнены.

Неверное непустое значение любого из пяти полей отклоняет весь запрос с HTTP 422 до создания контакта или заявки — в том числе при найденном контакте. Ответ содержит error: true, message: "Validation failed" и errors — объект с именами неверных полей и массивами сообщений на английском. Если в списке источников денег есть неизвестное значение, список частично не сохраняется: запрос отклоняется целиком.

#contacts/accreditateAgent

Метод для управления аккредитацией агента или агентства. Используйте опционально, если требуется аккредитовать агента или агентство для работы в Кабинете Агента MACRO

В запрос передаются:

  • id — ID контакта с ролью agent или agent_org,
  • accreditation — true, чтобы аккредитовать контакт, или false, чтобы снять аккредитацию.

Контакт должен быть найден в компании застройщика или среди связанных партнёрских компаний и должен иметь агентскую роль. Если контакт не найден или не подходит по роли, API вернёт ошибку.