Документация MACRO

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. Вы создаёте в системе MACRO API-ключКомпания — API-ключи для агрегатора и включаете нужные действия

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

⚠️ Поиск выполняется среди контактов компании застройщика и связанных партнёрских компаний. API возвращает один найденный контакт. Если контакт не будет найден, метод вернёт ошибку «Agent not found».

#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 вернёт ошибку.