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.

#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 — название агентства
  • phones — непустой массив телефонов (в каждом номере минимум 3 цифры)

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

  • roles — массив дополнительных ролей: buyer, partnyor, uchastnik_tenderov. Основную роль agent_org передавать не нужно.
  • emails — массив адресов эл. почты
  • nameFull — ассоциации (ключевые слова для поиска)
  • commFullTitle — краткое название организации
  • commInn — ИНН (10 цифр)
  • 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 — ИНН
  • 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 вернёт ошибку.