1. Служебная информация

Заказчик: Ткаченко Алексей
Продакт: 
Бизнес-аналитик: Николаев Николай Евгеньевич 
Руководитель IT-проекта: Бугакова Елизавета
Дата создания: 04.12.2025

Глоссарий

ЛК АН — Личный кабинет агента недвижимости.
ТрендАгент (ТА) — агрегатор/платформа, через которую агентства подают заявки.
Фиксация клиента — процесс проверки уникальности клиента по телефону и фиксация его за агентом.
Уникальность — возможность агента работать с клиентом и получать комиссионные от Догмы.
API фиксации — точка интеграции для проверки и фиксации клиента, описанная в файле спецификации.
ООО «Платформа Юг» — юрлицо, под которым ТрендАгент заведен в ЛК АН.

2. Контекст и цели

2.1. Описание проблемы

Сейчас проверка уникальности клиента выполняется вручную: сотрудник ТрендАгент каждый раз заносит данные в ЛК АН, ожидает ответ и вручную возвращает результат в свою систему, что приводит к высокой нагрузке, задержкам, ошибкам и негативному опыту агентов.

2.2. Цель

Автоматизировать процесс проверки уникальности и фиксации клиентов между ТрендАгент и ЛК АН, чтобы агенты могли самостоятельно и быстро выполнять эти операции прямо в личном кабинете ТрендАгента, с возможностью масштабирования на все регионы и корректной обработкой промежуточных статусов.

3. Зависимости, ограничения и риски

3.1. Зависимости и интеграции

• API интеграция фиксации ТрендАгент.
  TrendAgent интеграция.pdf

• ЛК ТрендАгент: инициатор запросов.

• Внутренние модули Догма:

  • механизм проверки уникальности;

  • модуль фиксации клиента;

  • модуль ручной проверки менеджерами;

  • бизнес-правила расчёта сроков фиксации.

• Служба безопасности Dogma — должна одобрить интеграцию внешнего сервиса (ограничения на API-доступ).

3.2. Ограничения и риски

• Регуляторика: передача персональных данных (ФИО, телефон) → требования 152-ФЗ.

• СБ может не пропустить интеграцию стороннего API в ЛКН.

• В Dogma используется логика ручной модерации при неоднозначной уникальности — может противоречить ожиданию «моментального ответа».

• Ограничения по лимитам запросов от ТА (анти-DDOS / защита от массовых поисков клиентов).

• Возможна необходимость тестового API-окружения (у Dogma может отсутствовать готовый sandbox).

• Плавающие сроки фиксации в текущей логике — но для категории «агрегатор» логика иная → требуется подтверждение.

4. Модели процессов

4.1. Процесс AS IS (кратко)

1. Агент отправляет заявку в ТрендАгент.

2. Оператор ТА вручную заполняет данные в ЛК Dogma.

3. ЛК Dogma возвращает результат (уникален/неуникален/на ручную проверку).

4. Оператор ТА вручную переносит ответ в систему ТА.

5. Агент получает решение.

4.2. Процесс TO BE

1. Агент отправляет заявку в ТрендАгент.

2. ТА автоматически формирует запрос к API Dogma /clients/fixation.

3. Dogma:

   • выполняет автоматическую проверку телефона;

   • если однозначно → возвращает «unique = true/false» и срок фиксации;

   • если случай неоднозначный → формирует промежуточный статус для ручной модерации.

4. ТА получает ответ API и отображает его агенту.

5. При статусе «ручная проверка» ТА должен периодически запрашивать актуальный статус (нужен отдельный endpoint или webhook — требуется уточнение).

5. Бизнес-требования

5.1. Пользовательские истории (US)

1. Как агент, я хочу в интерфейсе ТрендАгент мгновенно проверять уникальность клиента, чтобы понимать, могу ли я работать с ним.

2. Как оператор ТА, я хочу избавиться от ручного ввода в ЛК Dogma, чтобы избежать ошибок и ускорить обработку лидов.

3. Как менеджер Dogma, я хочу получать только те лиды, которые требуют ручной модерации, чтобы не тратить время на простые проверки.

4. Как продакт Dogma, я хочу контролировать объём и параметры входящих запросов от ТА, чтобы исключить злоупотребления и нагрузки на API.

5.2. Функциональные требования

FR1. Автоматическая проверка уникальности

• ТА должен отправлять POST-запрос /clients/fixation с параметрами:

  • name, surname, middle_name (если обязательны), phone, city.

• Dogma должна возвращать JSON-ответ согласно спецификации.

FR2. Обработка статусов

• Если unique = true → вернуть срок фиксации (status_valid).

• Если unique = false → вернуть комментарий.

• Если требуется ручная проверка → вернуть промежуточный статус (формат уточнить).

FR3. Аутентификация

• Dogma предоставляет ТА токен авторизации для вызова API.

FR4. Ограничения запросов

• API Dogma должен ограничивать число обращений от ТА (лимиты, anti-flood).

FR5. Логирование запросов

• В Dogma должны сохраняться:

  • входящий payload,

  • результаты проверки,

  • ошибки,

  • идентификатор агента/юрлица «Платформа Юг».

FR6. Ошибки

• Dogma должна возвращать корректные коды:

  • 4xx — ошибки валидации (например, некорректный телефон)

  • 5xx — системные ошибки

FR7. Поддержка ручной модерации

• Если по логике Dogma требуется ручная проверка, API должен предусматривать:

  • либо промежуточный статус в ответе,

  • либо механизм последующего получения результата.

5.3. Нефункциональные требования

• Время ответа API Dogma: ≤ X секунд (уточнить).

• Доступность API: не ниже 99% (уточнить).

• Защита данных согласно 152-ФЗ.

• Ограничение количества запросов в минуту (rate limit — определить).

• Логирование не менее N дней (уточнить).

5.4. Критерии приемки

1. При запросе от ТА API возвращает корректный статус уникальности.

2. В ЛК Dogma корректно фиксируется лид, созданный ТА.

3. Ручные проверки корректно обрабатываются и возвращаются ТА.

4. Сотрудник ТА полностью не участвует в проверке уникальности.

5. Тестовое окружение успешно пройдено.

6. СБ дает официальное разрешение на доступ к API.

6. Интерфейсы

• API Dogma — конечная точка /clients/fixation (из спецификации).

• Интерфейс ТрендАгент — форма подачи заявки и отображение результата проверки.

• Интерфейс ЛК Dogma — карточка клиента, статусы фиксации.

7. Артефакты

• Спецификация API фиксации клиента ТрендАгент (PDF)

  TrendAgent интеграция

• Запись встречи (текст протокола).

• Бизнес-логика проверки уникальности в Dogma (внутренний документ — необходимо получить).

Блок 2 — Список уточняющих вопросов

К бизнесу Dogma

1. Какие SLA считаются приемлемыми для API проверки уникальности (время ответа)?

2. Требуется ли поддержка промежуточного статуса для ручной модерации через API? Как должен выглядеть ответ API в таких случаях?

3. Нужен ли механизм получения статуса вручную проверяемых лидов (pull или webhook)?

4. Как должен вести себя API, если сервис уникальности временно недоступен?

5. Нужно ли ограничивать количество запросов от ТрендАгент? Какие лимиты?

6. Каков срок хранения логов API?

7. Нужно ли выводить историю проверок со стороны ТА в ЛК Dogma?

К ТрендАгент

1. Обязательны ли для передачи все поля ФИО или можно ограничиться phone + name?

2. Как отображается статус «ожидает ручной проверки» в интерфейсе ТА?

3. Нужно ли агенту возвращать финальный статус автоматически или по запросу?

К архитектору / разработке Dogma

1. Есть ли тестовое API-окружение или его нужно создать?

2. Существуют ли ограничения на интеграцию внешних сервисов в ЛК агент?

3. Какой формат должен быть у токена для ТА?

4. Как будет идентифицироваться юрлицо «Платформа Юг» при фиксации?

5. Как обрабатывается логика «агрегатор» — действительно ли фиксированный срок фиксации и отсутствие плавающих параметров?

К службе безопасности

1. Какие требования предъявляются к внешним интеграциям (IP whitelist, VPN, frequency limits)?

2. Можно ли ТА получить доступ к боевому API напрямую или потребуется шлюз?

3. Требуется ли заключения DPA (договор на обработку персональных данных)?