Справочник API Endpoints

​

Краткое введение в API

Команда: "Дай мне список всех моих чатов"
↓
API endpoint: GET /api/chats
↓
Система: "Вот твои чаты: Марина, Иван, Светлана"

​

1. Аутентификация и верификация

​

1.1 Регистрация по номеру телефона

• phone — номер телефона (например: +7 999 123-45-67)
• magic_link — опционально, пригласительная ссылка (если человек регистрируется по ссылке)

• Система проверяет номер телефона
• Если это новый номер → создаёт нового пользователя
• Если номер уже есть → находит существующего пользователя
• Переводит на следующий этап: отправка SMS кода

• Система говорит: “OK, готово к отправке кода”
• Пользователь переходит к вводу кода

• Неправильный формат номера → “Введите корректный номер”
• Номер забанен → “Этот номер больше не может входить”

​

1.2 Отправка SMS кода

• phone — номер телефона (пользователь должен указать номер, по которому хочет регистрироваться)

• Система проверяет, существует ли пользователь с этим номером
• Генерирует случайный 4-значный код (например: 7382)
• Отправляет SMS: “Ваш код для входа в Chat Bridge: 7382”
• Запоминает код и ставит срок действия (5 минут)

• SMS отправлена, пользователь должен её получить в течение 30 секунд
• Пользователь вводит код, который получил

• Номер не найден → “Пользователь с этим номером не найден” (если это не первая регистрация)
• SMS сервис не работает → “Не удалось отправить SMS, попробуйте позже”
• Слишком много попыток → “Вы запросили слишком много кодов, подождите”

​

1.3 Верификация кода и получение токена

• phone — номер телефона
• code — 4-значный код из SMS

• Система проверяет:
  • Код совпадает? ✓
  • Код не истёк (прошло < 5 минут)? ✓
  • Код ещё не использован? ✓
• Если всё OK:
  • Отмечает пользователя как “верифицированный”
  • Генерирует уникальный API токен (длинная строка вроде: abcd1234efgh5678ijkl9012)
  • Возвращает этот токен

• Пользователь получает токен доступа
• Теперь может выполнять другие команды (создавать компании, смотреть чаты и т.д.)
• Токен нужно хранить в безопасности (как пароль)

• Код неправильный → “Неверный код, попробуйте ещё раз”
• Код истёк → “Код больше не действителен, запросите новый”
• Код уже использован → “Этот код уже был использован”

​

2. Профиль пользователя

​

2.1 Получить информацию о себе

• Нужен: API токен (пользователь должен быть авторизован)

• Система по токену находит пользователя
• Собирает информацию о пользователе
• Загружает его текущую компанию (в которой он сейчас работает)

• Система возвращает:
  • Имя, фамилия
  • Номер телефона
  • Фото (если загружено)
  • Дата регистрации
  • Дата последнего входа
  • Текущая компания (ID, название, ваша роль)

{
  "id": "user123",
  "first_name": "Иван",
  "last_name": "Иванов",
  "phone": "+7 999 123-45-67",
  "is_verified": true,
  "current_company": {
    "id": "company456",
    "name": "Иванов и партнёры",
    "role": "MAINTAINER"
  }
}

• Токен неверный/истёк → “Авторизуйтесь заново”

​

3. Управление компаниями

​

3.1 Получить список моих компаний

• Нужен: API токен

• Система находит все компании пользователя
• Для каждой компании собирает:
  • Название
  • Статус (NEW, WAITING_FOR…, COMPLETED и т.д.)
  • Роль пользователя в компании (MAINTAINER, RESPONSIBLE, MANAGER)
  • Дата создания
  • Количество пользователей
  • Подключённые платформы (Avito, Cian, Domclick)

• Список всех компаний пользователя

[
  {
    "id": "company1",
    "name": "Иванов и партнёры",
    "status": "COMPLETED",
    "role": "MAINTAINER",
    "users_count": 5,
    "platforms": ["avito", "cian", "domclick"],
    "created_at": "2025-01-10"
  },
  {
    "id": "company2",
    "name": "Квартирка",
    "status": "WAITING_FOR_AVITO_ACCESS",
    "role": "MANAGER",
    "users_count": 2,
    "platforms": ["avito"],
    "created_at": "2025-01-12"
  }
]

​

3.2 Создать новую компанию

• Нужен: API токен
• Обязательно:
  • name — название компании (например: “Квартира на ул. Пушкина”)
• Опционально:
  • legal_address — юридический адрес
  • inn — ИНН (10 или 12 цифр)
  • ogrn — ОГРН/ОГРНИП (15 цифр)
  • bank_name — название банка
  • checking_account — расчётный счёт (20 цифр)
  • correspondent_account — корреспондентский счёт (20 цифр)
  • bik — БИК банка

• Система создаёт компанию
• Устанавливает статус: WAITING_FOR_PROVIDER_SELECTION (нужно выбрать платформы)
• Добавляет создателя в компанию с ролью MAINTAINER (владелец)
• Готово для следующего шага: выбор платформ

• Компания создана
• Пользователь становится её владельцем
• Может начать настройку интеграций

{
  "name": "Риэлторское агентство Иванова",
  "legal_address": "г. Москва, ул. Пушкина, д. 10",
  "inn": "7701234567"
}

• Название пусто или слишком длинное → “Введите корректное название”
• ИНН неправильный формат → “ИНН должен быть 10 или 12 цифр”
• ОГРН неправильный формат → “ОГРН должен быть 15 цифр”

​

3.3 Получить данные компании

• Нужен: API токен
• Нужно: ID компании

• Система проверяет: есть ли у вас доступ к этой компании?
• Если да → показывает всю информацию
• Если нет → ошибка “У вас нет доступа”

• Название компании
• Юридические реквизиты
• Текущий статус
• Подключённые платформы
• Список пользователей в компании (если у вас есть права)
• Дата создания

{
  "id": "company1",
  "name": "Иванов и партнёры",
  "status": "COMPLETED",
  "legal_address": "г. Москва, ул. Пушкина, д. 10",
  "inn": "7701234567",
  "ogrn": "102700009000",
  "use_avito": true,
  "use_cian": true,
  "use_domclick": false,
  "users": [
    {
      "id": "user1",
      "name": "Иван Иванов",
      "role": "MAINTAINER"
    },
    {
      "id": "user2",
      "name": "Петр Петров",
      "role": "MANAGER"
    }
  ]
}

​

3.4 Обновить данные компании

• Нужен: API токен
• Нужна: роль MAINTAINER (только владельцы могут менять)
• Нужен: ID компании
• Опционально (любые поля можно менять):
  • name — новое название
  • legal_address — новый адрес
  • inn, ogrn, bank_name — новые реквизиты
  • И т.д.

• Система проверяет: у вас роль MAINTAINER? ✓
• Обновляет указанные поля
• Сохраняет изменения

• Данные компании обновлены

• У вас нет роли MAINTAINER → “У вас недостаточно прав для этого действия”
• Неправильный формат данных → “Проверьте корректность введённых данных”

​

3.5 Удалить компанию

• Нужен: API токен
• Нужна: роль MAINTAINER
• Нужен: ID компании

• Система проверяет: у вас роль MAINTAINER? ✓
• Удаляет компанию (на самом деле “помечает как удалённую” — данные не теряются, просто скрываются)
• Все объявления и чаты компании становятся недоступными

• Компания удалена из вашего списка
• Она больше не видна
• Все сотрудники теряют доступ к компании

• Роль не MAINTAINER → “Только владельцы могут удалить компанию”

​

4. Пригласительные ссылки (Magic Links)

​

4.1 Получить список пригласительных ссылок

• Нужен: API токен
• Нужна: роль MAINTAINER или RESPONSIBLE

• Система находит все ссылки, созданные для вашей компании
• Собирает информацию о каждой ссылке:
  • Уникальный токен (для отправки людям)
  • Роль, которую получит новый пользователь
  • Максимальное количество использований
  • Текущее количество использований
  • Дата истечения
  • Кто создал ссылку

• Список всех активных ссылок

[
  {
    "id": "link1",
    "token": "abc123def456ghi789jkl012",
    "role": "MANAGER",
    "max_uses": 5,
    "current_uses": 2,
    "expires_at": "2025-02-10",
    "created_by": "Иван Иванов"
  },
  {
    "id": "link2",
    "token": "xyz987wvu654tsrq321opn",
    "role": "RESPONSIBLE",
    "max_uses": 1,
    "current_uses": 0,
    "expires_at": "2025-01-25",
    "created_by": "Иван Иванов"
  }
]

​

4.2 Создать новую пригласительную ссылку

• Нужен: API токен
• Нужна: роль MAINTAINER или RESPONSIBLE
• Обязательно:
  • role — роль для новых пользователей (MAINTAINER, RESPONSIBLE, MANAGER)
• Опционально:
  • max_uses — максимальное количество использований ссылки (по умолчанию: бесконечно)
  • expires_at — дата истечения ссылки (по умолчанию: бесконечно)

• Система генерирует уникальную ссылку (32 символа, вроде: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6)
• Сохраняет её с указанными ограничениями
• Готово для распределения

• Новая ссылка создана
• Можно отправить людям через WhatsApp, Email, SMS и т.д.

{
  "role": "MANAGER",
  "max_uses": 5,
  "expires_at": "2025-02-15"
}

https://chat-bridge.app/join/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

• Роль неизвестна → “Выберите корректную роль”
• Дата в прошлом → “Дата истечения должна быть в будущем”
• Максимальное количество ссылок → “Вы создали слишком много ссылок”

​

4.3 Проверить валидность ссылки

• Нужен: API токен
• Нужен: токен ссылки (те 32 символа)

• Система проверяет:
  • Ссылка существует? ✓
  • Ссылка не удалена? ✓
  • Дата не истекла? ✓
  • Лимит использований не превышен? ✓
• Если всё OK → говорит “Ссылка валидна”
• Если что-то не так → говорит почему ссылка не работает

• Если OK: информация о компании и роль, которую получит новый пользователь
• Если не работает: описание проблемы

• Ссылка не найдена → “Ссылка не существует”
• Ссылка истекла → “Ссылка уже истекла”
• Превышен лимит использований → “Максимальное количество участников по этой ссылке достигнуто”

​

4.4 Удалить пригласительную ссылку

• Нужен: API токен
• Нужна: роль MAINTAINER или RESPONSIBLE
• Нужен: ID ссылки

• Система удаляет ссылку
• Ссылка больше не работает
• Люди, которые уже присоединились по этой ссылке, остаются в компании

• Ссылка удалена

Ссылка была: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Вы удаляете её
↓
Людям, которые попытаются присоединиться, будет ошибка:
"Эта ссылка больше не действительна"
↓
Но люди, которые уже присоединились, остаются в компании

​

5. Интеграция с Avito

​

5.1 Генерировать ссылку для авторизации

• Нужен: API токен
• Нужна: роль MAINTAINER

• Система генерирует специальную ссылку на сайт Avito
• Ссылка содержит ID приложения Chat Bridge

• Ссылка на сайт Avito

Система возвращает ссылку вроде:
https://avito.ru/oauth/authorize?client_id=chat-bridge&...

Пользователь нажимает на ссылку
↓
Переходит на Avito
↓
Авторизуется в Avito (если ещё не авторизован)
↓
Avito спрашивает: "Разрешить Chat Bridge доступ к вашему аккаунту?"
↓
Пользователь нажимает "Разрешить"
↓
Avito отправляет код авторизации обратно в Chat Bridge

​

5.2 Получить access token по коду авторизации

• Нужен: API токен
• Нужна: роль MAINTAINER
• Нужен: код авторизации (Avito отправляет его после того, как пользователь нажмёт “Разрешить”)

• Система отправляет код в API Avito
• Avito проверяет код и отправляет обратно access_token и refresh_token
• Система сохраняет токены (в зашифрованном виде)
• Система запоминает дату истечения токена

• Система готова получать объявления и чаты из Avito
• Статус компании меняется на следующий (ждёт ввода XML фида или следующей платформы)

• Код неверный → “Код авторизации не распознан”
• Код истёк → “Код авторизации больше не действителен”
• Ошибка на сервере Avito → “Не удалось подключиться к Avito”

​

5.3 Создать/обновить фид объявлений

• Нужен: API токен
• Нужна: роль MAINTAINER
• Обязательно:
  • feed_url — полный URL фида (например: https://mysite.com/feed.xml)

• Система проверяет, что URL доступен (попытается скачать файл)
• Если доступен → сохраняет URL
• Статус компании меняется на следующий (требуется авторизация в Avito)

• URL фида сохранён
• Система знает, где брать объявления
• Позже, при синхронизации, загрузит объявления из этого фида

{
  "feed_url": "https://mysite.com/avito_feed.xml"
}

• URL недоступен → “Не удалось получить доступ к URL”
• URL не XML → “Файл не является валидным XML”
• Формат XML неправильный → “XML имеет неправильный формат”

​

6. Интеграция с Cian

​

6.1 Создать токен Cian

• Нужен: API токен
• Нужна: роль MAINTAINER
• Обязательно:
  • client_secret — токен из личного кабинета Cian (минимум 10 символов)

• Система проверяет токен (делает тестовый запрос в API Cian)
• Если токен работает → сохраняет его (в зашифрованном виде)
• Если токен не работает → возвращает ошибку

• Токен сохранён
• Система может получать чаты из Cian
• Статус компании меняется на следующий

{
  "client_secret": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

• Токен неверный → “Токен не прошёл валидацию”
• Токен истёк → “Токен больше не действителен”
• Токен слишком короткий → “Токен должен быть минимум 10 символов”

​

6.2 Обновить токен Cian

• Нужен: API токен
• Нужна: роль MAINTAINER
• Обязательно:
  • client_secret — новый токен из Cian

• Система проверяет новый токен
• Если работает → заменяет старый токен на новый
• Старый токен удаляется

• Токен обновлён
• Система может продолжать получать данные из Cian

​

7. Интеграция с Domclick

​

7.1 Создать токен Domclick

• Нужен: API токен
• Нужна: роль MAINTAINER
• Обязательно:
  • external_company_id — ID вашей компании в системе Domclick (строка вроде: “12345”)
  • stats_secret — токен для доступа к статистике
  • chats_secret — токен для доступа к чатам

• Система проверяет оба токена отдельно (делает тестовые запросы)
• Если оба токена работают → сохраняет их (в зашифрованном виде)
• Если хоть один не работает → возвращает ошибку

• Оба токена сохранены
• Система может получать чаты из Domclick
• Статус компании меняется на синхронизацию

{
  "external_company_id": "12345",
  "stats_secret": "stats_a1b2c3d4e5f6",
  "chats_secret": "chats_x9y8z7w6v5u4"
}

• stats_secret неверный → “Токен для статистики не прошёл валидацию”
• chats_secret неверный → “Токен для чатов не прошёл валидацию”
• external_company_id не найден → “Компания не найдена в Domclick”

​

7.2 Обновить токен Domclick

• Нужен: API токен
• Нужна: роль MAINTAINER
• Нужны: новые токены (в любой комбинации)

• Система проверяет новые токены
• Если работают → заменяет старые токены
• Если не работают → ошибка

• Токены обновлены
• Система может продолжать работать

​

8. Работа с чатами

​

8.1 Получить список чатов

• Нужен: API токен
• Опционально (все параметры для фильтрации):
  • page — номер страницы (для пагинации)
  • limit — количество чатов на странице (по умолчанию: 20)
  • search — поиск по имени клиента или тексту сообщения
  • last_message_direction — фильтр по направлению (“in” = входящие, “out” = исходящие)
  • is_unread — фильтр “только непрочитанные”
  • is_active — фильтр “только активные”
  • provider_id — фильтр по платформе (1=Avito, 2=Cian, 3=Domclick)

• Система находит все чаты пользователя
• Применяет фильтры (если указаны)
• Сортирует по дате последнего сообщения
• Разбивает на страницы

• Список чатов с информацией:
  • Имя клиента
  • Название объявления
  • Адрес
  • Дата последнего сообщения
  • Статус (прочитан/не прочитан)
  • Платформа (Avito/Cian/Domclick)
  • Количество непрочитанных сообщений

{
  "data": [
    {
      "id": "chat1",
      "client_name": "Марина",
      "ad_title": "Квартира на ул. Пушкина",
      "ad_address": "г. Москва, ул. Пушкина, д. 10, кв. 5",
      "provider": {
        "id": 1,
        "name": "Avito"
      },
      "last_message_text": "Когда можно посмотреть?",
      "last_message_at": "2025-01-14 15:30",
      "is_unread": true,
      "unread_count": 2
    },
    {
      "id": "chat2",
      "client_name": "Иван",
      "ad_title": "2-комнатная квартира",
      "ad_address": "г. Москва, ул. Лермонтова, д. 25",
      "provider": {
        "id": 2,
        "name": "Cian"
      },
      "last_message_text": "Спасибо, заинтересовал",
      "last_message_at": "2025-01-14 10:20",
      "is_unread": false,
      "unread_count": 0
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total": 156,
    "total_pages": 8
  }
}

1. Только непрочитанные чаты:
   /api/chats?is_unread=true

2. Только из Avito:
   /api/chats?provider_id=1

3. Только входящие сообщения + непрочитанные:
   /api/chats?last_message_direction=in&is_unread=true

4. Поиск по имени клиента:
   /api/chats?search=Марина

5. Со страницей и лимитом:
   /api/chats?page=2&limit=50

​

8.2 Получить детали конкретного чата

• Нужен: API токен
• Нужен: ID чата

• Система находит чат
• Проверяет, есть ли у вас доступ к нему
• Собирает всю информацию о чате

• Полная информация о чате:
  • Имя клиента
  • Контакты клиента
  • Информация об объявлении (название, цена, адрес, фото)
  • Информация о менеджере
  • Платформа (Avito/Cian/Domclick)
  • Дата первого и последнего сообщения

{
  "id": "chat1",
  "external_id": "avito_123456",
  "client": {
    "name": "Марина Смирнова",
    "phone": "+7 999 555-66-77"
  },
  "ad": {
    "id": "ad1",
    "title": "Квартира на ул. Пушкина",
    "address": "г. Москва, ул. Пушкина, д. 10, кв. 5",
    "price": 50000,
    "image_url": "https://...",
    "rooms": 2,
    "square": 65.5
  },
  "manager": {
    "id": "user1",
    "name": "Иван Иванов",
    "phone": "+7 999 111-22-33"
  },
  "provider": {
    "id": 1,
    "name": "Avito"
  },
  "messages_total_amount": 5,
  "messages_unread_amount": 2,
  "created_at": "2025-01-12 14:20",
  "updated_at": "2025-01-14 15:30"
}

​

8.3 Получить сообщения конкретного чата

• Нужен: API токен
• Нужен: ID чата
• Опционально:
  • page — номер страницы
  • limit — количество сообщений на странице (по умолчанию: 20)

• Система находит все сообщения в чате
• Сортирует их от старых к новым
• Разбивает на страницы

• Полная история сообщений с информацией:
  • Текст сообщения
  • Тип (текст, фото, файл и т.д.)
  • Направление (входящее/исходящее)
  • Дата и время
  • Статус доставки (отправлено/доставлено/прочитано)

{
  "data": [
    {
      "id": "msg1",
      "chat_id": "chat1",
      "text": "Здравствуйте, квартира ещё в аренде?",
      "type": "Text",
      "direction": "in",
      "is_read": true,
      "created_at": "2025-01-12 14:20",
      "author": "Марина"
    },
    {
      "id": "msg2",
      "chat_id": "chat1",
      "text": "Да, квартира свободна. Когда можете посмотреть?",
      "type": "Text",
      "direction": "out",
      "is_read": true,
      "created_at": "2025-01-12 14:25",
      "author": "Иван"
    },
    {
      "id": "msg3",
      "chat_id": "chat1",
      "text": "Завтра в 18:00?",
      "type": "Text",
      "direction": "in",
      "is_read": false,
      "created_at": "2025-01-14 15:30",
      "author": "Марина"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total": 23,
    "total_pages": 2
  }
}

​

Ограничения и лимиты

​

Автентификация

Authorization: Bearer YOUR_TOKEN_HERE

curl -H "Authorization: Bearer abcd1234efgh5678" \
  https://api.chat-bridge.app/api/chats