API Documentation¶

Base URL: http://localhost:8000 (development) Production URL: https://api.silent-meadow.ru

Все endpoints требуют аутентификации (кроме /auth/login и /health).

Authentication¶

Получить JWT токен для доступа к API.

POST /v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your_password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 1800
}

Использование токена:

GET /v1/properties
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Properties API¶

Get All Properties¶

Получить список всех участков с фильтрацией и пагинацией.

GET /v1/properties?status=available&min_price=200000&max_price=500000&page=1&per_page=20
Authorization: Bearer {token}

Query Parameters:

Parameter	Type	Description	Example
`status`	string	Фильтр по статусу	`available`, `reserved`, `sold`
`settlement`	string	Фильтр по поселку	`Тихие Луга`, `Мечтаево`
`min_price`	integer	Минимальная цена	`200000`
`max_price`	integer	Максимальная цена	`500000`
`min_area`	float	Минимальная площадь (соток)	`8`
`max_area`	float	Максимальная площадь (соток)	`15`
`page`	integer	Номер страницы	`1`
`per_page`	integer	Кол-во на странице	`20`

Response:

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "number": "502",
      "cadastral_number": "50:18:0090613:670",
      "area_sotok": 10.0,
      "price": 299000,
      "original_price": 389000,
      "status": "available",
      "latitude": 55.523456,
      "longitude": 36.234567,
      "settlement": "Тихие Луга",
      "description": "Участок с хорошим расположением",
      "images": [
        "https://cdn.silent-meadow.ru/properties/502-1.jpg",
        "https://cdn.silent-meadow.ru/properties/502-2.jpg"
      ],
      "created_at": "2026-02-10T12:00:00Z",
      "updated_at": "2026-02-15T18:30:00Z"
    }
  ],
  "total": 436,
  "page": 1,
  "per_page": 20,
  "pages": 22
}

Get Property by ID¶

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

GET /v1/properties/{property_id}
Authorization: Bearer {token}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "number": "502",
  "cadastral_number": "50:18:0090613:670",
  "area_sotok": 10.0,
  "price": 299000,
  "original_price": 389000,
  "status": "available",
  "latitude": 55.523456,
  "longitude": 36.234567,
  "settlement": "Тихие Луга",
  "description": "Участок с хорошим расположением",
  "images": ["..."],
  "created_at": "2026-02-10T12:00:00Z",
  "updated_at": "2026-02-15T18:30:00Z"
}

Create Property¶

Создать новый участок.

POST /v1/properties
Authorization: Bearer {token}
Content-Type: application/json

{
  "number": "503",
  "cadastral_number": "50:18:0090613:671",
  "area_sotok": 12.5,
  "price": 350000,
  "original_price": 450000,
  "status": "available",
  "latitude": 55.523460,
  "longitude": 36.234570,
  "settlement": "Тихие Луга",
  "description": "Участок угловой",
  "images": [
    "https://cdn.silent-meadow.ru/properties/503-1.jpg"
  ]
}

Response: 201 Created

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "number": "503",
  "cadastral_number": "50:18:0090613:671",
  ...
}

Update Property¶

Обновить информацию об участке.

PATCH /v1/properties/{property_id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "status": "reserved",
  "price": 280000
}

Response: 200 OK

Delete Property¶

Удалить участок.

DELETE /v1/properties/{property_id}
Authorization: Bearer {token}

Response: 204 No Content

Houses API¶

Get All Houses¶

Получить каталог домов.

GET /v1/houses?type=shale&min_area=60&max_area=120
Authorization: Bearer {token}

Query Parameters:

Parameter	Type	Description	Example
`type`	string	Тип дома	`shale`, `barnhouse`, `hi_tech`
`min_area`	integer	Минимальная площадь (м²)	`60`
`max_area`	integer	Максимальная площадь (м²)	`120`

Response:

{
  "items": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "name": "Шале",
      "type": "shale",
      "area_sqm": 60,
      "price_economy": 2500000,
      "price_comfort": 3200000,
      "description": "Современный дом в стиле Шале",
      "floor_plan_url": "https://cdn.silent-meadow.ru/houses/shale-60-plan.pdf",
      "images": [
        "https://cdn.silent-meadow.ru/houses/shale-60-1.jpg",
        "https://cdn.silent-meadow.ru/houses/shale-60-2.jpg"
      ],
      "features": {
        "bedrooms": 2,
        "bathrooms": 1,
        "floors": 2,
        "has_terrace": true
      },
      "created_at": "2026-02-01T10:00:00Z",
      "updated_at": "2026-02-01T10:00:00Z"
    }
  ],
  "total": 9
}

Create House¶

Добавить новый тип дома.

POST /v1/houses
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Барнхаус",
  "type": "barnhouse",
  "area_sqm": 80,
  "price_economy": 3500000,
  "price_comfort": 4200000,
  "description": "Современный барнхаус",
  "features": {
    "bedrooms": 3,
    "bathrooms": 2,
    "floors": 1
  }
}

Response: 201 Created

Avito API¶

Connect Avito Account¶

Инициировать OAuth2 flow для подключения Avito.

POST /v1/avito/auth
Authorization: Bearer {token}

Response:

{
  "auth_url": "https://avito.ru/oauth?client_id=...&redirect_uri=..."
}

Примечание: Пользователь должен перейти по auth_url, авторизоваться, и будет перенаправлен на callback.

Get Auth Status¶

Проверить статус подключения к Avito.

GET /v1/avito/auth/status
Authorization: Bearer {token}

Response:

{
  "connected": true,
  "user_id": "12345678",
  "username": "user@example.com",
  "expires_at": "2026-03-01T12:00:00Z"
}

Create Avito Ad¶

Создать объявление на Avito.

POST /v1/avito/ads
Authorization: Bearer {token}
Content-Type: application/json

{
  "property_id": "550e8400-e29b-41d4-a716-446655440000",
  "house_id": null,
  "title": "Участок 10 соток в ДНП Тихие Луга, 30 км от МКАД",
  "description": "Продается земельный участок 10 соток в живописном поселке Тихие Луга. Электричество подведено, газ по границе. Рядом лес, река. Отличное место для строительства дома.",
  "price": 299000
}

Response: 201 Created

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "property_id": "550e8400-e29b-41d4-a716-446655440000",
  "avito_ad_id": "2876543210",
  "title": "Участок 10 соток...",
  "status": "draft",
  "views": 0,
  "contacts": 0,
  "created_at": "2026-02-16T15:00:00Z"
}

Publish Avito Ad¶

Опубликовать объявление на Avito.

POST /v1/avito/ads/{ad_id}/publish
Authorization: Bearer {token}

Response:

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "status": "active",
  "published_at": "2026-02-16T15:05:00Z",
  "expires_at": "2026-03-18T15:05:00Z"
}

Get Avito Chats¶

Получить список чатов с покупателями.

GET /v1/avito/chats?unread_only=true
Authorization: Bearer {token}

Response:

{
  "chats": [
    {
      "id": "990e8400-e29b-41d4-a716-446655440004",
      "avito_chat_id": "chat_12345",
      "ad_id": "880e8400-e29b-41d4-a716-446655440003",
      "buyer_name": "Иван",
      "last_message": "Здравствуйте, участок еще актуален?",
      "last_message_at": "2026-02-16T16:30:00Z",
      "unread_count": 1
    }
  ]
}

Send Message to Avito Chat¶

Отправить сообщение покупателю в Avito.

POST /v1/avito/chats/{chat_id}/message
Authorization: Bearer {token}
Content-Type: application/json

{
  "message": "Здравствуйте! Да, участок актуален. Можем организовать просмотр в удобное для вас время."
}

Response:

{
  "success": true,
  "message_id": "msg_67890",
  "sent_at": "2026-02-16T16:35:00Z"
}

Telegram API¶

Get Telegram Leads¶

Получить лиды из Telegram с AI-оценкой.

GET /v1/telegram/leads?min_score=7&status=new&page=1&per_page=20
Authorization: Bearer {token}

Query Parameters:

Parameter	Type	Description
`min_score`	float	Минимальная AI-оценка (0-10)
`status`	string	`new`, `contacted`, `qualified`, `won`, `lost`
`property_id`	uuid	Фильтр по участку
`house_id`	uuid	Фильтр по дому
`page`	integer	Номер страницы

Response:

{
  "items": [
    {
      "id": "aa0e8400-e29b-41d4-a716-446655440005",
      "project_id": "bb0e8400-e29b-41d4-a716-446655440006",
      "name": "Иван",
      "telegram_username": "@ivan_petrov",
      "phone": null,
      "message": "Ищу участок в Подмосковье до 500К, желательно с электричеством. Рассматриваю варианты до 50 км от МКАД.",
      "score": 8.5,
      "source": "telegram",
      "property_id": null,
      "house_id": null,
      "status": "new",
      "created_at": "2026-02-16T14:20:00Z"
    }
  ],
  "total": 47,
  "page": 1,
  "per_page": 20
}

Add Telegram Group for Monitoring¶

Добавить группу для парсинга.

POST /v1/telegram/groups
Authorization: Bearer {token}
Content-Type: application/json

{
  "group_url": "https://t.me/nedvizhimost_mo",
  "project_id": "bb0e8400-e29b-41d4-a716-446655440006"
}

Response:

{
  "id": "cc0e8400-e29b-41d4-a716-446655440007",
  "group_url": "https://t.me/nedvizhimost_mo",
  "group_name": "Недвижимость МО",
  "members_count": 12450,
  "status": "active",
  "added_at": "2026-02-16T17:00:00Z"
}

Send CRM Notification¶

Отправить уведомление менеджеру в Telegram.

POST /v1/telegram/crm/notify
Authorization: Bearer {token}
Content-Type: application/json

{
  "lead_id": "aa0e8400-e29b-41d4-a716-446655440005",
  "manager_chat_id": "123456789",
  "message": "Новый лид с высоким score (8.5). Срочно свяжитесь!"
}

Response:

{
  "success": true,
  "message_id": 54321,
  "sent_at": "2026-02-16T17:05:00Z"
}

Yandex Maps API¶

Get Properties GeoJSON¶

Получить все участки в формате GeoJSON для отображения на карте.

GET /v1/map/properties?status=available
Authorization: Bearer {token}

Response:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [36.234567, 55.523456]
      },
      "properties": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "number": "502",
        "price": 299000,
        "status": "available",
        "area_sotok": 10.0,
        "settlement": "Тихие Луга"
      }
    }
  ]
}

Get Clusters¶

Получить кластеры участков для определенного уровня zoom.

GET /v1/map/clusters?zoom=12&bounds=55.5,36.2,55.6,36.3
Authorization: Bearer {token}

Response:

{
  "clusters": [
    {
      "coordinates": [36.234567, 55.523456],
      "count": 15,
      "properties": {
        "avg_price": 325000,
        "settlement": "Тихие Луга"
      }
    }
  ]
}

Geocode Address¶

Преобразовать адрес в координаты.

GET /v1/map/geocode?address=Можайск,%20ДНП%20Тихие%20Луга
Authorization: Bearer {token}

Response:

{
  "address": "Можайск, ДНП Тихие Луга",
  "latitude": 55.523456,
  "longitude": 36.234567,
  "precision": "street"
}

Error Responses¶

Все ошибки возвращаются в стандартном формате:

{
  "error": {
    "code": "PROPERTY_NOT_FOUND",
    "message": "Property with id 550e8400-e29b-41d4-a716-446655440000 not found",
    "details": null
  }
}

HTTP Status Codes¶

Code	Description
`200`	OK - запрос выполнен успешно
`201`	Created - ресурс создан
`204`	No Content - ресурс удален
`400`	Bad Request - некорректные данные
`401`	Unauthorized - не авторизован
`403`	Forbidden - доступ запрещен
`404`	Not Found - ресурс не найден
`422`	Unprocessable Entity - ошибка валидации
`429`	Too Many Requests - превышен rate limit
`500`	Internal Server Error - ошибка сервера

Rate Limiting¶

API ограничивает количество запросов:

Авторизованные запросы: 100 req/min
Неавторизованные запросы: 20 req/min

Headers в ответе:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1708099200

Webhooks¶

Avito Webhook¶

Avito отправляет уведомления о новых сообщениях.

POST /v1/avito/webhook
X-Avito-Signature: sha256=...
Content-Type: application/json

{
  "type": "message.new",
  "chat_id": "chat_12345",
  "message": {
    "id": "msg_67890",
    "text": "Здравствуйте, участок еще актуален?",
    "from": {
      "name": "Иван"
    },
    "created_at": "2026-02-16T16:30:00Z"
  }
}

Response: 200 OK

Postman Collection¶

Импортируйте коллекцию для быстрого тестирования API:

curl -o silent-meadow.postman_collection.json \
  https://silent-meadow.ru/api/postman-collection.json

Или используйте интерактивную документацию:

Swagger UI: http://localhost:8000/docs ReDoc: http://localhost:8000/redoc

SDK (планируется)¶

Python SDK¶

from silent_meadow import SilentMeadowClient

client = SilentMeadowClient(api_key="your_api_key")

# Get properties
properties = await client.properties.list(status="available", min_price=200000)

# Create Avito ad
ad = await client.avito.create_ad(
    property_id="550e8400-e29b-41d4-a716-446655440000",
    title="Участок 10 соток...",
    price=299000
)

TypeScript SDK¶

import { SilentMeadowClient } from "@silent-meadow/sdk";

const client = new SilentMeadowClient({ apiKey: "your_api_key" });

// Get properties
const properties = await client.properties.list({
  status: "available",
  minPrice: 200000,
});

// Create Avito ad
const ad = await client.avito.createAd({
  propertyId: "550e8400-e29b-41d4-a716-446655440000",
  title: "Участок 10 соток...",
  price: 299000,
});

API Version: v1 Last Updated: 2026-02-16 Maintained by: Silent Meadow Team

Для вопросов и поддержки создайте issue в GitHub репозитории.

API Documentation¶

Authentication¶

Login¶

Properties API¶

Get All Properties¶

Get Property by ID¶

Create Property¶

Update Property¶

Delete Property¶

Houses API¶

Get All Houses¶

Create House¶

Avito API¶

Connect Avito Account¶

Get Auth Status¶

Create Avito Ad¶

Publish Avito Ad¶

Get Avito Chats¶

Send Message to Avito Chat¶

Telegram API¶

Get Telegram Leads¶

Add Telegram Group for Monitoring¶

Send CRM Notification¶

Yandex Maps API¶

Get Properties GeoJSON¶

Get Clusters¶

Geocode Address¶

Error Responses¶

HTTP Status Codes¶

Rate Limiting¶

Webhooks¶

Avito Webhook¶

Postman Collection¶

SDK (планируется)¶

Python SDK¶

TypeScript SDK¶