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/create и указывает подходящую роль (агент или агентство недвижимости)
    • При необходимости отдельным запросом /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.

#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 — ИНН
  • comm_ogrn — ОГРН
  • comm_kpp — КПП
  • comm_address — юридический адрес

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

#estateBuy/create

При создании заявки укажите в её методеПереход на внешний сайтhttps://api.macroserver.ru/docs/api/v2/#tag/EstateBuy/operation/estateBuy/create поля:

  • contacts_aggregator_id — ID контакта юридического лица с ролью «Агрегатор», который инициирует создание заявки
  • contacts_agency_id — ID контакта юридического лица с ролью «Агентство недвижимости»
  • contacts_mediator_id — ID контакта физического лица с ролью «Агент»

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

#contacts/accreditateAgent

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

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

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

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