{ "openapi": "3.0.0", "info": { "title": "LandLordKeeper API", "description": "REST API for LandLordKeeper - Property Management System.\n\n**Note:** API documentation, examples and Swagger UI are in English only (translations are not supported in OpenAPI specification).\n\n## API Structure\n\n- **01. Authentication** - Login, JWT tokens, Google OAuth\n- **02. User Profile** - Settings, locale, currency preferences\n- **03. Properties** - Property management, documents, counters, expenses, charges, payments, receipts, rental charges, penalties, violations, compensations, assets, negotiations, proposals\n- **04. Contracts** - Rental contracts, agreement blocks, PDF print forms\n- **05. References** - Countries, currencies, languages, property types, expense types, units, document types, tariff zones\n- **06. Service Providers & Contragents** - Service providers, custom contragents\n- **07. Tools** - Health check, translations, Nova Poshta, geolocation, help links\n- **08. Messages** - Property messaging system\n- **09. Calendar** - Calendar events\n- **10. Billing** - Subscriptions, invoices, payment methods\n- **11. Partner Invitations** - Referral program\n", "version": "1.0.0" }, "paths": { "/api/v1/properties/{propertyId}/expenses/refresh-all": { "post": { "tags": [ "03. Properties / Expenses" ], "summary": "Refresh all automatic charges for property", "description": "Generates charges for all active automatic (non-MANUAL) expenses", "operationId": "post_api_property_expenses_refresh_all", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Refresh results", "content": { "application/json": { "schema": { "properties": { "created": { "type": "integer" }, "skipped": { "type": "integer" }, "errors": { "type": "integer" } }, "type": "object" } } } }, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/agreement-blocks": { "get": { "tags": [ "04. Contracts / Agreement Blocks" ], "summary": "List all agreement blocks", "description": "Returns list of all agreement blocks (contract conditions) with their codes, data types, country and translations. Can be filtered by country code. No authentication required.", "operationId": "get_api_agreement_blocks_list", "parameters": [ { "name": "country", "in": "query", "description": "Filter by country code (e.g., UA, US, DE). If not specified, returns all blocks.", "required": false, "schema": { "type": "string", "example": "UA" } } ], "responses": { "200": { "description": "List of agreement blocks", "content": { "application/json": { "schema": { "properties": { "agreement_blocks": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "MONTHLY_RENT_AMOUNT" }, "data_type": { "type": "string", "example": "float", "enum": [ "int", "float", "bool", "text", "date" ] }, "country": { "properties": { "code": { "type": "string", "example": "UA" }, "name": { "type": "object", "additionalProperties": { "type": "string" } } }, "type": "object", "nullable": true }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "additionalProperties": { "type": "string" } }, "image_url": { "type": "string", "example": "https://example.com/agreement_block/1.svg", "nullable": true }, "is_system": { "type": "boolean", "example": true }, "sort_order": { "type": "integer", "example": 0 } }, "type": "object" } }, "country_filter": { "type": "string", "example": "UA", "nullable": true }, "total": { "type": "integer", "example": 21 } }, "type": "object" } } } } } } }, "/api/v1/agreement-blocks/{code}": { "get": { "tags": [ "04. Contracts / Agreement Blocks" ], "summary": "Get agreement block by code", "description": "Returns agreement block details by code including country", "operationId": "get_api_agreement_blocks_show", "parameters": [ { "name": "code", "in": "path", "description": "Agreement block code (e.g., MONTHLY_RENT_AMOUNT, DEPOSIT_MONTHS)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agreement block details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "MONTHLY_RENT_AMOUNT" }, "data_type": { "type": "string", "example": "float", "enum": [ "int", "float", "bool", "text", "date" ] }, "country": { "properties": { "code": { "type": "string", "example": "UA" }, "name": { "type": "object", "additionalProperties": { "type": "string" } } }, "type": "object", "nullable": true }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "additionalProperties": { "type": "string" } }, "image_url": { "type": "string", "example": "https://example.com/agreement_block/1.svg", "nullable": true }, "is_system": { "type": "boolean", "example": true }, "sort_order": { "type": "integer", "example": 0 } }, "type": "object" } } } }, "404": { "description": "Agreement block not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Agreement block not found" } }, "type": "object" } } } } } } }, "/api/v1/agreement-blocks/by-type/{dataType}": { "get": { "tags": [ "04. Contracts / Agreement Blocks" ], "summary": "Get agreement blocks by data type", "description": "Returns list of agreement blocks filtered by data type, including country info", "operationId": "get_api_agreement_blocks_by_type", "parameters": [ { "name": "dataType", "in": "path", "description": "Data type to filter by", "required": true, "schema": { "type": "string", "enum": [ "int", "float", "bool", "text", "date" ] } } ], "responses": { "200": { "description": "List of agreement blocks with specified data type", "content": { "application/json": { "schema": { "properties": { "agreement_blocks": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "DEPOSIT_MONTHS" }, "data_type": { "type": "string", "example": "int" }, "country": { "properties": { "code": { "type": "string", "example": "UA" }, "name": { "type": "object", "additionalProperties": { "type": "string" } } }, "type": "object", "nullable": true }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "additionalProperties": { "type": "string" } }, "image_url": { "type": "string", "nullable": true }, "is_system": { "type": "boolean", "example": true }, "sort_order": { "type": "integer", "example": 0 } }, "type": "object" } }, "data_type": { "type": "string", "example": "int" }, "total": { "type": "integer", "example": 12 } }, "type": "object" } } } }, "400": { "description": "Invalid data type", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Invalid data type. Allowed: int, float, bool, text, date" } }, "type": "object" } } } } } } }, "/api/v1/analytics/track": { "post": { "operationId": "post_api_analytics_track", "responses": { "default": { "description": "" } } } }, "/api/v1": { "get": { "tags": [ "07. Tools" ], "summary": "API Information", "description": "Returns API version and documentation links", "operationId": "get_api_index", "responses": { "200": { "description": "API information", "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "LandLordKeeper API" }, "version": { "type": "string", "example": "1.0.0" }, "documentation": { "type": "string", "example": "/api/v1/doc.json" } }, "type": "object" } } } } } } }, "/api/v1/auth/login": { "post": { "tags": [ "01. Authentication" ], "summary": "User login", "description": "Authenticate with email and password to receive JWT token", "operationId": "post_api_auth_login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "format": "password", "example": "YourPassword123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Successful authentication", "content": { "application/json": { "schema": { "properties": { "token": { "type": "string" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "properties": { "code": { "type": "integer", "example": 401 }, "message": { "type": "string", "example": "Invalid credentials." } }, "type": "object" } } } } } } }, "/api/v1/auth/register": { "post": { "tags": [ "01. Authentication" ], "summary": "Start registration (Step 1)", "description": "Send verification code to email. If email exists, returns error. After receiving code, use /api/auth/register/verify to complete registration.", "operationId": "post_api_auth_register", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email" ], "properties": { "name": { "type": "string", "example": "John Doe", "maxLength": 100, "minLength": 2 }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "locale": { "type": "string", "example": "en" } }, "type": "object" } } } }, "responses": { "200": { "description": "Verification code sent", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Verification code sent to email" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" } }, "type": "object" } } } }, "409": { "description": "Email already exists", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "email_exists" }, "message": { "type": "string", "example": "Email already registered" } }, "type": "object" } } } }, "429": { "description": "Too many attempts", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "rate_limit" }, "wait": { "type": "integer", "example": 45 } }, "type": "object" } } } } } } }, "/api/v1/auth/register/verify": { "post": { "tags": [ "01. Authentication" ], "summary": "Complete registration (Step 2)", "description": "Verify email code and create user account. Use country codes from /api/countries and locale codes from /api/languages.", "operationId": "post_api_auth_register_verify", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "email", "code", "password", "country_code" ], "properties": { "email": { "type": "string", "format": "email", "example": "john@example.com" }, "code": { "type": "string", "example": "123456", "maxLength": 6, "minLength": 6 }, "password": { "type": "string", "format": "password", "example": "SecurePass123!", "minLength": 8 }, "country_code": { "type": "string", "example": "UA", "maxLength": 2, "minLength": 2 }, "phone": { "type": "string", "example": "+380501234567" }, "locale": { "type": "string", "example": "uk" } }, "type": "object" } } } }, "responses": { "201": { "description": "User created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "User registered successfully" }, "user": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error or invalid code", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "409": { "description": "Email or phone already exists", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "email_exists" } }, "type": "object" } } } } } } }, "/api/v1/auth/me": { "get": { "tags": [ "01. Authentication" ], "summary": "Get current user", "description": "Returns information about the currently authenticated user", "operationId": "get_api_auth_me", "responses": { "200": { "description": "User information", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+380501234567", "nullable": true }, "locale": { "type": "string", "example": "en" }, "country": { "properties": { "code": { "type": "string", "example": "UA" }, "phone_code": { "type": "string", "example": "+380" } }, "type": "object" }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "ROLE_USER" ] }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/auth/refresh": { "post": { "tags": [ "01. Authentication" ], "summary": "Refresh token", "description": "Get a new JWT token using current valid token. Call this before token expires.", "operationId": "post_api_auth_refresh", "responses": { "200": { "description": "New token generated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Token is valid" }, "expires_in": { "type": "integer", "example": 3600 } }, "type": "object" } } } }, "401": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/admin/backup/create": { "post": { "tags": [ "14. Backup" ], "summary": "Start database backup", "description": "Runs mysqldump in background. Returns file_id immediately. Poll /status until done.", "operationId": "post_api_backup_create", "responses": { "200": { "description": "Backup started", "content": { "application/json": { "schema": { "properties": { "file_id": { "type": "string", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "500": { "description": "Failed to start process" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/admin/backup/{fileId}/status": { "get": { "tags": [ "14. Backup" ], "summary": "Check backup status", "description": "Returns status: running | done | failed | not_found", "operationId": "get_api_backup_status", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Status info", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "enum": [ "running", "done", "failed", "not_found" ] }, "size_bytes": { "type": "integer", "nullable": true }, "error": { "type": "string", "nullable": true } }, "type": "object" } } } }, "404": { "description": "Invalid fileId format" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/admin/backup/{fileId}/download": { "get": { "tags": [ "14. Backup" ], "summary": "Download backup file", "description": "Streams the .sql.gz file. Only available when status=done.", "operationId": "get_api_backup_download", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Binary .sql.gz file stream" }, "404": { "description": "Not found or not ready" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/admin/backup/{fileId}": { "delete": { "tags": [ "14. Backup" ], "summary": "Delete backup files", "description": "Deletes .sql.gz, .done, .error temp files from server.", "operationId": "delete_api_backup_delete", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{\"deleted\": true}" }, "404": { "description": "Invalid fileId format" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/billing/wallet": { "get": { "tags": [ "10. Billing" ], "summary": "Get wallet balance", "operationId": "get_api_billing_wallet", "responses": { "200": {}, "401": {} } } }, "/api/v1/billing/transactions": { "get": { "tags": [ "10. Billing" ], "summary": "Get paginated transaction list", "operationId": "get_api_billing_transactions", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "from_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": {}, "401": {} } } }, "/api/v1/billing/invoices": { "get": { "tags": [ "10. Billing" ], "summary": "Get paginated invoice list", "operationId": "get_api_billing_invoices", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "method", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": {}, "401": {} } } }, "/api/v1/billing/property/{propId}": { "get": { "tags": [ "10. Billing" ], "summary": "Get property subscription status", "operationId": "get_api_billing_property", "parameters": [ { "name": "propId", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": {}, "403": {}, "404": {} } } }, "/api/v1/billing/top-up": { "post": { "tags": [ "10. Billing" ], "summary": "Create top-up invoice (not yet implemented \u2014 use web UI)", "operationId": "post_api_billing_top_up", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amount", "method" ], "properties": { "amount": { "type": "number" }, "method": { "type": "string", "example": "bank_transfer" } }, "type": "object" } } } }, "responses": { "200": {}, "400": {}, "401": {}, "403": {} }, "deprecated": true } }, "/api/v1/billing/subscribe/{propId}": { "post": { "tags": [ "10. Billing" ], "summary": "Subscribe property", "operationId": "post_api_billing_subscribe", "parameters": [ { "name": "propId", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "plan" ], "properties": { "plan": { "type": "string", "example": "monthly" } }, "type": "object" } } } }, "responses": { "200": {}, "400": {}, "403": {}, "404": {} } } }, "/api/v1/billing/stats": { "get": { "tags": [ "10. Billing" ], "summary": "Get payment statistics by year", "description": "Returns total paid and per-property breakdown for the authenticated user", "operationId": "get_api_billing_stats", "parameters": [ { "name": "year", "in": "query", "description": "Year for statistics (default: current year)", "required": false, "schema": { "type": "integer", "example": 2026 } } ], "responses": { "200": { "description": "Payment statistics", "content": { "application/json": { "schema": { "properties": { "year": { "type": "integer", "example": 2026 }, "total_paid": { "type": "string", "example": "240.0000" }, "by_property": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "total": { "type": "string" }, "count": { "type": "integer" } }, "type": "object" } } }, "type": "object" } } } }, "401": {} } } }, "/api/v1/bonus/balance": { "get": { "tags": [ "12. Bonus & Referral" ], "summary": "Get bonus balance", "operationId": "get_api_bonus_balance", "responses": { "default": { "description": "" } } } }, "/api/v1/bonus/transactions": { "get": { "tags": [ "12. Bonus & Referral" ], "summary": "List bonus transactions", "operationId": "get_api_bonus_transactions", "responses": { "default": { "description": "" } } } }, "/api/v1/bonus/transfer": { "post": { "tags": [ "12. Bonus & Referral" ], "summary": "Transfer bonuses to wallet", "operationId": "post_api_bonus_transfer", "responses": { "default": { "description": "" } } } }, "/api/v1/bonus/referral-link": { "get": { "tags": [ "12. Bonus & Referral" ], "summary": "Get referral link", "operationId": "get_api_bonus_referral_link", "responses": { "default": { "description": "" } } } }, "/api/v1/bonus/referrals": { "get": { "tags": [ "12. Bonus & Referral" ], "summary": "List referrals", "operationId": "get_api_bonus_referrals", "responses": { "default": { "description": "" } } } }, "/api/v1/bonus/gifts": { "get": { "tags": [ "12. Bonus & Referral" ], "summary": "List available gifts", "operationId": "get_api_bonus_gifts", "responses": { "default": { "description": "" } } } }, "/api/v1/bonus/orders": { "get": { "tags": [ "12. Bonus & Referral" ], "summary": "List gift orders", "operationId": "get_api_bonus_orders", "responses": { "default": { "description": "" } } } }, "/api/v1/calendar/events": { "get": { "tags": [ "Calendar" ], "summary": "Get calendar events", "description": "Returns individual calendar events for all user properties. The web UI aggregates these into daily summaries (\u25bc charged, \u25b2 paid, \u25cf events, \u03a3 balance). Event types: counter readings, expense/rental charges, contracts, documents, payments, penalties, repair compensations, violations. All monetary amounts are in the original currency \u2014 use /daily-balances endpoint for converted totals.", "operationId": "get_api_calendar_events", "parameters": [ { "name": "start", "in": "query", "description": "Start date in ISO 8601 format (YYYY-MM-DD)", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "end", "in": "query", "description": "End date in ISO 8601 format (YYYY-MM-DD)", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-02-01" } }, { "name": "property_id", "in": "query", "description": "Filter by property ID (optional)", "required": false, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Array of calendar events in FullCalendar format", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "counter-due-1-2026-01" }, "title": { "type": "string", "example": "Counter Reading Due: 232323" }, "start": { "type": "string", "format": "date", "example": "2026-01-20" }, "allDay": { "type": "boolean", "example": true }, "backgroundColor": { "type": "string", "example": "#e53935" }, "borderColor": { "type": "string", "example": "#e53935" }, "textColor": { "type": "string", "example": "#fff" }, "extendedProps": { "properties": { "type": { "type": "string", "example": "counter_reading_due" }, "status": { "type": "string", "example": "upcoming" }, "property": { "type": "string", "example": "My Apartment" }, "propertyId": { "type": "integer", "example": 1 }, "counterId": { "type": "integer", "example": 1 }, "counterSerial": { "type": "string", "example": "232323" }, "url": { "type": "string", "example": "/properties/1/counters/1/values/new" } }, "type": "object" } }, "type": "object" } } } } }, "400": { "description": "Invalid date format or missing parameters", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Missing start or end date" } }, "type": "object" } } } }, "401": { "description": "Unauthorized - JWT token required" } } } }, "/api/v1/calendar/event-types": { "get": { "tags": [ "Calendar" ], "summary": "Get calendar event types", "description": "Returns list of available event types with their colors and descriptions", "operationId": "get_api_calendar_event_types", "responses": { "200": { "description": "List of event types", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "type": { "type": "string", "example": "counter_reading_due" }, "color": { "type": "string", "example": "#e53935" }, "description": { "type": "string", "example": "Counter reading due date" }, "category": { "type": "string", "example": "counters" } }, "type": "object" } } } } } } } }, "/api/v1/calendar/properties": { "get": { "tags": [ "Calendar" ], "summary": "Get user properties for calendar filter", "description": "Returns list of properties the user has access to for filtering calendar events", "operationId": "get_api_calendar_properties", "responses": { "200": { "description": "List of properties", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "My Apartment" }, "address": { "type": "string", "example": "123 Main St, Kyiv" } }, "type": "object" } } } } } } } }, "/api/v1/calendar/daily-balances": { "get": { "tags": [ "Calendar" ], "summary": "Get daily cumulative balances", "description": "Returns starting balance before the period and daily charge/payment deltas. Client computes running balance per day. All amounts converted to user currency.", "operationId": "get_api_calendar_daily_balances", "parameters": [ { "name": "start", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-02-01" } }, { "name": "end", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-02-28" } } ], "responses": { "200": { "description": "Daily balance data", "content": { "application/json": { "schema": { "properties": { "startBalance": { "type": "number", "example": -28159.58 }, "dailyDeltas": { "type": "object", "example": "{\"2026-02-01\": -656.43, \"2026-02-02\": 2282.16}" }, "dayCharges": { "type": "object", "example": "{\"2026-02-01\": 688.63}" }, "dayPaid": { "type": "object", "example": "{\"2026-02-01\": 32.20}" }, "rangeStart": { "type": "string", "example": "2026-02-01" }, "rangeEnd": { "type": "string", "example": "2026-02-28" }, "currency": { "type": "string", "example": "\u20ac" } }, "type": "object" } } } } } } }, "/api/v1/calendar/balance": { "get": { "tags": [ "Calendar" ], "summary": "Get detailed balance for a specific date", "description": "Returns cumulative balance per property split into utilities and rental. Each section shows: opening debt, day charges (+\u25bc), day payments (\u2212\u25b2), closing balance (\u03a3). Includes drill-down items (individual charge/payment documents) for the day.", "operationId": "get_api_calendar_balance", "parameters": [ { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-02-01" } } ], "responses": { "200": { "description": "Balance breakdown by property", "content": { "application/json": { "schema": { "properties": { "properties": { "type": "array", "items": { "properties": { "propertyName": { "type": "string", "example": "My Apartment" }, "utilityDebtBefore": { "type": "number", "example": 1338.51 }, "utilityChargedDay": { "type": "number", "example": 14.27 }, "utilityPaidDay": { "type": "number", "example": 10.4 }, "utilityDebt": { "type": "number", "example": 1342.38 }, "utilityDayItems": { "type": "array", "items": { "properties": { "label": { "type": "string", "example": "Electricity" }, "desc": { "type": "string", "example": "Monthly charge" }, "amount": { "type": "number", "example": 14.27 }, "url": { "type": "string", "example": "/properties/12/charges/42" } }, "type": "object" } }, "rentalDebtBefore": { "type": "number", "example": 0 }, "rentalChargedDay": { "type": "number", "example": 486.18 }, "rentalPaidDay": { "type": "number", "example": 0 }, "rentalDebt": { "type": "number", "example": 486.18 }, "totalDebt": { "type": "number", "example": 1828.56 } }, "type": "object" } }, "currency": { "type": "string", "example": "\u20ac" } }, "type": "object" } } } } } } }, "/api/v1/calendar/charges": { "get": { "tags": [ "Calendar" ], "summary": "Get charges for a specific date", "description": "Returns expense charges, rental charges, and penalties for the given date. Filtered from the events endpoint by charge types.", "operationId": "get_api_calendar_charges", "parameters": [ { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-02-01" } }, { "name": "property_id", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Charge events for the date", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } } } } }, "/api/v1/calendar/payments": { "get": { "tags": [ "Calendar" ], "summary": "Get payments for a specific date", "description": "Returns payments, refunds, and repair compensations for the given date.", "operationId": "get_api_calendar_payments", "parameters": [ { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-02-01" } }, { "name": "property_id", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment events for the date", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } } } } }, "/api/v1/communications/{id}/accesses": { "get": { "tags": [ "03. Properties / Communication Access" ], "summary": "List users with access to communication", "description": "Returns list of users who have access to this communication. Only property owner can see this.", "operationId": "get_api_communication_accesses_list", "parameters": [ { "name": "id", "in": "path", "description": "Communication ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Access list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "property_user_id": { "type": "integer" }, "user": { "type": "object" }, "role": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "total": { "type": "integer" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Communication Access" ], "summary": "Grant user access to communication", "description": "Grants access to a property user. Only property owner can do this.", "operationId": "post_api_communication_accesses_add", "parameters": [ { "name": "id", "in": "path", "description": "Communication ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "property_user_id" ], "properties": { "property_user_id": { "type": "integer" } }, "type": "object" } } } }, "responses": { "201": { "description": "Access granted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "data": { "type": "object" } }, "type": "object" } } } }, "400": {}, "401": {}, "403": {}, "404": {}, "409": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/communications/{id}/accesses/{propertyUserId}": { "delete": { "tags": [ "03. Properties / Communication Access" ], "summary": "Revoke user access to communication", "description": "Revokes access from a property user. Only property owner can do this.", "operationId": "delete_api_communication_accesses_remove", "parameters": [ { "name": "id", "in": "path", "description": "Communication ID", "required": true, "schema": { "type": "integer" } }, { "name": "propertyUserId", "in": "path", "description": "Property User ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Access revoked", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/communications/{id}/available-users": { "get": { "tags": [ "03. Properties / Communication Access" ], "summary": "Get users without access to communication", "description": "Returns property users who can be granted access. Only owner can see this.", "operationId": "get_api_communication_accesses_available", "parameters": [ { "name": "id", "in": "path", "description": "Communication ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Users list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/communications/{id}/password": { "get": { "tags": [ "03. Properties / Communication Access" ], "summary": "Get communication password", "description": "Returns password for communication. Only property owner can access. All access is logged.", "operationId": "get_api_communication_get_password", "parameters": [ { "name": "id", "in": "path", "description": "Communication ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Password retrieved", "content": { "application/json": { "schema": { "properties": { "password": { "type": "string" }, "accessed_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/communication-types": { "get": { "tags": [ "05. References / Communication Types" ], "summary": "List communication types", "description": "Returns list of all active communication types.", "operationId": "get_api_communication_types_list", "responses": { "200": { "description": "Communication types list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "WIFI" }, "name_key": { "type": "string", "example": "communication_type.wifi.name" }, "description_key": { "type": "string", "example": "communication_type.wifi.description" }, "icon_url": { "type": "string", "example": "/images/communication_types/wifi.svg" }, "show_login": { "type": "boolean", "example": true }, "show_password": { "type": "boolean", "example": true }, "show_access_address": { "type": "boolean", "example": true } }, "type": "object" } }, "total": { "type": "integer", "example": 14 } }, "type": "object" } } } } } } }, "/api/v1/communication-types/{code}": { "get": { "tags": [ "05. References / Communication Types" ], "summary": "Get communication type by code", "description": "Returns communication type details by code.", "operationId": "get_api_communication_types_show", "parameters": [ { "name": "code", "in": "path", "description": "Communication type code", "required": true, "schema": { "type": "string", "example": "WIFI" } } ], "responses": { "200": { "description": "Communication type details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "WIFI" }, "name_key": { "type": "string", "example": "communication_type.wifi.name" }, "description_key": { "type": "string", "example": "communication_type.wifi.description" }, "icon_url": { "type": "string", "example": "/images/communication_types/wifi.svg" }, "show_login": { "type": "boolean", "example": true }, "show_password": { "type": "boolean", "example": true }, "show_access_address": { "type": "boolean", "example": true } }, "type": "object" } } } }, "404": {} } } }, "/api/v1/properties/{propertyId}/contracts": { "get": { "tags": [ "04. Contracts" ], "summary": "List property contracts", "description": "Returns list of all contracts for a property. User must have access to the property.", "operationId": "get_api_contracts_list", "parameters": [ { "name": "propertyId", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Contracts list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Rental Agreement 2026", "nullable": true }, "property_id": { "type": "integer", "example": 5 }, "tenant": { "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "John Smith" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+380501234567", "nullable": true } }, "type": "object" }, "rental_type": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "LONG_TERM" }, "name_key": { "type": "string", "example": "rental_type.long_term" } }, "type": "object" }, "signing_date": { "type": "string", "format": "date", "example": "2026-01-10" }, "start_date": { "type": "string", "format": "date", "example": "2026-01-15" }, "end_date": { "type": "string", "format": "date", "example": "2027-01-14", "nullable": true }, "is_open_ended": { "type": "boolean", "example": false }, "is_active": { "type": "boolean", "example": true }, "created_by": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Owner Name" }, "email": { "type": "string", "example": "owner@example.com" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-01-10T09:00:00+00:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-01-10T09:00:00+00:00" } }, "type": "object" } }, "total": { "type": "integer", "example": 3 }, "page": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "404": { "description": "Property not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Property not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "04. Contracts" ], "summary": "Create contract", "description": "Creates a new contract via ContractFormHandler (same path as the web UI): validates tenant/rental type/dates/overlap, persists the contract with HTML-sanitized fields, and saves contract term blocks (agreement_block_id => value). RATE_REVISION_CURRENCY defaults to EUR when not supplied. User must have EDIT access to the property.", "operationId": "post_api_contracts_create", "parameters": [ { "name": "propertyId", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "tenant_id", "rental_type_id", "signing_date", "start_date" ], "properties": { "name": { "type": "string", "example": "Rental Agreement 2026" }, "tenant_id": { "type": "integer", "example": 5 }, "rental_type_id": { "type": "integer", "example": 1 }, "signing_date": { "type": "string", "format": "date", "example": "2026-01-10" }, "start_date": { "type": "string", "format": "date", "example": "2026-01-15" }, "end_date": { "type": "string", "format": "date", "example": "2027-01-14" }, "blocks": { "description": "Contract term blocks with values", "type": "array", "items": { "properties": { "agreement_block_id": { "type": "integer", "example": 1 }, "value": { "type": "string", "example": "2" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Contract created", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Contract created successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Rental Agreement 2026", "nullable": true }, "property_id": { "type": "integer", "example": 5 }, "tenant": { "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "John Smith" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "nullable": true } }, "type": "object" }, "rental_type": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "LONG_TERM" }, "name_key": { "type": "string", "example": "rental_type.long_term" } }, "type": "object" }, "signing_date": { "type": "string", "format": "date", "example": "2026-01-10" }, "start_date": { "type": "string", "format": "date", "example": "2026-01-15" }, "end_date": { "type": "string", "format": "date", "nullable": true }, "is_open_ended": { "type": "boolean", "example": false }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error or dates overlap", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Contract dates overlap with existing contract" }, "overlapping_contract_id": { "type": "integer", "example": 5 } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "404": { "description": "Property, tenant, or rental type not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Tenant not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/contracts/{id}": { "get": { "tags": [ "04. Contracts" ], "summary": "Get contract details", "description": "Returns contract details including attached documents and contract blocks. User must have access to the property.", "operationId": "get_api_contracts_show", "parameters": [ { "name": "id", "in": "path", "description": "Contract ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Contract details with documents", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Rental Agreement 2026", "nullable": true }, "property_id": { "type": "integer", "example": 5 }, "tenant": { "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "John Smith" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+380501234567", "nullable": true } }, "type": "object" }, "rental_type": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "LONG_TERM" }, "name_key": { "type": "string", "example": "rental_type.long_term" } }, "type": "object" }, "signing_date": { "type": "string", "format": "date", "example": "2026-01-10" }, "start_date": { "type": "string", "format": "date", "example": "2026-01-15" }, "end_date": { "type": "string", "format": "date", "example": "2027-01-14", "nullable": true }, "is_open_ended": { "type": "boolean", "example": false }, "is_active": { "type": "boolean", "example": true }, "blocks": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "agreement_block_id": { "type": "integer" }, "code": { "type": "string" }, "name_key": { "type": "string" }, "data_type": { "type": "string" }, "value": { "type": "string" } }, "type": "object" } }, "documents": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "document_id": { "type": "integer" }, "file_name": { "type": "string" }, "file_url": { "type": "string" }, "file_size": { "type": "integer" }, "file_size_formatted": { "type": "string" }, "mime_type": { "type": "string" }, "extension": { "type": "string" }, "comment": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "documents_count": { "type": "integer", "example": 3 }, "created_by": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Owner Name" }, "email": { "type": "string", "example": "owner@example.com" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "404": { "description": "Contract not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Contract not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "04. Contracts" ], "summary": "Update contract", "description": "Updates a contract via ContractFormHandler (same path as the web UI): validates and persists with HTML-sanitized fields. Supports partial update \u2014 missing fields are filled from the existing contract. Dates cannot overlap with other contracts on the same property. If blocks is provided, it fully replaces existing blocks; if blocks is omitted, existing blocks are preserved.", "operationId": "put_api_contracts_update", "parameters": [ { "name": "id", "in": "path", "description": "Contract ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Updated Contract Name" }, "tenant_id": { "type": "integer", "example": 5 }, "rental_type_id": { "type": "integer", "example": 1 }, "signing_date": { "type": "string", "format": "date", "example": "2026-01-10" }, "start_date": { "type": "string", "format": "date", "example": "2026-01-15" }, "end_date": { "type": "string", "format": "date", "example": "2027-01-14", "nullable": true }, "blocks": { "description": "Contract term blocks with values (replaces existing blocks)", "type": "array", "items": { "properties": { "agreement_block_id": { "type": "integer", "example": 1 }, "value": { "type": "string", "example": "2" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Contract updated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Contract updated successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "nullable": true }, "property_id": { "type": "integer" }, "tenant": { "type": "object" }, "rental_type": { "type": "object" }, "signing_date": { "type": "string", "format": "date" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date", "nullable": true }, "is_open_ended": { "type": "boolean" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error or dates overlap", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Contract dates overlap with existing contract" }, "overlapping_contract_id": { "type": "integer", "example": 5 } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "404": { "description": "Contract not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Contract not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "04. Contracts" ], "summary": "Delete contract", "description": "Deletes the contract with S3-first cascade removal of attached documents. User must have EDIT access. Returns 400 if the contract is inactive, has penalties, or has linked payments. Returns 500 if S3 deletion fails.", "operationId": "delete_api_contracts_delete", "parameters": [ { "name": "id", "in": "path", "description": "Contract ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Contract deleted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Contract deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "404": { "description": "Contract not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Contract not found" } }, "type": "object" } } } }, "400": { "description": "Cannot delete (inactive, has penalties, or has linked payments)", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } }, "500": { "description": "S3 deletion failed", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/contracts/active": { "get": { "tags": [ "04. Contracts" ], "summary": "Get active contract", "description": "Returns the currently active contract for a property (if any).", "operationId": "get_api_contracts_active", "parameters": [ { "name": "propertyId", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Active contract or null", "content": { "application/json": { "schema": { "properties": { "data": { "description": "Contract object if active contract exists, null otherwise", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "nullable": true }, "property_id": { "type": "integer" }, "tenant": { "type": "object" }, "rental_type": { "type": "object" }, "signing_date": { "type": "string", "format": "date" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date", "nullable": true }, "is_open_ended": { "type": "boolean" }, "is_active": { "type": "boolean", "example": true } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "404": { "description": "Property not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Property not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/contracts/{id}/documents": { "get": { "tags": [ "04. Contracts" ], "summary": "List contract documents", "description": "Returns list of all documents attached to a contract. User must have access to the property (landlord, tenant, or their agents).", "operationId": "get_api_contracts_documents_list", "parameters": [ { "name": "id", "in": "path", "description": "Contract ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Documents list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "document_id": { "type": "integer", "example": 10 }, "file_name": { "type": "string", "example": "contract_scan.pdf" }, "file_url": { "type": "string", "example": "https://s3.example.com/docs/contract_scan.pdf" }, "file_size": { "type": "integer", "example": 1048576 }, "file_size_formatted": { "type": "string", "example": "1 MB" }, "mime_type": { "type": "string", "example": "application/pdf" }, "extension": { "type": "string", "example": "pdf" }, "comment": { "type": "string", "example": "Main contract scan", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "total": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "404": { "description": "Contract not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Contract not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "04. Contracts" ], "summary": "Upload contract document", "description": "Uploads a document (scan) to a contract. Allowed for landlord, tenant, and their agents. Allowed formats: PDF, JPG, PNG. Max size: 10 MB.", "operationId": "post_api_contracts_documents_upload", "parameters": [ { "name": "id", "in": "path", "description": "Contract ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "file", "file_name", "mime_type" ], "properties": { "file": { "type": "string", "format": "byte" }, "file_name": { "type": "string", "example": "contract_scan.pdf" }, "mime_type": { "type": "string", "example": "application/pdf" }, "comment": { "type": "string", "example": "Main contract scan", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Document uploaded", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Document uploaded successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "document_id": { "type": "integer", "example": 10 }, "file_name": { "type": "string", "example": "contract_scan.pdf" }, "file_url": { "type": "string" }, "comment": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Invalid file type. Allowed: PDF, JPG, PNG" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "404": { "description": "Contract not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Contract not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/contracts/{id}/documents/{docId}": { "delete": { "tags": [ "04. Contracts" ], "summary": "Delete contract document", "description": "Deletes a document from a contract. Only landlord and landlord agent can delete documents.", "operationId": "delete_api_contracts_documents_delete", "parameters": [ { "name": "id", "in": "path", "description": "Contract ID", "required": true, "schema": { "type": "integer" } }, { "name": "docId", "in": "path", "description": "Contract document ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Document deleted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Document deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied (only landlord/agent can delete)", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied. Only landlord or landlord agent can delete documents." } }, "type": "object" } } } }, "404": { "description": "Contract or document not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Document not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/contracts/{id}/print/{type}": { "post": { "tags": [ "04. Contracts / Print Forms" ], "summary": "Generate contract print form HTML", "description": "Generates HTML for a contract print form. The `type` parameter selects which form to generate.\n\n**Available types:**\n- `contract` \u2014 Main rental contract (supports `layout` parameter)\n- `keys-addendum` \u2014 Keys handover addendum\n- `keyfobs-addendum` \u2014 Keyfobs handover addendum\n- `prepayment-addendum` \u2014 Prepayment addendum\n- `acceptance-act` \u2014 Property acceptance act\n- `return-act` \u2014 Property return act\n- `deposit-addendum` \u2014 Security deposit addendum\n- `termination-notice-addendum` \u2014 Termination notice addendum\n- `rate-addendum` \u2014 Rate review addendum\n- `utilities-addendum` \u2014 Utilities addendum\n- `other-conditions-addendum` \u2014 Other conditions addendum\n- `rent-amount-addendum` \u2014 Rent amount addendum\n- `payment-day-addendum` \u2014 Payment day addendum\n- `grace-period-addendum` \u2014 Grace period addendum\n- `utilities-payment-day-addendum` \u2014 Utilities payment day addendum\n- `min-rental-period-addendum` \u2014 Minimum rental period addendum\n- `utilities-grace-period-addendum` \u2014 Utilities grace period addendum\n- `allowed-violations-addendum` \u2014 Allowed violations addendum\n- `tenant-rate-review-rights-addendum` \u2014 Tenant rate review rights addendum\n- `late-vacating-penalty-addendum` \u2014 Late vacating penalty addendum\n- `advance-payment-rate-fixed-addendum` \u2014 Advance payment rate fixed addendum\n- `force-majeure-addendum` \u2014 Force majeure addendum\n- `insurance-addendum` \u2014 Insurance addendum\n- `pets-addendum` \u2014 Pets addendum\n- `auto-renewal-addendum` \u2014 Auto renewal addendum\n- `good-neighbor-relations-addendum` \u2014 Good neighbor relations addendum\n- `parking-rules-addendum` \u2014 Parking rules addendum\n- `territory-order-addendum` \u2014 Territory order addendum\n- `staircase-order-addendum` \u2014 Staircase order addendum\n- `own-communications-addendum` \u2014 Own communications addendum\n- `confidentiality-addendum` \u2014 Confidentiality addendum\n- `landlord-access-addendum` \u2014 Landlord access addendum\n- `repair-before-leaving-addendum` \u2014 Repair before leaving addendum\n- `repair-against-rent-addendum` \u2014 Repair against rent addendum\n- `forward-mail-addendum` \u2014 Forward mail addendum\n- `tenant-assets-list-addendum` \u2014 Tenant assets list addendum\n- `all-addendums` \u2014 All applicable addendums in one document\n\nReturns base64-encoded HTML content.", "operationId": "post_api_contract_print", "parameters": [ { "name": "id", "in": "path", "description": "Contract ID", "required": true, "schema": { "type": "integer" } }, { "name": "type", "in": "path", "description": "Print form type", "required": true, "schema": { "type": "string", "pattern": "[a-z\\-]+", "enum": [ "contract", "keys-addendum", "keyfobs-addendum", "prepayment-addendum", "acceptance-act", "return-act", "deposit-addendum", "termination-notice-addendum", "rate-addendum", "utilities-addendum", "other-conditions-addendum", "rent-amount-addendum", "payment-day-addendum", "grace-period-addendum", "utilities-payment-day-addendum", "min-rental-period-addendum", "utilities-grace-period-addendum", "allowed-violations-addendum", "tenant-rate-review-rights-addendum", "late-vacating-penalty-addendum", "advance-payment-rate-fixed-addendum", "force-majeure-addendum", "insurance-addendum", "pets-addendum", "auto-renewal-addendum", "good-neighbor-relations-addendum", "parking-rules-addendum", "territory-order-addendum", "staircase-order-addendum", "own-communications-addendum", "confidentiality-addendum", "landlord-access-addendum", "repair-before-leaving-addendum", "repair-against-rent-addendum", "forward-mail-addendum", "tenant-assets-list-addendum", "all-addendums" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractPrintRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractPrintResponse" } } } }, "400": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/counters": { "get": { "tags": [ "03. Properties / Counters" ], "summary": "List counters for a property", "operationId": "get_api_counters_list", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Counters" ], "summary": "Create a new counter", "description": "Creates a counter with its initial reading via CounterService. Supports multi-zone tariffs (TWO_ZONE requires t1+t2, THREE_ZONE requires t1+t2+t3 \u2014 their sum becomes initial_value). Automatically assigns the measurement unit and computes next_reading_due_date. Returns 500 if DB insert fails.", "operationId": "post_api_counters_create", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "expense_type_id", "serial_number", "initial_value", "initial_value_date" ], "properties": { "expense_type_id": { "type": "integer", "example": 1 }, "serial_number": { "type": "string", "example": "12345678" }, "tariff_type": { "type": "string", "example": "SINGLE_ZONE", "enum": [ "SINGLE_ZONE", "TWO_ZONE", "THREE_ZONE" ] }, "initial_value": { "type": "string", "example": "0" }, "initial_value_t1": { "type": "string", "example": null, "nullable": true }, "initial_value_t2": { "type": "string", "example": null, "nullable": true }, "initial_value_t3": { "type": "string", "example": null, "nullable": true }, "initial_value_date": { "type": "string", "format": "date", "example": "2026-01-01" } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "403": {}, "500": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/counters/{id}": { "get": { "tags": [ "03. Properties / Counters" ], "summary": "Get counter details", "description": "Returns counter details including all readings.", "operationId": "get_api_counters_show", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Counter details with readings", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer" }, "expense_type": { "type": "object" }, "serial_number": { "type": "string" }, "tariff_type": { "type": "string", "enum": [ "SINGLE_ZONE", "TWO_ZONE", "THREE_ZONE" ] }, "zone_count": { "type": "integer" }, "initial_value": { "type": "string" }, "current_value": { "type": "string" }, "values": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "value": { "type": "string" }, "value_t1": { "type": "string", "nullable": true }, "value_t2": { "type": "string", "nullable": true }, "value_t3": { "type": "string", "nullable": true }, "date": { "type": "string", "format": "date" }, "is_initial": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": {} }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "03. Properties / Counters" ], "summary": "Update counter", "description": "Updates the counter metadata (expense type, serial number, tariff type) via CounterService. Initial reading values cannot be changed here \u2014 update the initial CounterValue separately. All body fields are optional (partial update). Returns 500 if DB update fails.", "operationId": "put_api_counters_update", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "expense_type_id": { "type": "integer" }, "serial_number": { "type": "string" }, "tariff_type": { "type": "string", "enum": [ "SINGLE_ZONE", "TWO_ZONE", "THREE_ZONE" ] }, "measurement_unit_id": { "type": "integer", "nullable": true } }, "type": "object" } } } }, "responses": { "200": {}, "400": {}, "403": {}, "500": {} }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Counters" ], "summary": "Delete counter", "description": "Delete a counter. Cannot delete counters with linked expense charges - deactivate them instead.", "operationId": "delete_api_counters_delete", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": {}, "400": {}, "403": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/counters/{id}/toggle-active": { "post": { "tags": [ "03. Properties / Counters" ], "summary": "Toggle counter active status", "description": "Activate or deactivate a counter. Deactivated counters are not used for expense charge generation.", "operationId": "post_api_counters_toggle_active", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Status toggled", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer" }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "403": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/counters/{id}/values": { "post": { "tags": [ "03. Properties / Counters" ], "summary": "Add counter reading", "description": "Adds a new counter reading via CounterService (handles delta calculation for adjustments, multi-zone validation, next-reading-due-date recomputation). If is_adjustment is not set and total consumption would be negative, is_adjustment is auto-enabled and values are stored as negative deltas. Returns 500 if DB insert fails.", "operationId": "post_api_counter_values_create", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "date" ], "properties": { "value": { "type": "string", "example": "123.456" }, "value_t1": { "type": "string", "example": "60.000" }, "value_t2": { "type": "string", "example": "40.000" }, "value_t3": { "type": "string", "example": "23.456" }, "date": { "type": "string", "format": "date", "example": "2026-01-07" }, "is_adjustment": { "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "201": {}, "400": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/counters/{id}/values/{valueId}": { "put": { "tags": [ "03. Properties / Counters" ], "summary": "Update counter reading", "description": "Updates a counter reading via CounterService. Supports partial update \u2014 fields not present in the body keep their current value. Returns 500 if DB update fails.", "operationId": "put_api_counter_values_update", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "valueId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "value": { "type": "string" }, "value_t1": { "type": "string" }, "value_t2": { "type": "string" }, "value_t3": { "type": "string" }, "date": { "type": "string", "format": "date" } }, "type": "object" } } } }, "responses": { "200": {}, "400": {}, "403": {} }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Counters" ], "summary": "Delete counter reading", "operationId": "delete_api_counter_values_delete", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "valueId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": {}, "403": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/countries": { "get": { "tags": [ "05. References / Countries" ], "summary": "List all countries", "description": "Returns list of all active countries with their codes and phone codes. No authentication required.", "operationId": "get_api_countries_list", "responses": { "200": { "description": "List of countries", "content": { "application/json": { "schema": { "properties": { "countries": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "UA" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "phone_code": { "type": "string", "example": "+380" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } }, "total": { "type": "integer", "example": 10 } }, "type": "object" } } } } } } }, "/api/v1/countries/{code}": { "get": { "tags": [ "05. References / Countries" ], "summary": "Get country by code", "description": "Returns country details by ISO 3166-1 alpha-2 code", "operationId": "get_api_countries_show", "parameters": [ { "name": "code", "in": "path", "description": "ISO 3166-1 alpha-2 country code (e.g., UA, US, DE)", "required": true, "schema": { "type": "string", "maxLength": 2, "minLength": 2 } } ], "responses": { "200": { "description": "Country details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "UA" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "phone_code": { "type": "string", "example": "+380" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "404": { "description": "Country not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Country not found" } }, "type": "object" } } } } } } }, "/api/v1/currencies": { "get": { "tags": [ "05. References / Currencies" ], "summary": "List all currencies", "description": "Returns list of all active currencies with their codes and symbols. No authentication required.", "operationId": "get_api_currencies_list", "responses": { "200": { "description": "List of currencies", "content": { "application/json": { "schema": { "properties": { "currencies": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "EUR" }, "numeric_code": { "type": "integer", "example": 978 }, "symbol": { "type": "string", "example": "\\u20AC" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "is_base": { "type": "boolean", "example": true } }, "type": "object" } }, "base_currency": { "type": "string", "example": "EUR" }, "total": { "type": "integer", "example": 10 } }, "type": "object" } } } } } } }, "/api/v1/currencies/{code}": { "get": { "tags": [ "05. References / Currencies" ], "summary": "Get currency by code", "description": "Returns currency details by ISO 4217 code", "operationId": "get_api_currencies_show", "parameters": [ { "name": "code", "in": "path", "description": "ISO 4217 currency code (e.g., EUR, USD, UAH)", "required": true, "schema": { "type": "string", "pattern": "[A-Z]{3}", "maxLength": 3, "minLength": 3 } } ], "responses": { "200": { "description": "Currency details", "content": { "application/json": { "schema": { "properties": { "code": { "type": "string", "example": "EUR" }, "numeric_code": { "type": "integer", "example": 978 }, "symbol": { "type": "string", "example": "\\u20AC" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "is_base": { "type": "boolean", "example": true } }, "type": "object" } } } }, "404": { "description": "Currency not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Currency not found" } }, "type": "object" } } } } } } }, "/api/v1/currency-rates": { "get": { "tags": [ "05. References / Currencies" ], "summary": "Get exchange rates", "description": "Returns exchange rates for a specific date. If no date provided, returns latest available rates.", "operationId": "get_api_currency_rates_list", "parameters": [ { "name": "date", "in": "query", "description": "Date in Y-m-d format (e.g., 2024-01-15). If not provided, returns latest rates.", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Exchange rates", "content": { "application/json": { "schema": { "properties": { "date": { "type": "string", "format": "date", "example": "2024-01-15" }, "base_currency": { "type": "string", "example": "EUR" }, "multiplier": { "type": "integer", "example": 100 }, "rates": { "type": "array", "items": { "properties": { "currency": { "type": "string", "example": "USD" }, "rate": { "type": "number", "example": 117.5 }, "rate_per_unit": { "type": "number", "example": 1.175 } }, "type": "object" } }, "total": { "type": "integer", "example": 8 } }, "type": "object" } } } } } } }, "/api/v1/currency-rates/dates": { "get": { "tags": [ "05. References / Currencies" ], "summary": "Get available rate dates", "description": "Returns list of dates for which exchange rates are available", "operationId": "get_api_currency_rates_dates", "responses": { "200": { "description": "List of dates", "content": { "application/json": { "schema": { "properties": { "dates": { "type": "array", "items": { "type": "string", "format": "date" } }, "total": { "type": "integer", "example": 30 } }, "type": "object" } } } } } } }, "/api/v1/currency/convert": { "post": { "summary": "\u041a\u043e\u043d\u0432\u0435\u0440\u0442\u0443\u0432\u0430\u0442\u0438 \u0441\u0443\u043c\u0443 \u0437 \u043e\u0434\u043d\u0456\u0454\u0457 \u0432\u0430\u043b\u044e\u0442\u0438 \u0432 \u0456\u043d\u0448\u0443.", "description": "POST /api/currency/convert\nBody: {\n \"amount\": \"100.50\",\n \"from_currency_id\": 1,\n \"to_currency_id\": 2\n}\n\nResponse: {\n \"amount\": \"100.50\",\n \"from_currency\": {\"id\": 1, \"code\": \"EUR\", \"symbol\": \"\u20ac\"},\n \"to_currency\": {\"id\": 2, \"code\": \"UAH\", \"symbol\": \"\u20b4\"},\n \"converted_amount\": \"4020.00\",\n \"formatted\": \"4 020.00 \u20b4\"\n}", "operationId": "post_api_currency_convert", "responses": { "default": { "description": "" } } } }, "/api/v1/currency/convert-batch": { "post": { "summary": "\u041a\u043e\u043d\u0432\u0435\u0440\u0442\u0443\u0432\u0430\u0442\u0438 \u043c\u0430\u0441\u0438\u0432 \u0441\u0443\u043c (\u0434\u043b\u044f batch \u043e\u0431\u0440\u043e\u0431\u043a\u0438).", "description": "POST /api/currency/convert-batch\nBody: {\n \"items\": [\n {\"amount\": \"100\", \"from_currency_id\": 1},\n {\"amount\": \"50\", \"from_currency_id\": 2}\n ],\n \"to_currency_id\": 3\n}\n\nResponse: {\n \"to_currency\": {\"id\": 3, \"code\": \"UAH\", \"symbol\": \"\u20b4\"},\n \"items\": [\n {\"amount\": \"100\", \"from_currency_id\": 1, \"converted_amount\": \"4020.00\"},\n {\"amount\": \"50\", \"from_currency_id\": 2, \"converted_amount\": \"50.00\"}\n ],\n \"total\": \"4070.00\"\n}", "operationId": "post_api_currency_convert_batch", "responses": { "default": { "description": "" } } } }, "/api/v1/user/custom-contragents": { "get": { "tags": [ "06. References / Custom Contragents" ], "summary": "List user custom contragents", "description": "Get all custom contragents created by current user", "operationId": "get_api_custom_contragents_list", "parameters": [ { "name": "search", "in": "query", "description": "Search by name, short name or tax number", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of custom contragents", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "short_name": { "type": "string", "nullable": true }, "tax_number": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "total": { "type": "integer" } }, "type": "object" } } } } } }, "post": { "tags": [ "06. References / Custom Contragents" ], "summary": "Create custom contragent", "description": "Create new custom contragent with strict validation", "operationId": "post_api_custom_contragents_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Example Company LLC" }, "short_name": { "type": "string", "example": "Example Co", "nullable": true }, "legal_form": { "type": "string", "example": "LLC", "nullable": true }, "tax_number": { "type": "string", "example": "12345678", "nullable": true }, "vat_number": { "type": "string", "example": "123456789012", "nullable": true }, "tax_system": { "type": "string", "example": "General", "nullable": true }, "iban": { "type": "string", "example": "UA123456789012345678901234567", "nullable": true }, "bank_name": { "type": "string", "example": "PrivatBank", "nullable": true }, "bank_mfo": { "type": "string", "example": "305299", "nullable": true }, "swift": { "type": "string", "example": "PBANUA2X", "nullable": true }, "email": { "type": "string", "format": "email", "example": "info@example.com", "nullable": true }, "phone": { "type": "string", "example": "+380 44 123 4567", "nullable": true }, "website": { "type": "string", "format": "url", "example": "https://example.com", "nullable": true }, "legal_address": { "type": "string", "example": "Kyiv, Khreshchatyk St, 1", "nullable": true }, "actual_address": { "type": "string", "example": "Kyiv, Khreshchatyk St, 1", "nullable": true }, "director_name": { "type": "string", "example": "John Doe", "nullable": true }, "contact_person": { "type": "string", "example": "Jane Smith", "nullable": true }, "registration_date": { "type": "string", "format": "date", "example": "2020-01-15", "nullable": true }, "notes": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Custom contragent created", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Validation failed" }, "violations": { "type": "object", "example": { "name": "validation.contragent.name.min_length", "tax_number": "validation.contragent.tax_number.invalid", "iban": "validation.contragent.iban.invalid" } } }, "type": "object" } } } } } } }, "/api/v1/user/custom-contragents/{id}": { "get": { "tags": [ "06. References / Custom Contragents" ], "summary": "Get custom contragent details", "description": "Get detailed information about a custom contragent", "operationId": "get_api_custom_contragents_show", "parameters": [ { "name": "id", "in": "path", "description": "Contragent ID", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Contragent details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "short_name": { "type": "string", "nullable": true }, "legal_form": { "type": "string", "nullable": true }, "tax_number": { "type": "string", "nullable": true }, "vat_number": { "type": "string", "nullable": true }, "tax_system": { "type": "string", "nullable": true }, "iban": { "type": "string", "nullable": true }, "bank_name": { "type": "string", "nullable": true }, "bank_mfo": { "type": "string", "nullable": true }, "swift": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "legal_address": { "type": "string", "nullable": true }, "actual_address": { "type": "string", "nullable": true }, "director_name": { "type": "string", "nullable": true }, "contact_person": { "type": "string", "nullable": true }, "registration_date": { "type": "string", "format": "date", "nullable": true }, "notes": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "404": { "description": "Contragent not found" } } }, "put": { "tags": [ "06. References / Custom Contragents" ], "summary": "Update custom contragent", "description": "Update custom contragent with strict validation", "operationId": "put_api_custom_contragents_update", "parameters": [ { "name": "id", "in": "path", "description": "Contragent ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "short_name": { "type": "string", "nullable": true }, "tax_number": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Contragent updated" }, "400": { "description": "Validation failed" }, "404": { "description": "Contragent not found" } } }, "delete": { "tags": [ "06. References / Custom Contragents" ], "summary": "Delete custom contragent", "description": "Delete custom contragent", "operationId": "delete_api_custom_contragents_delete", "parameters": [ { "name": "id", "in": "path", "description": "Contragent ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Contragent deleted" }, "404": { "description": "Contragent not found" } } }, "patch": { "tags": [ "06. Custom Contragents" ], "summary": "\u041e\u0431\u043d\u043e\u0432\u0438\u0442\u044c \u043a\u043e\u043d\u0442\u0440\u0430\u0433\u0435\u043d\u0442\u0430 \u0441 \u0432\u0430\u043b\u0438\u0434\u0430\u0446\u0438\u0435\u0439.", "operationId": "patch_api_custom_contragents_update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "" } } } }, "/api/v1/dev/auth/impersonate/{id}": { "post": { "operationId": "post_api_dev_impersonate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "" } } } }, "/api/v1/dev/auth/issue-token": { "post": { "summary": "Issues a short-lived one-time login token for browser-based Playwright auth.", "description": "POST /api/v1/dev/auth/issue-token\nHeaders: X-Dev-Token: \nBody: {\"user_id\": 1}", "operationId": "post_api_dev_issue_token", "responses": { "default": { "description": "" } } } }, "/api/v1/admin/diag/query": { "post": { "tags": [ "15. Diagnostics" ], "summary": "Start a read-only diagnostic run", "description": "Fires an isolated headless Claude run asynchronously. Returns run_id immediately; poll GET /query/{runId}.", "operationId": "post_api_diag_query", "responses": { "202": { "description": "Run started", "content": { "application/json": { "schema": { "properties": { "run_id": { "type": "string", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "400": { "description": "Validation error (empty/too long prompt, bad session_id)" }, "403": { "description": "Not a ROLE_SUPER_USER" }, "429": { "description": "Rate limit or concurrency cap exceeded" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/admin/diag/query/{runId}": { "get": { "tags": [ "15. Diagnostics" ], "summary": "Poll a diagnostic run", "description": "Returns status/result (server-side capped to DIAG_OUTPUT_CAP), turns and cost.", "operationId": "get_api_diag_status", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run status" }, "404": { "description": "Invalid runId format" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/admin/diag/query/{runId}/stop": { "post": { "tags": [ "15. Diagnostics" ], "summary": "Abort a diagnostic run", "description": "SIGTERM + done-marker (reuses ClaudeConsoleRunner::stop()).", "operationId": "post_api_diag_stop", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{\"stopped\": true}" }, "404": { "description": "Invalid runId format" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/documents": { "get": { "tags": [ "03. Properties / Documents" ], "summary": "List property documents", "description": "Returns list of all documents for a property. User must have access to the property.", "operationId": "get_api_documents_list", "parameters": [ { "name": "propertyId", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "type_id", "in": "query", "description": "Filter by document type ID", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Documents list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "property_id": { "type": "integer", "example": 5 }, "document_type": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "CONTRACT" }, "name_key": { "type": "string", "example": "document_type.contract" } }, "type": "object" }, "file_url": { "type": "string", "example": "https://storage.example.com/documents/abc123.pdf" }, "original_name": { "type": "string", "example": "contract.pdf" }, "file_size": { "type": "integer", "example": 1048576 }, "file_size_formatted": { "type": "string", "example": "1 MB" }, "mime_type": { "type": "string", "example": "application/pdf" }, "extension": { "type": "string", "example": "pdf" }, "is_image": { "type": "boolean", "example": false }, "is_video": { "type": "boolean", "example": false }, "is_pdf": { "type": "boolean", "example": true }, "comment": { "type": "string", "example": "Signed contract", "nullable": true }, "visible_to_roles": { "type": "array", "items": { "type": "string" }, "example": [ "PROPERTY_TENANT" ], "nullable": true }, "created_by": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Owner Name" }, "email": { "type": "string", "example": "owner@example.com" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "total": { "type": "integer", "example": 5 }, "stats": { "properties": { "total_count": { "type": "integer", "example": 5 }, "total_size": { "type": "integer", "example": 5242880 }, "total_size_formatted": { "type": "string", "example": "5 MB" }, "by_type": { "type": "object", "additionalProperties": { "type": "integer" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "404": { "description": "Property not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Property not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Documents" ], "summary": "Upload document", "description": "Uploads a new document to the property via DocumentService (S3 upload, persist, Google Drive sync, document-uploaded notifications). Comment is HTML-sanitized. User must have EDIT access.", "operationId": "post_api_documents_upload", "parameters": [ { "name": "propertyId", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "document_type_id", "file_content", "file_name" ], "properties": { "document_type_id": { "type": "integer", "example": 1 }, "file_content": { "type": "string" }, "file_name": { "type": "string", "example": "contract.pdf" }, "mime_type": { "type": "string", "example": "application/pdf" }, "comment": { "type": "string", "example": "Signed contract" } }, "type": "object" } } } }, "responses": { "201": { "description": "Document uploaded", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Document uploaded successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "property_id": { "type": "integer", "example": 5 }, "document_type": { "type": "object" }, "file_url": { "type": "string", "example": "https://storage.example.com/documents/abc123.pdf" }, "original_name": { "type": "string", "example": "contract.pdf" }, "file_size": { "type": "integer" }, "file_size_formatted": { "type": "string" }, "mime_type": { "type": "string" }, "extension": { "type": "string" }, "is_image": { "type": "boolean" }, "is_video": { "type": "boolean" }, "is_pdf": { "type": "boolean" }, "comment": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "document_type_id, file_content and file_name are required" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "404": { "description": "Property or document type not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Document type not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/documents/{id}": { "get": { "tags": [ "03. Properties / Documents" ], "summary": "Get document details", "description": "Returns document details. User must have access to the property.", "operationId": "get_api_documents_show", "parameters": [ { "name": "id", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Document details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "property_id": { "type": "integer", "example": 5 }, "document_type": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "CONTRACT" }, "name_key": { "type": "string", "example": "document_type.contract" } }, "type": "object" }, "file_url": { "type": "string", "example": "https://storage.example.com/documents/abc123.pdf" }, "original_name": { "type": "string", "example": "contract.pdf" }, "file_size": { "type": "integer", "example": 1048576 }, "file_size_formatted": { "type": "string", "example": "1 MB" }, "mime_type": { "type": "string", "example": "application/pdf" }, "extension": { "type": "string", "example": "pdf" }, "is_image": { "type": "boolean", "example": false }, "is_video": { "type": "boolean", "example": false }, "is_pdf": { "type": "boolean", "example": true }, "comment": { "type": "string", "example": "Signed contract", "nullable": true }, "visible_to_roles": { "type": "array", "items": { "type": "string" }, "nullable": true }, "created_by": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Owner Name" }, "email": { "type": "string", "example": "owner@example.com" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Document not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "03. Properties / Documents" ], "summary": "Update document", "description": "Updates document visibility and/or comment. Comment is HTML-sanitized. User must have EDIT access to the property.", "operationId": "put_api_documents_update", "parameters": [ { "name": "id", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "visible_to": { "description": "Array of role codes that can see document. Empty array or null = visible to all.", "type": "array", "items": { "type": "string", "enum": [ "PROPERTY_TENANT", "PROPERTY_TENANT_AGENT", "PROPERTY_MAINTENANCE" ] }, "example": [ "PROPERTY_TENANT", "PROPERTY_MAINTENANCE" ] }, "comment": { "description": "Optional comment for the document (max 1000 characters). Pass null or empty string to remove.", "type": "string", "example": "Signed contract from January 2026" } }, "type": "object" } } } }, "responses": { "200": { "description": "Document updated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Document updated successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Document not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Documents" ], "summary": "Delete document", "description": "Deletes a document via DocumentService with S3-first cascade (S3 delete \u2192 DB row delete \u2192 Google Drive mirror cleanup \u2192 deletion notifications). User must have EDIT access.", "operationId": "delete_api_documents_delete", "parameters": [ { "name": "id", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Document deleted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Document deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Document not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/media/bulk-delete": { "post": { "tags": [ "03. Properties / Documents" ], "summary": "Bulk delete media documents", "description": "Deletes multiple documents at once via DocumentService (S3-first cascade per document). The csrf_token field is required because this endpoint is also used by the in-app media gallery UI. User can only delete documents from properties they have access to.", "operationId": "post_api_media_bulk_delete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ids", "csrf_token" ], "properties": { "ids": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] }, "csrf_token": { "type": "string", "example": "abc123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Documents deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "deleted": { "type": "integer", "example": 3 }, "failed": { "type": "integer", "example": 0 }, "errors": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "400": {}, "403": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/document-types": { "get": { "tags": [ "05. References / Document Types" ], "summary": "List document types", "description": "Returns list of all active document types with allowed extensions and size limits.", "operationId": "get_api_document_types_list", "responses": { "200": { "description": "Document types list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "OFFICIAL_DOCUMENT" }, "name_key": { "type": "string", "example": "document_type.official.name" }, "description_key": { "type": "string", "example": "document_type.official.description" }, "allowed_extensions": { "type": "string", "example": "pdf,doc,docx" }, "max_size_bytes": { "type": "integer", "example": 20971520 }, "max_size_mb": { "type": "number", "example": 20 } }, "type": "object" } }, "total": { "type": "integer", "example": 10 } }, "type": "object" } } } } } } }, "/api/v1/document-types/{code}": { "get": { "tags": [ "05. References / Document Types" ], "summary": "Get document type by code", "description": "Returns document type details by code.", "operationId": "get_api_document_types_show", "parameters": [ { "name": "code", "in": "path", "description": "Document type code", "required": true, "schema": { "type": "string", "example": "OFFICIAL_DOCUMENT" } } ], "responses": { "200": { "description": "Document type details", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": {} } } }, "/api/v1/expenses/{id}/unlinked-readings": { "get": { "tags": [ "03. Properties / Expense Charges" ], "summary": "Unlinked readings for expense \u2014 File Master select source", "description": "Dedicated endpoint for File Master frontend \u2014 lets the JS populate the\n`counter_value_id` select without having to know the propertyId in the DOM.\nIDOR is enforced via {@see \\PropertyExpenseVoter::VIEW} (non-members get 403).", "operationId": "get_api_expense_unlinked_readings_by_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Per-counter list of unlinked readings" }, "403": { "description": "No access to the expense" }, "404": { "description": "Expense not found" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/expenses/{expenseId}/charges": { "get": { "tags": [ "03. Properties / Expense Charges" ], "summary": "List charges for an expense", "operationId": "get_api_expense_charges_list", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "expenseId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Expense Charges" ], "summary": "Create a new charge", "description": "For counter-based expenses: use counter_value_ids to link existing readings. For fixed consumption: use quantity. Use GET /unlinked-readings to get available readings.", "operationId": "post_api_expense_charges_create", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expenseId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "charge_date", "period_start", "period_end" ], "properties": { "charge_date": { "type": "string", "format": "date", "example": "2026-01-21" }, "period_start": { "type": "string", "format": "date", "example": "2025-12-01" }, "period_end": { "type": "string", "format": "date", "example": "2025-12-31" }, "counter_value_ids": { "description": "Counter mode: IDs of counter readings to link (from GET /unlinked-readings)", "type": "array", "items": { "type": "integer" }, "example": [ 123, 456 ] }, "quantity": { "type": "string", "example": "150.0000" }, "notes": { "type": "string", "nullable": true }, "items": { "description": "[DEPRECATED] Use counter_value_ids for counter-based expenses instead", "type": "array", "items": { "properties": { "counter_id": { "type": "integer", "nullable": true }, "zone_code": { "type": "string", "example": "DAY" }, "previous_value": { "type": "string", "example": "1000.000", "nullable": true }, "current_value": { "type": "string", "example": "1100.000", "nullable": true }, "quantity": { "type": "string", "example": "100.0000" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "403": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/charges": { "get": { "tags": [ "03. Properties / Expense Charges" ], "summary": "List all charges for a property", "operationId": "get_api_expense_charges_list_all", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/charges/{id}": { "get": { "tags": [ "03. Properties / Expense Charges" ], "summary": "Get charge details", "operationId": "get_api_expense_charges_show", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "03. Properties / Expense Charges" ], "summary": "Update charge", "description": "Updates a manual charge. Notes are HTML-sanitized. AUTO-source charges cannot be edited (returns 403). All body fields are optional (partial update).", "operationId": "put_api_expense_charges_update", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "charge_date": { "type": "string", "format": "date" }, "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "quantity": { "type": "string" }, "notes": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": {}, "400": {}, "403": {} }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Expense Charges" ], "summary": "Delete charge", "description": "Deletes a manual charge with S3-first cascade removal of attached documents. AUTO-source charges cannot be deleted (returns 403). Returns 500 if S3 deletion fails.", "operationId": "delete_api_expense_charges_delete", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": {}, "403": {}, "404": {}, "500": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/charges/{id}/confirm": { "post": { "tags": [ "03. Properties / Expense Charges" ], "summary": "Confirm a charge (tenant only)", "description": "Confirm a charge that is pending confirmation. Only tenant or tenant agent can confirm charges.", "operationId": "post_api_expense_charges_confirm", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Charge confirmed successfully", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer" }, "status": { "type": "string", "example": "CONFIRMED" }, "is_confirmed": { "type": "boolean", "example": true }, "confirmed_at": { "type": "string", "format": "date-time" }, "confirmed_by_user": { "type": "object" } }, "type": "object" } } } }, "400": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/expenses/{expenseId}/unlinked-readings": { "get": { "tags": [ "03. Properties / Expense Charges" ], "summary": "Get unlinked counter readings for an expense", "description": "Returns unlinked readings for each counter of the expense. Used when creating charges for counter-based expenses.", "operationId": "get_api_expense_unlinked_readings", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "expenseId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of unlinked readings per counter", "content": { "application/json": { "schema": { "properties": { "has_counters": { "type": "boolean" }, "all_counters_have_readings": { "type": "boolean" }, "can_create_charge": { "type": "boolean" }, "counters_without_readings": { "description": "List of counters that do not have unlinked readings", "type": "array", "items": { "properties": { "counter_id": { "type": "integer" }, "serial_number": { "type": "string" }, "tariff_type": { "type": "string" } }, "type": "object" } }, "counters": { "type": "array", "items": { "properties": { "counter_id": { "type": "integer" }, "serial_number": { "type": "string" }, "tariff_type": { "type": "string" }, "unlinked_readings": { "type": "array", "items": { "properties": { "ids": { "type": "array", "items": { "type": "integer" } }, "date": { "type": "string", "format": "date" }, "value": { "type": "string" }, "previous_value": { "type": "string" }, "consumption": { "type": "string" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } } } }, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/charges/{id}/documents": { "post": { "tags": [ "03. Properties / Expense Charges" ], "summary": "Attach document to expense charge", "description": "Upload document and attach it to the charge. Uses two-step drive sync pattern (documents/ \u2192 expenses/{Y}/{M}/).", "operationId": "post_api_expense_charges_attach_document", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "type": "string", "format": "binary" }, "document_type_id": { "type": "integer", "nullable": true }, "comment": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/charges/{chargeId}/documents": { "get": { "tags": [ "03. Properties / Expense Documents" ], "summary": "List documents for a charge", "operationId": "get_api_charge_documents_list", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "chargeId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Expense Documents" ], "summary": "Upload a document to charge", "description": "Uploads a document via DocumentService, links it to the charge, and reassigns the Google Drive path to the expenses/{Y}/{M}/ folder. Comment is HTML-sanitized.", "operationId": "post_api_charge_documents_upload", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chargeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file", "document_type_id" ], "properties": { "file": { "type": "string", "format": "binary" }, "document_type_id": { "type": "integer" }, "comment": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/charges/{chargeId}/documents/{id}": { "get": { "tags": [ "03. Properties / Expense Documents" ], "summary": "Get charge document details", "operationId": "get_api_charge_documents_show", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chargeId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "03. Properties / Expense Documents" ], "summary": "Update charge document comment", "description": "Updates the comment on a charge document link. Comment is HTML-sanitized.", "operationId": "put_api_charge_documents_update", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chargeId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "comment": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Expense Documents" ], "summary": "Delete charge document", "description": "Deletes the document via DocumentService with S3-first cascade (same as web controller).", "operationId": "delete_api_charge_documents_delete", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chargeId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/expense-providers/available": { "get": { "tags": [ "03. Properties / Expense Providers" ], "summary": "Get all available expense providers grouped by type", "operationId": "get_api_expense_providers_available", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Available expense providers grouped by type", "content": { "application/json": { "schema": { "properties": { "service_providers": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "tax_number": { "type": "string" } }, "type": "object" } }, "users": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "type": "object" } }, "partner_invitations": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "type": "object" } }, "custom_contragents": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "404": {} } } }, "/api/v1/properties/{propertyId}/expense-providers/create-by-email": { "post": { "tags": [ "03. Properties / Expense Providers" ], "summary": "Create ExpenseProvider using email (for user or partner_invitation types)", "operationId": "post_api_expense_providers_create_by_email", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "provider_type", "email" ], "properties": { "provider_type": { "description": "Type of provider to create", "type": "string", "enum": [ "user", "partner_invitation" ] }, "email": { "description": "Email of the user or partner to invite", "type": "string", "format": "email" }, "name": { "description": "Name for partner invitation (required when provider_type=partner_invitation)", "type": "string" }, "locale": { "description": "Language for partner invitation (default: uk)", "type": "string", "enum": [ "uk", "en", "ru", "pl", "de" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "ExpenseProvider created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "type": "integer" }, "provider_type": { "type": "string" }, "provider_id": { "type": "integer" }, "cached_name": { "type": "string" } }, "type": "object" }, "invitation_sent": { "type": "boolean" } }, "type": "object" } } } }, "400": { "description": "Invalid data or validation error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "error_key": { "type": "string" } }, "type": "object" } } } }, "404": {} } } }, "/api/v1/properties/{propertyId}/expense-providers/create-or-get": { "post": { "tags": [ "03. Properties / Expense Providers" ], "summary": "Create or get ExpenseProvider for a specific provider", "operationId": "post_api_expense_providers_create_or_get", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "provider_type", "provider_id" ], "properties": { "provider_type": { "type": "string", "enum": [ "service_provider", "user", "partner_invitation", "custom_contragent" ] }, "provider_id": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": {}, "400": {}, "404": {} } } }, "/api/v1/expense-types": { "get": { "tags": [ "05. References / Expense Types" ], "summary": "List all expense types", "description": "Returns list of all active expense types with their codes, translations and icons. No authentication required.", "operationId": "get_api_expense_types_list", "responses": { "200": { "description": "List of expense types", "content": { "application/json": { "schema": { "properties": { "expense_types": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "HEATING" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "additionalProperties": { "type": "string" } }, "icon_url": { "type": "string", "example": "https://fsn1.your-objectstorage.com/llm/expense_type/heating.svg", "nullable": true }, "with_counters": { "type": "boolean", "example": true }, "is_active": { "type": "boolean", "example": true }, "sort_order": { "type": "integer", "example": 1 } }, "type": "object" } }, "total": { "type": "integer", "example": 13 } }, "type": "object" } } } } } } }, "/api/v1/expense-types/{code}": { "get": { "tags": [ "05. References / Expense Types" ], "summary": "Get expense type by code", "description": "Returns expense type details by code", "operationId": "get_api_expense_types_show", "parameters": [ { "name": "code", "in": "path", "description": "Expense type code (e.g., HEATING, ELECTRICITY, GAS, HOT_WATER)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Expense type details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "HEATING" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "additionalProperties": { "type": "string" } }, "icon_url": { "type": "string", "example": "https://fsn1.your-objectstorage.com/llm/expense_type/heating.svg", "nullable": true }, "with_counters": { "type": "boolean", "example": true }, "is_active": { "type": "boolean", "example": true }, "sort_order": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "404": { "description": "Expense type not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Expense type not found" } }, "type": "object" } } } } } } }, "/api/v1/export/charges": { "get": { "summary": "Export charges to Excel/PDF/CSV.", "operationId": "get_api_export_charges", "responses": { "default": { "description": "" } } } }, "/api/v1/export/expenses": { "get": { "summary": "Export expenses to Excel/PDF/CSV.", "operationId": "get_api_export_expenses", "responses": { "default": { "description": "" } } } }, "/api/v1/export/payments": { "get": { "summary": "Export payments to Excel/PDF/CSV.", "operationId": "get_api_export_payments", "responses": { "default": { "description": "" } } } }, "/api/v1/export/documents": { "get": { "summary": "Export documents to Excel/PDF/CSV.", "operationId": "get_api_export_documents", "responses": { "default": { "description": "" } } } }, "/api/v1/export/counters": { "get": { "summary": "Export counters to Excel/PDF/CSV.", "operationId": "get_api_export_counters", "responses": { "default": { "description": "" } } } }, "/api/v1/export/counter-readings/{counterId}": { "get": { "summary": "Export counter readings (values) of a single counter to Excel/PDF/CSV.", "operationId": "get_api_export_counter_readings", "parameters": [ { "name": "counterId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "" } } } }, "/api/v1/export/contracts": { "get": { "summary": "Export contracts to Excel/PDF/CSV.", "operationId": "get_api_export_contracts", "responses": { "default": { "description": "" } } } }, "/api/v1/export/tenant-assets": { "get": { "summary": "Export tenant assets to Excel/PDF/CSV.", "operationId": "get_api_export_tenant_assets", "responses": { "default": { "description": "" } } } }, "/api/v1/export/property-expenses/{id}": { "get": { "summary": "Export property expenses (\u0432\u0435\u0441\u044c \u043f\u0435\u0440\u0438\u043e\u0434) to Excel/PDF/CSV.", "description": "Excel \u2014 2 \u043b\u0438\u0441\u0442\u0430: \u0421\u0432\u043e\u0434\u043a\u0430 \u043f\u043e \u043a\u0430\u0442\u0435\u0433\u043e\u0440\u0438\u044f\u043c+\u0432\u0430\u043b\u044e\u0442\u0430\u043c ({@see \\self::buildPropertyExpensesSummaryRows()})\n+ \u0414\u0435\u0442\u0430\u043b\u0438\u0437\u0430\u0446\u0438\u044f \u043d\u0430\u0447\u0438\u0441\u043b\u0435\u043d\u0438\u0439 (\u0432\u0441\u0435 {@see \\ExpenseCharge} \u043e\u0431\u044a\u0435\u043a\u0442\u0430, \u043e\u0442\u0441\u043e\u0440\u0442\u0438\u0440\u043e\u0432\u0430\u043d\u043d\u044b\u0435 \u043f\u043e \u0434\u0430\u0442\u0435).\nCSV/PDF \u2014 \u0442\u043e\u043b\u044c\u043a\u043e \u0421\u0432\u043e\u0434\u043a\u0430 (\u0442\u0430\u0431\u043b\u0438\u0447\u043d\u044b\u0439 \u0444\u043e\u0440\u043c\u0430\u0442 \u043d\u0435 \u043f\u043e\u0434\u0434\u0435\u0440\u0436\u0438\u0432\u0430\u0435\u0442 \u043d\u0435\u0441\u043a\u043e\u043b\u044c\u043a\u043e \u043b\u0438\u0441\u0442\u043e\u0432).\n\nTASK-476, \u0442\u0440\u0435\u043a C2 (+ \u0434\u043e\u0440\u0430\u0431\u043e\u0442\u043a\u0430 \u043f\u043e \u043a\u043e\u0434-\u0440\u0435\u0432\u044c\u044e, fix-C2).", "operationId": "get_api_export_property_expenses", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "" } } } }, "/api/v1/properties/{id}/financial-summary": { "get": { "tags": [ "07. Properties" ], "summary": "Get property financial summary (balances)", "operationId": "get_api_property_financial_summary", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "date", "in": "query", "description": "Balance date (default: today)", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Financial summary" }, "403": { "description": "Access denied" }, "404": { "description": "Property not found" } } } }, "/api/v1/properties/{id}/reconciliation": { "get": { "tags": [ "07. Properties" ], "summary": "Get property reconciliation data", "operationId": "get_api_property_reconciliation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "type", "in": "query", "description": "Filter type (default: all)", "required": false, "schema": { "type": "string", "enum": [ "all", "expense", "rental" ] } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Reconciliation data" }, "400": { "description": "Missing required parameters" }, "403": { "description": "Access denied" } } } }, "/api/v1/geo/ip": { "get": { "tags": [ "07. Tools / Geolocation" ], "summary": "Get real client IP address", "description": "Returns the real client IP address, handling Cloudflare and other proxies", "operationId": "get_api_geo_ip", "responses": { "200": { "description": "Client IP address", "content": { "application/json": { "schema": { "properties": { "ip": { "type": "string", "example": "91.200.123.45" } }, "type": "object" } } } } } } }, "/api/v1/geo/locale": { "post": { "tags": [ "07. Tools / Geolocation" ], "summary": "Detect locale from IP address", "description": "Detects country and locale from IP. Priority: GeoIP DB > CF-IPCountry header", "operationId": "post_api_geo_locale", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "ip" ], "properties": { "ip": { "type": "string", "example": "91.200.123.45" } }, "type": "object" } } } }, "responses": { "200": { "description": "Detected locale and country", "content": { "application/json": { "schema": { "properties": { "locale": { "type": "string", "example": "uk" }, "country": { "type": "string", "example": "UA", "nullable": true }, "source": { "type": "string", "example": "geoip", "enum": [ "geoip", "cloudflare", "default" ] } }, "type": "object" } } } }, "400": { "description": "Invalid IP address" } } } }, "/api/v1/geo/detect": { "get": { "tags": [ "07. Tools / Geolocation" ], "summary": "Detect locale from current request", "description": "Detects client IP and returns locale in one request", "operationId": "get_api_geo_detect", "responses": { "200": { "description": "Detected locale, country and IP", "content": { "application/json": { "schema": { "properties": { "ip": { "type": "string", "example": "91.200.123.45" }, "locale": { "type": "string", "example": "uk" }, "country": { "type": "string", "example": "UA", "nullable": true }, "source": { "type": "string", "example": "geoip", "enum": [ "geoip", "cloudflare", "default" ] } }, "type": "object" } } } } } } }, "/api/v1/geo/geocode": { "post": { "tags": [ "07. Tools / Geolocation" ], "summary": "Geocode address to coordinates", "description": "Returns lat/lng for city/street/building via OpenStreetMap Nominatim. Public endpoint.", "operationId": "post_api_geo_geocode", "requestBody": { "content": { "application/json": { "schema": { "properties": { "city": { "type": "string", "example": "Kyiv" }, "street": { "type": "string", "example": "Khreshchatyk" }, "building": { "type": "string", "example": "1" } }, "type": "object" } } } }, "responses": { "200": { "description": "Coordinates found" }, "404": { "description": "Address not found" } } } }, "/api/v1/geo/streets": { "get": { "tags": [ "07. Tools / Geolocation" ], "summary": "Search streets by postal code", "description": "Returns streets matching query within a postal code area via Nominatim. Public endpoint.", "operationId": "get_api_geo_streets", "parameters": [ { "name": "postalcode", "in": "query", "required": true, "schema": { "type": "string", "example": "03039" } }, { "name": "city", "in": "query", "required": true, "schema": { "type": "string", "example": "\u041a\u0438\u0457\u0432" } }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "example": "\u041d" } } ], "responses": { "200": { "description": "List of streets" } } } }, "/api/v1/help-links": { "get": { "tags": [ "Help Links" ], "summary": "Get all help links", "operationId": "get_api_help_links_list", "parameters": [ { "name": "is_active", "in": "query", "description": "Filter by active status (1 or 0)", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "List of help links", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "route_name": { "type": "string", "example": "app_property_adjustments_index" }, "library_path": { "type": "string", "example": "/adjustments/service-provider" }, "full_library_url": { "type": "string", "example": "/library/adjustments/service-provider" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } } } } }, "post": { "tags": [ "Help Links" ], "summary": "Create new help link", "operationId": "post_api_help_links_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "route_name", "library_path" ], "properties": { "route_name": { "type": "string", "example": "app_property_adjustments_index" }, "library_path": { "type": "string", "example": "/adjustments/service-provider" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Help link created", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "message": { "type": "string", "example": "Help link created successfully" } }, "type": "object" } } } }, "400": {} } } }, "/api/v1/help-links/{id}": { "get": { "tags": [ "Help Links" ], "summary": "Get help link by ID", "operationId": "get_api_help_links_show", "parameters": [ { "name": "id", "in": "path", "description": "Help link ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Help link details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "route_name": { "type": "string", "example": "app_property_adjustments_index" }, "library_path": { "type": "string", "example": "/adjustments/service-provider" }, "full_library_url": { "type": "string", "example": "/library/adjustments/service-provider" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "404": {} } }, "put": { "tags": [ "Help Links" ], "summary": "Update help link", "operationId": "put_api_help_links_update", "parameters": [ { "name": "id", "in": "path", "description": "Help link ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "route_name": { "type": "string", "example": "app_property_adjustments_index" }, "library_path": { "type": "string", "example": "/adjustments/service-provider" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": {}, "404": {} } }, "delete": { "tags": [ "Help Links" ], "summary": "Delete help link", "operationId": "delete_api_help_links_delete", "parameters": [ { "name": "id", "in": "path", "description": "Help link ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "404": {} } } }, "/api/v1/help-links/by-route/{routeName}": { "get": { "tags": [ "Help Links" ], "summary": "Get help link by route name", "operationId": "get_api_help_links_by_route", "parameters": [ { "name": "routeName", "in": "path", "description": "Symfony route name", "required": true, "schema": { "type": "string", "example": "app_property_adjustments_index" } } ], "responses": { "200": { "description": "Help link details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "route_name": { "type": "string", "example": "app_property_adjustments_index" }, "library_path": { "type": "string", "example": "/adjustments/service-provider" }, "full_library_url": { "type": "string", "example": "/library/adjustments/service-provider" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "404": {} } } }, "/api/v1/inline-image-upload": { "post": { "operationId": "post_api_inline_image_upload", "responses": { "default": { "description": "" } } } }, "/api/v1/properties/{id}/lt-adjustments": { "get": { "tags": [ "03. Properties / Landlord-Tenant Adjustments" ], "summary": "List landlord-tenant balance adjustments for a property", "operationId": "get_app_api_landlordtenantadjustment_list", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of adjustments", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "adjustment_date": { "type": "string", "format": "date" }, "amount": { "type": "number", "format": "float" }, "currency": { "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "symbol": { "type": "string" } }, "type": "object" }, "notes": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "confirmed_by_landlord", "confirmed_by_tenant", "fully_confirmed" ] }, "is_confirmed_by_landlord": { "type": "boolean" }, "is_confirmed_by_tenant": { "type": "boolean" }, "documents_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "type": "object" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } }, "type": "object" } } } }, "403": {}, "404": {} } }, "post": { "tags": [ "03. Properties / Landlord-Tenant Adjustments" ], "summary": "Create a new landlord-tenant balance adjustment", "description": "Creates an adjustment via service layer (notes are HTML-sanitized) and sends bilateral notification (email + Telegram) to the opposite party.", "operationId": "post_app_api_landlordtenantadjustment_create", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "adjustment_date", "amount", "currency_id" ], "properties": { "adjustment_date": { "type": "string", "format": "date", "example": "2026-01-28" }, "amount": { "type": "number", "format": "float", "example": -150.5 }, "currency_id": { "type": "integer", "example": 1 }, "notes": { "type": "string", "example": "Correction for overbilling", "nullable": true }, "contract_id": { "type": "integer", "example": 5, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Adjustment created", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": {}, "403": {}, "404": {} } } }, "/api/v1/properties/{id}/lt-adjustments/{aid}": { "get": { "tags": [ "03. Properties / Landlord-Tenant Adjustments" ], "summary": "Get adjustment details", "operationId": "get_app_api_landlordtenantadjustment_show", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "aid", "in": "path", "description": "Adjustment ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Adjustment details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer" }, "adjustment_date": { "type": "string", "format": "date" }, "amount": { "type": "number", "format": "float" }, "currency": { "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "symbol": { "type": "string" } }, "type": "object" }, "notes": { "type": "string", "nullable": true }, "status": { "type": "string" }, "is_confirmed_by_landlord": { "type": "boolean" }, "landlord_confirmed_by": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "landlord_confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "is_confirmed_by_tenant": { "type": "boolean" }, "tenant_confirmed_by": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "tenant_confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "contract": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "documents": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "original_name": { "type": "string" }, "file_size": { "type": "integer" }, "comment": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "403": {}, "404": {} } }, "put": { "tags": [ "03. Properties / Landlord-Tenant Adjustments" ], "summary": "Update an adjustment", "description": "Updates an adjustment via service layer (notes are HTML-sanitized) and sends bilateral update notification to the opposite party. All body fields are optional (partial update).", "operationId": "put_app_api_landlordtenantadjustment_update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "aid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "adjustment_date": { "type": "string", "format": "date", "example": "2026-01-28" }, "amount": { "type": "number", "format": "float", "example": -150.5 }, "currency_id": { "type": "integer", "example": 1 }, "notes": { "type": "string", "example": "Updated notes", "nullable": true }, "contract_id": { "type": "integer", "example": 5, "nullable": true } }, "type": "object" } } } }, "responses": { "200": {}, "400": {}, "403": {}, "404": {} } }, "delete": { "tags": [ "03. Properties / Landlord-Tenant Adjustments" ], "summary": "Delete an adjustment", "description": "Deletes the adjustment with S3-first cascade removal of attached documents. Returns 500 if S3 deletion fails (DB row is then kept intact).", "operationId": "delete_app_api_landlordtenantadjustment_delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "aid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": {}, "403": {}, "404": {}, "500": {} } } }, "/api/v1/properties/{id}/lt-adjustments/{aid}/documents": { "post": { "tags": [ "03. Properties / Landlord-Tenant Adjustments" ], "summary": "Attach a document to adjustment", "description": "Attaches an existing property document (uploaded separately via the documents endpoint) to the adjustment. Comment is HTML-sanitized. Returns 400 if the document is already attached.", "operationId": "post_app_api_landlordtenantadjustment_attachdocument", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "aid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "document_id" ], "properties": { "document_id": { "type": "integer", "example": 42 }, "comment": { "type": "string", "example": "Invoice copy", "nullable": true } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "403": {}, "404": {} } } }, "/api/v1/properties/{id}/lt-adjustments/{aid}/documents/{did}": { "delete": { "tags": [ "03. Properties / Landlord-Tenant Adjustments" ], "summary": "Detach a document from adjustment", "description": "Removes the link between the adjustment and the document. The document itself is not deleted \u2014 use DELETE /documents/{id} for that.", "operationId": "delete_app_api_landlordtenantadjustment_detachdocument", "parameters": [ { "name": "did", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "aid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": {}, "403": {}, "404": {} } } }, "/api/v1/properties/{id}/lt-adjustments/{aid}/confirm-landlord": { "post": { "tags": [ "03. Properties / Landlord-Tenant Adjustments" ], "summary": "Confirm adjustment by landlord", "description": "Marks the adjustment as confirmed by the landlord and sends a notification to the tenant. Returns 400 if already confirmed.", "operationId": "post_app_api_landlordtenantadjustment_confirmbylandlord", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "aid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": {}, "400": {}, "403": {}, "404": {} } } }, "/api/v1/properties/{id}/lt-adjustments/{aid}/confirm-tenant": { "post": { "tags": [ "03. Properties / Landlord-Tenant Adjustments" ], "summary": "Confirm adjustment by tenant", "description": "Marks the adjustment as confirmed by the tenant and sends a notification to the landlord. Returns 400 if already confirmed.", "operationId": "post_app_api_landlordtenantadjustment_confirmbytenant", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "aid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": {}, "400": {}, "403": {}, "404": {} } } }, "/api/v1/languages": { "get": { "tags": [ "05. References / Languages" ], "summary": "List all languages", "description": "Returns list of all active languages. No authentication required.", "operationId": "get_api_languages_list", "responses": { "200": { "description": "List of languages", "content": { "application/json": { "schema": { "properties": { "languages": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "en" }, "name": { "type": "string", "example": "English" }, "native_name": { "type": "string", "example": "English" }, "is_default": { "type": "boolean", "example": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } }, "total": { "type": "integer", "example": 3 }, "default": { "type": "string", "example": "en" } }, "type": "object" } } } } } } }, "/api/v1/languages/{code}": { "get": { "tags": [ "05. References / Languages" ], "summary": "Get language by code", "description": "Returns language details by ISO 639-1 code", "operationId": "get_api_languages_show", "parameters": [ { "name": "code", "in": "path", "description": "ISO 639-1 language code (e.g., en, uk, ru)", "required": true, "schema": { "type": "string", "maxLength": 5, "minLength": 2 } } ], "responses": { "200": { "description": "Language details", "content": { "application/json": { "schema": { "properties": { "code": { "type": "string", "example": "en" }, "name": { "type": "string", "example": "English" }, "native_name": { "type": "string", "example": "English" }, "is_default": { "type": "boolean", "example": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "404": { "description": "Language not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Language not found" } }, "type": "object" } } } } } } }, "/api/v1/measurement-units": { "get": { "tags": [ "05. References / Units" ], "summary": "List all measurement units", "description": "Returns list of all measurement units with their codes, symbols and translations. No authentication required.", "operationId": "get_api_measurement_units_list", "responses": { "200": { "description": "List of measurement units", "content": { "application/json": { "schema": { "properties": { "measurement_units": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "kwh" }, "symbol": { "type": "string", "example": "kWh" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "sort_order": { "type": "integer", "example": 1 } }, "type": "object" } }, "total": { "type": "integer", "example": 10 } }, "type": "object" } } } } } } }, "/api/v1/measurement-units/{code}": { "get": { "tags": [ "05. References / Units" ], "summary": "Get measurement unit by code", "description": "Returns measurement unit details by code", "operationId": "get_api_measurement_units_show", "parameters": [ { "name": "code", "in": "path", "description": "Measurement unit code (e.g., kwh, m3, gcal)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Measurement unit details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "kwh" }, "symbol": { "type": "string", "example": "kWh" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "sort_order": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "404": { "description": "Measurement unit not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Measurement unit not found" } }, "type": "object" } } } } } } }, "/api/v1/properties/{propertyId}/negotiations": { "get": { "tags": [ "03. Properties / Negotiations" ], "summary": "List property contract negotiations", "description": "Returns list of contract negotiations for the property. Landlords and landlord agents only.", "operationId": "get_api_property_negotiations_list", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "sent", "viewed", "approved", "rejected", "expired" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Negotiations list", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "recipientEmail": { "type": "string" }, "recipientName": { "type": "string" }, "status": { "type": "string" }, "locale": { "type": "string" }, "hideRequisites": { "type": "boolean" }, "contractId": { "type": "integer", "nullable": true }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "viewedAt": { "type": "string", "format": "date-time", "nullable": true }, "respondedAt": { "type": "string", "format": "date-time", "nullable": true }, "response": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "isExpired": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "type": "object" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "totalPages": { "type": "integer" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Negotiations" ], "summary": "Create and send contract negotiation", "description": "Creates a contract negotiation via ContractNegotiationService (persist/flush), generates contract PDF, and sends email to recipient via NotificationService. Can use existing contract_id or create a new draft contract from blocks data. If email sending fails, the negotiation is still created and email_error is returned in the response body.", "operationId": "post_api_property_negotiations_create", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "recipient_email", "recipient_name" ], "properties": { "recipient_email": { "type": "string", "format": "email", "example": "tenant@example.com" }, "recipient_name": { "type": "string", "example": "John Doe" }, "locale": { "type": "string", "example": "uk" }, "hide_requisites": { "type": "boolean", "example": true }, "expires_in_days": { "type": "integer", "example": 14 }, "contract_type": { "type": "string", "example": "existing", "enum": [ "existing", "new" ] }, "contract_id": { "type": "integer", "example": 1 }, "rental_type_id": { "type": "integer", "example": 1 }, "blocks": { "description": "Block values for new contract (block_id => value)", "type": "object", "example": { "1": "10000", "2": "5" }, "additionalProperties": { "type": "string" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Negotiation created and email sent", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Negotiation created and email sent" }, "data": { "type": "object" } }, "type": "object" } } } }, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/negotiations/{id}": { "get": { "tags": [ "03. Properties / Negotiations" ], "summary": "Get negotiation details", "description": "Returns detailed information about a contract negotiation.", "operationId": "get_api_property_negotiations_show", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Negotiation details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Negotiations" ], "summary": "Delete negotiation", "description": "Delete a contract negotiation.", "operationId": "delete_api_property_negotiations_delete", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Negotiation deleted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Negotiation deleted" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/negotiations/{id}/resend": { "post": { "tags": [ "03. Properties / Negotiations" ], "summary": "Resend negotiation email", "description": "Regenerates the contract PDF and resends the negotiation email via NotificationService, then updates sent_at via ContractNegotiationService::markResent. Returns 400 if the negotiation is already responded (approved/rejected) or expired.", "operationId": "post_api_property_negotiations_resend", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Email resent", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Email resent successfully" } }, "type": "object" } } } }, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/nova-poshta/areas": { "get": { "tags": [ "07. Tools / Nova Poshta" ], "summary": "List all Ukrainian regions", "description": "Returns list of all Ukrainian regions (oblasts) from Nova Poshta API. Public endpoint.", "operationId": "get_api_nova_poshta_areas", "responses": { "200": { "description": "List of areas", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "ref": { "type": "string", "example": "71508128-9b87-11de-822f-000c2965ae0e" }, "name": { "type": "string", "example": "Kyivska" } }, "type": "object" } }, "total": { "type": "integer", "example": 25 } }, "type": "object" } } } } } } }, "/api/v1/nova-poshta/cities": { "get": { "tags": [ "07. Tools / Nova Poshta" ], "summary": "List cities in a region", "description": "Returns list of cities in a specific region by area_ref, optionally filtered by name. City list is cached per area; search is applied as a client-side filter without additional API calls. Public endpoint.", "operationId": "get_api_nova_poshta_cities", "parameters": [ { "name": "area_ref", "in": "query", "description": "Nova Poshta area reference (UUID)", "required": true, "schema": { "type": "string", "example": "71508128-9b87-11de-822f-000c2965ae0e" } }, { "name": "search", "in": "query", "description": "City name filter (minimum 2 characters; shorter values are ignored)", "required": false, "schema": { "type": "string", "example": "\u0414\u043d\u0456\u043f\u0440\u043e", "minLength": 2 } } ], "responses": { "200": { "description": "List of cities", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "ref": { "type": "string", "example": "e221d627-391c-11dd-90d9-001a92567626" }, "name": { "type": "string", "example": "Kyiv" }, "region": { "type": "string", "example": "Kyivskyi", "nullable": true } }, "type": "object" } }, "total": { "type": "integer", "example": 100 } }, "type": "object" } } } }, "400": { "description": "Missing area_ref parameter", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "area_ref parameter is required" } }, "type": "object" } } } } } } }, "/api/v1/nova-poshta/streets": { "get": { "tags": [ "07. Tools / Nova Poshta" ], "summary": "Search streets in a city", "description": "Searches for streets in a specific city by name. Minimum 2 characters required. Public endpoint.", "operationId": "get_api_nova_poshta_streets", "parameters": [ { "name": "city_ref", "in": "query", "description": "Nova Poshta city reference (UUID)", "required": true, "schema": { "type": "string", "example": "e221d627-391c-11dd-90d9-001a92567626" } }, { "name": "search", "in": "query", "description": "Street name search query (minimum 2 characters)", "required": true, "schema": { "type": "string", "example": "Main", "minLength": 2 } } ], "responses": { "200": { "description": "List of matching streets", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "ref": { "type": "string", "example": "18e2ffc8-d68d-11e3-9937-003048d2b473" }, "name": { "type": "string", "example": "Khreshchatyk" }, "type": { "type": "string", "example": "street", "nullable": true } }, "type": "object" } }, "total": { "type": "integer", "example": 5 } }, "type": "object" } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "city_ref and search parameters are required" } }, "type": "object" } } } } } } }, "/api/v1/nova-poshta/search-by-zip": { "get": { "tags": [ "07. Tools / Nova Poshta" ], "summary": "Search city by postal code", "description": "Find city, region and area by Ukrainian postal code (5 digits). Public endpoint.", "operationId": "get_api_nova_poshta_search_by_zip", "parameters": [ { "name": "zip", "in": "query", "description": "Ukrainian postal code (5 digits)", "required": true, "schema": { "type": "string", "example": "01001" } } ], "responses": { "200": { "description": "City found" }, "404": { "description": "Postal code not found" } } } }, "/api/v1/partner-invitations": { "get": { "tags": [ "11. Partner Invitations" ], "summary": "List partner invitations", "description": "Returns list of partner invitations created by the current user.", "operationId": "get_api_partner_invitations_list", "parameters": [ { "name": "name", "in": "query", "schema": { "type": "string" } }, { "name": "email", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "invited", "confirmed", "declined" ] } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Partner invitations list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "locale": { "type": "string" }, "status": { "type": "string" }, "invited_at": { "type": "string", "format": "date-time" }, "confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "declined_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "totalPages": { "type": "integer" }, "statistics": { "properties": { "invited": { "type": "integer" }, "confirmed": { "type": "integer" }, "declined": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "11. Partner Invitations" ], "summary": "Create partner invitation", "description": "Create a new partner invitation and send email to the invited person.", "operationId": "post_api_partner_invitations_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email" ], "properties": { "name": { "type": "string", "example": "John Doe", "maxLength": 200, "minLength": 2 }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "locale": { "type": "string", "example": "uk", "enum": [ "uk", "en", "ru", "pl", "de" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Invitation created successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" }, "invitation": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "status": { "type": "string" }, "invited_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "updated": { "type": "boolean" } }, "type": "object" } } } }, "400": { "description": "Validation error or business logic error", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "enum": [ "validation_failed", "already_registered", "declined_cannot_reinvite", "already_confirmed" ] }, "message": { "type": "string" } }, "type": "object" } } } }, "401": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/partner-invitations/{id}": { "get": { "tags": [ "11. Partner Invitations" ], "summary": "Get partner invitation details", "description": "Returns details of a specific partner invitation.", "operationId": "get_api_partner_invitations_show", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Invitation details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "locale": { "type": "string" }, "status": { "type": "string" }, "invited_at": { "type": "string", "format": "date-time" }, "confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "declined_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/partner-invitations/{id}/resend": { "post": { "tags": [ "11. Partner Invitations" ], "summary": "Resend partner invitation", "description": "Resend the invitation email to the invited person. Only works for invitations with status \"invited\".", "operationId": "post_api_partner_invitations_resend", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Invitation resent successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "type": "object" } } } }, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/payments": { "get": { "tags": [ "03. Properties / Payments" ], "summary": "List user payments", "description": "Returns list of all payments accessible to the authenticated user across all their properties. Payments are linked through ExpenseCharge \u2192 PropertyExpense \u2192 ExpenseProvider chain.", "operationId": "get_api_payments_list", "parameters": [ { "name": "property_id", "in": "query", "schema": { "type": "integer" } }, { "name": "expense_type_id", "in": "query", "schema": { "type": "integer" } }, { "name": "service_provider_id", "in": "query", "schema": { "type": "integer" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date", "example": "2026-01-31" } }, { "name": "amount_from", "in": "query", "schema": { "type": "string", "example": "100.00" } }, { "name": "amount_to", "in": "query", "schema": { "type": "string", "example": "1000.00" } }, { "name": "is_active", "in": "query", "schema": { "type": "boolean" } }, { "name": "owner_confirmation", "in": "query", "schema": { "type": "string", "enum": [ "UNKNOWN", "CONFIRMED", "REJECTED" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Payments list with pagination", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer", "example": 42 }, "totalAmount": { "type": "string", "example": "15234.50" }, "page": { "type": "integer", "example": 1 }, "totalPages": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "401": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/payments": { "get": { "tags": [ "03. Properties / Payments" ], "summary": "List property payments", "description": "Returns payments for a specific property. Visibility depends on user role: owners see all, tenants see active payments, maintenance sees only their recipient payments.", "operationId": "get_api_property_payments_list", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "expense_type_id", "in": "query", "schema": { "type": "integer" } }, { "name": "service_provider_id", "in": "query", "schema": { "type": "integer" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date", "example": "2026-01-31" } }, { "name": "amount_from", "in": "query", "schema": { "type": "string" } }, { "name": "amount_to", "in": "query", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "schema": { "type": "boolean" } }, { "name": "owner_confirmation", "in": "query", "schema": { "type": "string", "enum": [ "UNKNOWN", "CONFIRMED", "REJECTED" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Payments list with pagination and total amount", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer", "example": 15 }, "totalAmount": { "type": "string", "example": "3450.00" }, "page": { "type": "integer", "example": 1 }, "totalPages": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Payments" ], "summary": "Create payment", "description": "Creates a new payment linked to an expense charge (utilities) OR a rental charge (rent). Provide exactly one of expense_charge_id or rental_charge_id.", "operationId": "post_api_property_payments_create", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "payment_date", "amount", "currency_id" ], "properties": { "payment_date": { "type": "string", "format": "date", "example": "2026-01-15" }, "amount": { "type": "string", "example": "150.50" }, "currency_id": { "type": "integer", "example": 1 }, "expense_charge_id": { "type": "integer", "example": 42, "nullable": true }, "rental_charge_id": { "type": "integer", "example": 17, "nullable": true }, "contract_id": { "type": "integer", "example": 5, "nullable": true }, "payer_user_id": { "type": "integer", "example": 10, "nullable": true }, "notes": { "type": "string", "example": "January electricity payment", "nullable": true }, "is_active": { "type": "boolean", "example": true, "default": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Payment created successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Payment created successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "errors": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "401": {}, "403": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/payments/{id}": { "get": { "tags": [ "03. Properties / Payments" ], "summary": "Get payment details", "description": "Returns payment details including attached receipt file. Recipient is determined through Payment \u2192 ExpenseCharge \u2192 PropertyExpense \u2192 ExpenseProvider chain.", "operationId": "get_api_property_payments_show", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment details with file attachment", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "type": "integer", "example": 1 }, "property_id": { "type": "integer", "example": 5 }, "property_name": { "type": "string", "example": "Apartment Kyiv" }, "payment_date": { "type": "string", "format": "date", "example": "2026-01-15" }, "amount": { "type": "string", "example": "1500.00" }, "amount_formatted": { "type": "string", "example": "1,500.00 \u20b4" }, "currency": { "properties": { "id": { "type": "integer", "example": 3 }, "code": { "type": "string", "example": "UAH" }, "symbol": { "type": "string", "example": "\u20b4" } }, "type": "object" }, "expense_type": { "properties": { "id": { "type": "integer", "example": 2 }, "code": { "type": "string", "example": "ELECTRICITY" }, "name_key": { "type": "string", "example": "expense_type.electricity" } }, "type": "object", "nullable": true }, "service_provider": { "properties": { "id": { "type": "integer", "example": 3 }, "name": { "type": "string", "example": "Kyivenergo" } }, "type": "object", "nullable": true }, "recipient_user": { "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "John Maintenance" } }, "type": "object", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "owner_confirmation": { "type": "string", "example": "CONFIRMED", "enum": [ "UNKNOWN", "CONFIRMED", "REJECTED" ] }, "notes": { "type": "string", "example": "January electricity payment", "nullable": true }, "has_file": { "type": "boolean", "example": true }, "file_url": { "type": "string", "example": "https://llm.com/file/cGF5bWVudDoxOjA6ZWEyNTYuLi4", "nullable": true }, "file_name": { "type": "string", "example": "receipt.pdf", "nullable": true }, "created_by": { "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "John Doe" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-01-15 10:30:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-01-15 10:30:00" } }, "type": "object" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "03. Properties / Payments" ], "summary": "Update payment", "description": "Updates an existing payment. All fields from create request can be updated.", "operationId": "put_api_property_payments_update", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "payment_date", "amount", "currency_id", "expense_charge_id" ], "properties": { "payment_date": { "type": "string", "format": "date", "example": "2026-01-15" }, "amount": { "type": "string", "example": "150.50" }, "currency_id": { "type": "integer", "example": 1 }, "expense_charge_id": { "type": "integer", "example": 42 }, "contract_id": { "type": "integer", "example": 5, "nullable": true }, "payer_user_id": { "type": "integer", "example": 10, "nullable": true }, "notes": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "default": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment updated successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Payment updated successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "400": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Payments" ], "summary": "Delete payment", "description": "Permanently deletes a payment including attached file from S3 storage. Only owners/agents or payment author can delete.", "operationId": "delete_api_property_payments_delete", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Payment deleted successfully" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/payments/{id}/confirm": { "post": { "tags": [ "03. Properties / Payments" ], "summary": "Confirm payment", "description": "Property owner or agent confirms the payment as valid. Changes owner_confirmation to CONFIRMED.", "operationId": "post_api_property_payments_confirm", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment confirmed successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Payment confirmed" }, "data": { "type": "object" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/payments/{id}/reject": { "post": { "tags": [ "03. Properties / Payments" ], "summary": "Reject payment", "description": "Property owner or agent rejects the payment as invalid. Changes owner_confirmation to REJECTED.", "operationId": "post_api_property_payments_reject", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment rejected successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Payment rejected" }, "data": { "type": "object" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/penalties": { "get": { "tags": [ "03. Properties / Penalties" ], "summary": "List property contract penalties", "description": "Returns list of contract penalties for the property.", "operationId": "get_api_property_penalties_list", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "contract_id", "in": "query", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Penalties list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "totalPages": { "type": "integer" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Penalties" ], "summary": "Create contract penalty", "description": "Creates a new contract penalty via PenaltyService (description is HTML-sanitized, linked agreement blocks are synced). If the contract has a tenant, it is auto-assigned as violator.", "operationId": "post_api_property_penalties_create", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "contract_id", "penalty_date", "amount", "currency_id", "description" ], "properties": { "contract_id": { "type": "integer", "example": 1 }, "penalty_date": { "type": "string", "format": "date", "example": "2024-01-15" }, "amount": { "description": "Penalty amount", "type": "number", "format": "float", "example": 500 }, "paid_amount": { "description": "Amount already paid (default 0)", "type": "number", "format": "float", "example": 0 }, "currency_id": { "type": "integer", "example": 1 }, "description": { "type": "string", "maxLength": 5000 }, "block_ids": { "type": "array", "items": { "type": "integer" }, "nullable": true } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/penalties/{id}": { "get": { "tags": [ "03. Properties / Penalties" ], "summary": "Get contract penalty details", "description": "Returns penalty details including attached documents and linked contract blocks.", "operationId": "get_api_property_penalties_show", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Penalty details with documents", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "type": "integer" }, "property_id": { "type": "integer" }, "contract_id": { "type": "integer" }, "penalty_date": { "type": "string", "format": "date" }, "amount": { "type": "number", "format": "float" }, "currency": { "type": "object", "nullable": true }, "description": { "type": "string" }, "violator": { "type": "object", "nullable": true }, "contract": { "type": "object", "nullable": true }, "documents": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "original_name": { "type": "string" }, "file_size": { "type": "integer" }, "file_url": { "type": "string" } }, "type": "object" } }, "blocks": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "block_code": { "type": "string" }, "block_name_key": { "type": "string" }, "penalty_date": { "type": "string", "format": "date" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "03. Properties / Penalties" ], "summary": "Update contract penalty", "description": "Updates the penalty via PenaltyService (description is HTML-sanitized, block links are re-synced). All body fields are optional (partial update).", "operationId": "put_api_property_penalties_update", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "penalty_date": { "type": "string", "format": "date" }, "amount": { "type": "number", "format": "float" }, "currency_id": { "type": "integer" }, "description": { "type": "string" }, "block_ids": { "type": "array", "items": { "type": "integer" } } }, "type": "object" } } } }, "responses": { "200": {}, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Penalties" ], "summary": "Delete contract penalty", "description": "Deletes a contract penalty with S3-first cascade removal of attached documents. Returns 500 if S3 deletion fails (DB row is then kept intact).", "operationId": "delete_api_property_penalties_delete", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "401": {}, "403": {}, "404": {}, "500": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/penalties/{id}/documents": { "post": { "tags": [ "03. Properties / Penalties" ], "summary": "Attach document to penalty", "description": "Upload and attach a document to the penalty.", "operationId": "post_api_property_penalties_attach_document", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/penalties/{id}/documents/{documentId}": { "delete": { "tags": [ "03. Properties / Penalties" ], "summary": "Detach document from penalty", "description": "Remove a document from the penalty (does not delete the document itself).", "operationId": "delete_api_property_penalties_detach_document", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/communications": { "get": { "tags": [ "03. Properties / Communications" ], "summary": "List property communications", "description": "Returns list of all communications for a property. User must have access.", "operationId": "get_api_communications_list", "parameters": [ { "name": "propertyId", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "active_only", "in": "query", "description": "Return only active communications", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Communications list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Communications" ], "summary": "Create communication", "description": "Creates a new communication via CommunicationService (fields are HTML-sanitized, persisted via service layer \u2014 same path as the web UI). User must have EDIT access.", "operationId": "post_api_communications_create", "parameters": [ { "name": "propertyId", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "communication_type_id" ], "properties": { "communication_type_id": { "type": "integer", "example": 1 }, "information": { "type": "string", "example": "Provider: Kyivstar" }, "login": { "type": "string", "nullable": true }, "password": { "type": "string", "nullable": true }, "access_address": { "type": "string", "example": "192.168.1.1", "nullable": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Communication created", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "data": { "type": "object" } }, "type": "object" } } } }, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/communications/{id}": { "get": { "tags": [ "03. Properties / Communications" ], "summary": "Get communication details", "description": "Returns communication details with attached documents.", "operationId": "get_api_communications_show", "parameters": [ { "name": "id", "in": "path", "description": "Communication ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Communication details with documents", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer" }, "property_id": { "type": "integer" }, "communication_type": { "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "name_key": { "type": "string" }, "icon_url": { "type": "string" } }, "type": "object" }, "information": { "type": "string", "nullable": true }, "login": { "type": "string", "nullable": true }, "password_set": { "type": "boolean" }, "access_address": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "is_currently_active": { "description": "Kept for backward compatibility. Now identical to is_active (date-based activation removed).", "type": "boolean" }, "documents": { "type": "array", "items": { "properties": { "link_id": { "type": "integer" }, "comment": { "type": "string", "nullable": true }, "document": { "properties": { "id": { "type": "integer" }, "original_name": { "type": "string" }, "file_url": { "type": "string" }, "file_size_formatted": { "type": "string" }, "is_image": { "type": "boolean" } }, "type": "object" } }, "type": "object" } }, "documents_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "03. Properties / Communications" ], "summary": "Update communication", "description": "Updates the communication via CommunicationService (fields are HTML-sanitized). All body fields are optional (partial update). User must have EDIT access.", "operationId": "put_api_communications_update", "parameters": [ { "name": "id", "in": "path", "description": "Communication ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "information": { "type": "string" }, "login": { "type": "string", "nullable": true }, "password": { "type": "string", "nullable": true }, "access_address": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Communications" ], "summary": "Delete communication", "description": "Deletes a communication. User must have edit access.", "operationId": "delete_api_communications_delete", "parameters": [ { "name": "id", "in": "path", "description": "Communication ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Communication deleted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/communications/{id}/documents/upload": { "post": { "tags": [ "03. Properties / Communications" ], "summary": "Upload document to communication", "description": "Uploads a file via DocumentService (S3 storage + drive sync) and attaches it to the communication via CommunicationService::attachDocument. Comment is HTML-sanitized.", "operationId": "post_api_communications_upload_document", "parameters": [ { "name": "id", "in": "path", "description": "Communication ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file", "document_type_id" ], "properties": { "file": { "type": "string", "format": "binary" }, "document_type_id": { "type": "integer" }, "comment": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Document uploaded and attached", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "data": { "properties": { "comment": { "type": "string", "nullable": true }, "document": { "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/communications/{id}/documents": { "post": { "tags": [ "03. Properties / Communications" ], "summary": "Attach existing document to communication", "description": "Links an existing property document to the communication via CommunicationService::attachDocument. Comment is HTML-sanitized.", "operationId": "post_api_communications_attach_document", "parameters": [ { "name": "id", "in": "path", "description": "Communication ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "document_id" ], "properties": { "document_id": { "type": "integer", "example": 5 }, "comment": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "401": {}, "403": {}, "404": {}, "409": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/communications/{id}/documents/{documentId}": { "delete": { "tags": [ "03. Properties / Communications" ], "summary": "Detach document from communication", "description": "Removes the link between document and communication.", "operationId": "delete_api_communications_remove_document", "parameters": [ { "name": "id", "in": "path", "description": "Communication ID", "required": true, "schema": { "type": "integer" } }, { "name": "documentId", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties": { "get": { "tags": [ "03. Properties" ], "summary": "List user properties", "description": "Returns list of all properties accessible to the authenticated user.", "operationId": "get_api_properties_list", "responses": { "200": { "description": "Properties list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "My Apartment" }, "description": { "type": "string", "example": "Cozy apartment in city center", "nullable": true }, "color": { "type": "string", "example": "#3498DB" }, "property_type": { "properties": { "id": { "type": "integer", "example": 2 }, "code": { "type": "string", "example": "APARTMENT" }, "name_key": { "type": "string", "example": "property_type.apartment" } }, "type": "object" }, "country": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "UA" }, "name_key": { "type": "string", "example": "country.ua" } }, "type": "object", "nullable": true }, "address": { "properties": { "area_ref": { "type": "string", "example": "71508128-9b87-11de-822f-000c2965ae0e" }, "area_name": { "type": "string", "example": "Example Region" }, "city_ref": { "type": "string", "example": "e221d627-391c-11dd-90d9-001a92567626" }, "city_name": { "type": "string", "example": "Example City" }, "street_ref": { "type": "string", "example": "18e2ffc8-d68d-11e3-9937-003048d2b473", "nullable": true }, "street_name": { "type": "string", "example": "Main Street", "nullable": true }, "building_number": { "type": "string", "example": "1A" }, "apartment_number": { "type": "string", "example": "42", "nullable": true }, "full_address": { "type": "string", "example": "Example Region, Example City, Main Street, 1A, apt. 42" } }, "type": "object" }, "user_role": { "type": "string", "example": "PROPERTY_LANDLORD", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00+00:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-01-20T14:15:00+00:00" } }, "type": "object" } }, "total": { "type": "integer", "example": 5 } }, "type": "object" } } } }, "401": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties" ], "summary": "Create property", "description": "Creates a new property via PropertyService (fields are HTML-sanitized, owner is auto-assigned as PROPERTY_LANDLORD). The authenticated user becomes the owner.", "operationId": "post_api_properties_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "property_type_id", "area_ref", "city_ref", "building_number" ], "properties": { "name": { "type": "string", "example": "My Apartment", "maxLength": 255, "minLength": 2 }, "description": { "type": "string", "example": "Apartment in city center", "nullable": true }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "example": "#3498DB" }, "property_type_id": { "type": "integer", "example": 2 }, "area_ref": { "type": "string", "example": "71508128-9b87-11de-822f-000c2965ae0e" }, "area_name": { "type": "string", "example": "Kyiv Oblast", "nullable": true }, "city_ref": { "type": "string", "example": "e221d627-391c-11dd-90d9-001a92567626" }, "city_name": { "type": "string", "example": "Kyiv", "nullable": true }, "street_ref": { "type": "string", "example": "18e2ffc8-d68d-11e3-9937-003048d2b473", "nullable": true }, "street_name": { "type": "string", "example": "Khreschatyk", "nullable": true }, "building_number": { "type": "string", "example": "1A", "maxLength": 20 }, "apartment_number": { "type": "string", "example": "42", "nullable": true, "maxLength": 20 }, "country_id": { "type": "integer", "example": 1 }, "living_area": { "type": "number", "format": "float", "example": 45.5, "nullable": true }, "total_area": { "type": "number", "format": "float", "example": 12.3, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Property created", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Property created successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "My Apartment" }, "description": { "type": "string", "example": "Apartment in city center", "nullable": true }, "color": { "type": "string", "example": "#3498DB" }, "property_type": { "properties": { "id": { "type": "integer", "example": 2 }, "code": { "type": "string", "example": "APARTMENT" }, "name_key": { "type": "string", "example": "property_type.apartment" } }, "type": "object" }, "country": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "UA" }, "name_key": { "type": "string", "example": "country.ua" } }, "type": "object", "nullable": true }, "address": { "properties": { "area_ref": { "type": "string", "example": "71508128-9b87-11de-822f-000c2965ae0e" }, "area_name": { "type": "string", "example": "Example Region" }, "city_ref": { "type": "string", "example": "e221d627-391c-11dd-90d9-001a92567626" }, "city_name": { "type": "string", "example": "Example City" }, "street_ref": { "type": "string", "example": "18e2ffc8-d68d-11e3-9937-003048d2b473", "nullable": true }, "street_name": { "type": "string", "example": "Main Street", "nullable": true }, "building_number": { "type": "string", "example": "1A" }, "apartment_number": { "type": "string", "example": "42", "nullable": true }, "full_address": { "type": "string", "example": "Example Region, Example City, Main Street, 1A, apt. 42" } }, "type": "object" }, "user_role": { "type": "string", "example": "PROPERTY_LANDLORD" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00+00:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00+00:00" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Validation failed" }, "errors": { "type": "array", "items": { "type": "string" }, "example": [ "Name is required and must be at least 2 characters" ] } }, "type": "object" } } } }, "401": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{id}": { "get": { "tags": [ "03. Properties" ], "summary": "Property details", "description": "Returns detailed information about a property. User must have access to the property.", "operationId": "get_api_properties_show", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Property details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "My Apartment" }, "description": { "type": "string", "example": "Cozy apartment in city center", "nullable": true }, "color": { "type": "string", "example": "#3498DB" }, "property_type": { "properties": { "id": { "type": "integer", "example": 2 }, "code": { "type": "string", "example": "APARTMENT" }, "name_key": { "type": "string", "example": "property_type.apartment" } }, "type": "object" }, "country": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "UA" }, "name_key": { "type": "string", "example": "country.ua" } }, "type": "object", "nullable": true }, "address": { "properties": { "area_ref": { "type": "string", "example": "71508128-9b87-11de-822f-000c2965ae0e" }, "area_name": { "type": "string", "example": "Example Region" }, "city_ref": { "type": "string", "example": "e221d627-391c-11dd-90d9-001a92567626" }, "city_name": { "type": "string", "example": "Example City" }, "street_ref": { "type": "string", "example": "18e2ffc8-d68d-11e3-9937-003048d2b473", "nullable": true }, "street_name": { "type": "string", "example": "Main Street", "nullable": true }, "building_number": { "type": "string", "example": "1A" }, "apartment_number": { "type": "string", "example": "42", "nullable": true }, "full_address": { "type": "string", "example": "Example Region, Example City, Main Street, 1A, apt. 42" } }, "type": "object" }, "user_role": { "type": "string", "example": "PROPERTY_LANDLORD", "nullable": true }, "users": { "description": "List of users (only for owner)", "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 5 }, "email": { "type": "string", "example": "user@example.com" }, "name": { "type": "string", "example": "John Smith" }, "role": { "properties": { "id": { "type": "integer", "example": 10 }, "code": { "type": "string", "example": "PROPERTY_LANDLORD" }, "name_key": { "type": "string", "example": "role.property_landlord" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00+00:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-01-20T14:15:00+00:00" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "404": { "description": "Property not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Property not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "03. Properties" ], "summary": "Update property", "description": "Updates an existing property via PropertyService (fields are HTML-sanitized). User must have EDIT permissions (PROPERTY_LANDLORD or PROPERTY_LANDLORD_AGENT).", "operationId": "put_api_properties_update", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "My Apartment", "maxLength": 255, "minLength": 2 }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "property_type_id": { "type": "integer" }, "area_ref": { "type": "string" }, "area_name": { "type": "string" }, "city_ref": { "type": "string" }, "city_name": { "type": "string" }, "street_ref": { "type": "string", "nullable": true }, "street_name": { "type": "string", "nullable": true }, "building_number": { "type": "string" }, "apartment_number": { "type": "string", "nullable": true }, "country_id": { "type": "integer", "nullable": true }, "living_area": { "type": "number", "format": "float", "nullable": true }, "total_area": { "type": "number", "format": "float", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Property updated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Property updated successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "My Apartment" }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "example": "#3498DB" }, "property_type": { "properties": { "id": { "type": "integer", "example": 2 }, "code": { "type": "string", "example": "APARTMENT" }, "name_key": { "type": "string", "example": "property_type.apartment" } }, "type": "object" }, "country": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "UA" }, "name_key": { "type": "string", "example": "country.ua" } }, "type": "object", "nullable": true }, "address": { "properties": { "area_ref": { "type": "string" }, "area_name": { "type": "string" }, "city_ref": { "type": "string" }, "city_name": { "type": "string" }, "street_ref": { "type": "string", "nullable": true }, "street_name": { "type": "string", "nullable": true }, "building_number": { "type": "string" }, "apartment_number": { "type": "string", "nullable": true }, "full_address": { "type": "string" } }, "type": "object" }, "user_role": { "type": "string", "example": "PROPERTY_LANDLORD" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Name must be at least 2 characters" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "You cannot edit this property" } }, "type": "object" } } } }, "404": { "description": "Property not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Property not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties" ], "summary": "Delete property", "description": "Deletes the property via PropertyDeletionService (4-phase cascade: S3 documents \u2192 SQL children \u2192 Doctrine children \u2192 property). Only the owner (PROPERTY_LANDLORD) can delete. Returns 500 if cascade fails.", "operationId": "delete_api_properties_delete", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Property deleted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Property deleted successfully" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Only owner can delete", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Only owner can delete this property" } }, "type": "object" } } } }, "404": { "description": "Property not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Property not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{id}/users": { "get": { "tags": [ "03. Properties" ], "summary": "List property users", "description": "Returns list of all users associated with the property. Only owner can view.", "operationId": "get_api_properties_users_list", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Users list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "user_id": { "type": "integer", "example": 5 }, "email": { "type": "string", "example": "user@example.com" }, "name": { "type": "string", "example": "John Smith" }, "role": { "properties": { "id": { "type": "integer", "example": 10 }, "code": { "type": "string", "example": "PROPERTY_TENANT" }, "name_key": { "type": "string", "example": "role.property_tenant" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Only owner can view", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Only owner can view users" } }, "type": "object" } } } }, "404": { "description": "Property not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Property not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties" ], "summary": "Add user to property", "description": "Adds a user with the specified role to the property via PropertyService::addUserToProperty. Only owner can add users. Cannot add PROPERTY_LANDLORD role (that role belongs to the property owner only).", "operationId": "post_api_properties_users_add", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_id", "role_id" ], "properties": { "user_id": { "type": "integer", "example": 5 }, "role_id": { "type": "integer", "example": 12 } }, "type": "object" } } } }, "responses": { "201": { "description": "User added", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "User added successfully" }, "data": { "properties": { "id": { "type": "integer", "example": 15 }, "user_id": { "type": "integer", "example": 5 }, "email": { "type": "string", "example": "tenant@example.com" }, "name": { "type": "string", "example": "John Smith" }, "role": { "properties": { "id": { "type": "integer", "example": 12 }, "code": { "type": "string", "example": "PROPERTY_TENANT" }, "name_key": { "type": "string", "example": "role.property_tenant" } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-20T14:30:00+00:00" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "user_id and role_id are required" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Only owner can add", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Only owner can add users" } }, "type": "object" } } } }, "404": { "description": "Property/user/role not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "User not found" } }, "type": "object" } } } }, "409": { "description": "User already added", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "User already has access to this property" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{id}/users/{userId}": { "delete": { "tags": [ "03. Properties" ], "summary": "Remove user from property", "description": "Removes a user from the property via PropertyService::removeUserFromProperty. Only owner can remove. Cannot remove the owner.", "operationId": "delete_api_properties_users_remove", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "userId", "in": "path", "description": "User ID to remove", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "User removed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "User removed successfully" } }, "type": "object" } } } }, "400": { "description": "Cannot remove owner", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Cannot remove owner from property" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Only owner can remove", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Only owner can remove users" } }, "type": "object" } } } }, "404": { "description": "Property or user not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "User is not associated with this property" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{id}/search-user": { "get": { "tags": [ "03. Properties" ], "summary": "Search user", "description": "Searches for a user by email or phone. Returns result only if exactly 1 user is found (privacy protection).", "operationId": "get_api_properties_search_user", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "q", "in": "query", "description": "Search query (email or phone)", "required": true, "schema": { "type": "string", "minLength": 3 } } ], "responses": { "200": { "description": "Search result", "content": { "application/json": { "schema": { "properties": { "user": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "error": { "type": "string", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Only owner can search", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Only owner can search users" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{id}/available-roles": { "get": { "tags": [ "03. Properties" ], "summary": "Available roles", "description": "Returns list of roles that can be assigned to property users (all PROPERTY_* roles except LANDLORD).", "operationId": "get_api_properties_available_roles", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Roles list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 10 }, "code": { "type": "string", "example": "PROPERTY_TENANT" }, "name_key": { "type": "string", "example": "role.property_tenant" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Access denied" } }, "type": "object" } } } }, "404": { "description": "Property not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Property not found" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/generate-description": { "post": { "tags": [ "03. Properties" ], "summary": "Generate property description via AI", "description": "Generates a property description using Grok AI based on provided form data.", "operationId": "post_api_properties_generate_description", "requestBody": { "content": { "application/json": { "schema": { "properties": { "propertyTypeCode": { "type": "string", "example": "APARTMENT" }, "address": { "type": "string", "example": "Kyiv, Khreshchatyk 1" }, "totalArea": { "type": "string", "example": "75" }, "livingArea": { "type": "string", "example": "55" }, "characteristics": { "type": "object", "example": { "ROOM_COUNT": "3", "FLOOR": "5" } }, "locale": { "type": "string", "example": "uk" } }, "type": "object" } } } }, "responses": { "200": { "description": "Generated description", "content": { "application/json": { "schema": { "properties": { "description": { "type": "string" } }, "type": "object" } } } }, "400": {}, "500": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/geocode": { "post": { "tags": [ "03. Properties" ], "summary": "Geocode address to coordinates", "description": "Returns lat/lng for given city, street, building via OpenStreetMap Nominatim.", "operationId": "post_api_properties_geocode", "requestBody": { "content": { "application/json": { "schema": { "properties": { "city": { "type": "string", "example": "Kyiv" }, "street": { "type": "string", "example": "Khreshchatyk" }, "building": { "type": "string", "example": "1" } }, "type": "object" } } } }, "responses": { "200": { "description": "Coordinates", "content": { "application/json": { "schema": { "properties": { "lat": { "type": "number", "example": 50.4501 }, "lng": { "type": "number", "example": 30.5234 } }, "type": "object" } } } }, "404": { "description": "Address not found" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{id}/descriptions": { "get": { "tags": [ "03. Properties" ], "summary": "List property description translations", "description": "Returns all description translations for a property.", "operationId": "get_api_properties_descriptions_list", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Description translations", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "locale": { "type": "string", "example": "en" }, "description": { "type": "string", "example": "

Spacious apartment...

" }, "updated_at": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties" ], "summary": "Save property description translation", "description": "Create or update a description translation for a specific locale.", "operationId": "post_api_properties_descriptions_save", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "locale": { "type": "string", "example": "en" }, "description": { "type": "string", "example": "

Spacious apartment...

" } }, "type": "object" } } } }, "responses": { "200": { "description": "Saved" }, "400": { "description": "Validation error" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{id}/descriptions/translate": { "post": { "tags": [ "03. Properties" ], "summary": "Translate property description via AI", "description": "Translates the main property description to a target locale using Grok AI.", "operationId": "post_api_properties_descriptions_translate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "target_locale": { "type": "string", "example": "en" }, "source_html": { "type": "string", "example": "

\u041f\u0440\u043e\u0441\u0442\u043e\u0440\u0430 \u043a\u0432\u0430\u0440\u0442\u0438\u0440\u0430...

" } }, "type": "object" } } } }, "responses": { "200": { "description": "Translated HTML" }, "400": { "description": "Missing parameters" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/property-data-types": { "get": { "tags": [ "05. References / Property Data Types" ], "summary": "List property data types", "description": "Returns list of all active property data types. Can filter by group.", "operationId": "get_api_property_data_types_list", "parameters": [ { "name": "group", "in": "query", "description": "Filter by group code (building, apartment, infrastructure, utilities, security, parking, land, other)", "required": false, "schema": { "type": "string", "example": "apartment" } }, { "name": "data_type", "in": "query", "description": "Filter by data type (string, bool, int, float)", "required": false, "schema": { "type": "string", "example": "bool" } } ], "responses": { "200": { "description": "Property data types list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "FLOOR_COUNT" }, "name_key": { "type": "string", "example": "property_data_type.floor_count.name" }, "data_type": { "type": "string", "example": "int" }, "group_code": { "type": "string", "example": "building" }, "icon_url": { "type": "string", "example": "https://s3.example.com/property_data_type/1.svg" }, "unit": { "type": "string", "example": "m\u00b2", "nullable": true }, "is_system": { "type": "boolean", "example": true } }, "type": "object" } }, "total": { "type": "integer", "example": 159 } }, "type": "object" } } } } } } }, "/api/v1/property-data-types/grouped": { "get": { "tags": [ "05. References / Property Data Types" ], "summary": "List property data types grouped by category", "description": "Returns all active property data types organized by group.", "operationId": "get_api_property_data_types_grouped", "responses": { "200": { "description": "Grouped property data types", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object", "example": { "building": [ { "id": 1, "code": "FLOOR_COUNT", "name_key": "property_data_type.floor_count.name" } ], "apartment": [ { "id": 17, "code": "ROOM_COUNT", "name_key": "property_data_type.room_count.name" } ] } }, "groups": { "type": "array", "items": { "type": "string" }, "example": [ "building", "apartment", "infrastructure", "utilities", "security", "parking", "land", "other" ] }, "total": { "type": "integer", "example": 159 } }, "type": "object" } } } } } } }, "/api/v1/property-data-types/{code}": { "get": { "tags": [ "05. References / Property Data Types" ], "summary": "Get property data type by code", "description": "Returns property data type details by code.", "operationId": "get_api_property_data_types_show", "parameters": [ { "name": "code", "in": "path", "description": "Property data type code", "required": true, "schema": { "type": "string", "pattern": "[A-Z_]+", "example": "FLOOR_COUNT" } } ], "responses": { "200": { "description": "Property data type details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "FLOOR_COUNT" }, "name_key": { "type": "string", "example": "property_data_type.floor_count.name" }, "data_type": { "type": "string", "example": "int" }, "group_code": { "type": "string", "example": "building" }, "icon_url": { "type": "string", "example": "https://s3.example.com/property_data_type/1.svg" }, "unit": { "type": "string", "example": null, "nullable": true }, "is_system": { "type": "boolean", "example": true } }, "type": "object" } } } }, "404": {} } } }, "/api/v1/property-data-types/meta/groups": { "get": { "tags": [ "05. References / Property Data Types" ], "summary": "Get available property data type groups", "description": "Returns list of available group codes with translation keys.", "operationId": "get_api_property_data_types_groups", "responses": { "200": { "description": "Property data type groups", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "building" }, "name_key": { "type": "string", "example": "property_data_type.group.building" } }, "type": "object" } } }, "type": "object" } } } } } } }, "/api/v1/property-data-types/meta/data-types": { "get": { "tags": [ "05. References / Property Data Types" ], "summary": "Get available data types", "description": "Returns list of available data types (string, bool, int, float).", "operationId": "get_api_property_data_types_data_types", "responses": { "200": { "description": "Available data types", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "string" }, "example": [ "string", "bool", "int", "float" ] } }, "type": "object" } } } } } } }, "/api/v1/property-data-types/property-data-types-by-type": { "get": { "tags": [ "05. References / Property Data Types" ], "summary": "Get property data types filtered by property type (for AJAX form reload).", "operationId": "get_api_property_data_types_by_type", "responses": { "default": { "description": "" } } } }, "/api/v1/properties/{propertyId}/data-values": { "get": { "tags": [ "03. Properties / Characteristics" ], "summary": "List property data values", "description": "Returns list of all data values set for the property.", "operationId": "get_api_property_data_values_list", "parameters": [ { "name": "propertyId", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "group", "in": "query", "description": "Filter by group code", "required": false, "schema": { "type": "string", "example": "apartment" } } ], "responses": { "200": { "description": "Property data values list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "ROOM_COUNT" }, "name_key": { "type": "string", "example": "property_data_type.room_count.name" }, "data_type": { "type": "string", "example": "int" }, "group_code": { "type": "string", "example": "apartment" }, "value": { "type": "string", "example": "3" }, "formatted_value": { "type": "string", "example": "3" }, "unit": { "type": "string", "example": null, "nullable": true }, "icon_url": { "type": "string", "nullable": true } }, "type": "object" } }, "total": { "type": "integer", "example": 15 } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Characteristics" ], "summary": "Set or update a property data value", "description": "Set or update a single data value for the property. Use data type code to identify the characteristic.", "operationId": "post_api_property_data_values_set", "parameters": [ { "name": "propertyId", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "value" ], "properties": { "code": { "type": "string", "example": "ROOM_COUNT" }, "value": { "type": "string", "example": "3" } }, "type": "object" } } } }, "responses": { "200": { "description": "Value set successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Value set successfully" }, "data": { "type": "object" } }, "type": "object" } } } }, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/data-values/grouped": { "get": { "tags": [ "03. Properties / Characteristics" ], "summary": "List property data values grouped by category", "description": "Returns all data values organized by group.", "operationId": "get_api_property_data_values_grouped", "parameters": [ { "name": "propertyId", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Grouped property data values", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object", "example": { "building": [ { "code": "FLOOR_COUNT", "value": "9", "formatted_value": "9" } ], "apartment": [ { "code": "ROOM_COUNT", "value": "3", "formatted_value": "3" } ] } }, "groups": { "type": "array", "items": { "type": "string" }, "example": [ "building", "apartment", "utilities" ] }, "total": { "type": "integer", "example": 15 } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/data-values/batch": { "put": { "tags": [ "03. Properties / Characteristics" ], "summary": "Batch update property data values", "description": "Update multiple data values at once. Empty values will remove the characteristic.", "operationId": "put_api_property_data_values_batch", "parameters": [ { "name": "propertyId", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "values" ], "properties": { "values": { "description": "Object with code => value pairs", "type": "object", "example": { "ROOM_COUNT": "3", "FLOOR_NUMBER": "5", "HAS_BALCONY": "1", "BUILDING_TYPE": "brick" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Values updated successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Values updated successfully" }, "updated": { "type": "integer", "example": 4 }, "removed": { "type": "integer", "example": 1 }, "errors": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/data-values/{code}": { "get": { "tags": [ "03. Properties / Characteristics" ], "summary": "Get a property data value", "description": "Get a single data value by data type code.", "operationId": "get_api_property_data_values_show", "parameters": [ { "name": "propertyId", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "code", "in": "path", "description": "Property data type code", "required": true, "schema": { "type": "string", "example": "ROOM_COUNT" } } ], "responses": { "200": { "description": "Property data value", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Characteristics" ], "summary": "Delete a property data value", "description": "Remove a data value from the property by data type code.", "operationId": "delete_api_property_data_values_delete", "parameters": [ { "name": "propertyId", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "code", "in": "path", "description": "Property data type code", "required": true, "schema": { "type": "string", "example": "ROOM_COUNT" } } ], "responses": { "200": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/expenses": { "get": { "tags": [ "03. Properties / Expenses" ], "summary": "List expenses for a property", "operationId": "get_api_property_expenses_list", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "active_only", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Expenses" ], "summary": "Create a new expense", "description": "Creates a new expense via ExpenseService (same path as web UI): validates the form, persists expense with linked counters and zone prices. Notes are HTML-sanitized. The API uses service_provider_id (ServiceProvider::id); internally it maps to ExpenseProvider.", "operationId": "post_api_property_expenses_create", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "expense_type_id", "calculation_period", "unit_price", "measurement_unit_id", "currency_id", "start_date", "service_provider_id" ], "properties": { "expense_type_id": { "type": "integer", "example": 1 }, "calculation_period": { "type": "string", "enum": [ "MANUAL", "MONTHLY", "QUARTERLY", "SEMI_ANNUAL", "ANNUAL" ] }, "unit_price": { "type": "string", "example": "2.5000" }, "measurement_unit_id": { "type": "integer", "example": 1 }, "fixed_consumption": { "type": "string", "example": "100.0000", "nullable": true }, "currency_id": { "type": "integer", "example": 1 }, "start_date": { "type": "string", "format": "date", "example": "2026-01-01" }, "end_date": { "type": "string", "format": "date", "nullable": true }, "service_provider_id": { "description": "Required. ServiceProvider ID that will be mapped to an ExpenseProvider for this property.", "type": "integer", "nullable": false }, "account_number": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "consumption_type": { "description": "\u0422\u0438\u043f \u0441\u043f\u043e\u0436\u0438\u0432\u0430\u043d\u043d\u044f. \u042f\u043a\u0449\u043e \u043d\u0435 \u0432\u043a\u0430\u0437\u0430\u043d\u043e \u2014 \u0432\u0438\u0437\u043d\u0430\u0447\u0430\u0454\u0442\u044c\u0441\u044f \u0430\u0432\u0442\u043e\u043c\u0430\u0442\u0438\u0447\u043d\u043e \u0437\u0430 \u043d\u0430\u044f\u0432\u043d\u0456\u0441\u0442\u044e counter_ids.", "type": "string", "nullable": true, "enum": [ "fixed", "flat_fee", "counters", "as_incurred" ] }, "counter_ids": { "description": "Array of counter IDs to link", "type": "array", "items": { "type": "integer" }, "nullable": true }, "zone_prices": { "description": "Zone prices for multi-zone counters", "type": "object", "example": "{\"DAY\": \"4.32\", \"NIGHT\": \"2.16\"}", "nullable": true }, "charge_day": { "type": "integer", "example": 15 }, "payment_days": { "type": "integer", "example": 3 }, "reminder_days": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "403": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/expenses/{id}": { "get": { "tags": [ "03. Properties / Expenses" ], "summary": "Get expense details", "operationId": "get_api_property_expenses_show", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "03. Properties / Expenses" ], "summary": "Update expense", "description": "Updates the expense via ExpenseService (same path as web UI): re-validates, re-fills fields, and processes zone prices. Notes are HTML-sanitized. counter_ids (if provided) fully replaces the existing counter links.", "operationId": "put_api_property_expenses_update", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "expense_type_id": { "type": "integer" }, "calculation_period": { "type": "string" }, "unit_price": { "type": "string" }, "measurement_unit_id": { "type": "integer" }, "fixed_consumption": { "type": "string", "nullable": true }, "currency_id": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date", "nullable": true }, "service_provider_id": { "description": "Required. ServiceProvider ID that will be mapped to an ExpenseProvider for this property.", "type": "integer", "nullable": false }, "account_number": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "notes": { "type": "string", "nullable": true }, "consumption_type": { "description": "\u0422\u0438\u043f \u0441\u043f\u043e\u0436\u0438\u0432\u0430\u043d\u043d\u044f. \u042f\u043a\u0449\u043e \u043d\u0435 \u0432\u043a\u0430\u0437\u0430\u043d\u043e \u2014 \u0432\u0438\u0437\u043d\u0430\u0447\u0430\u0454\u0442\u044c\u0441\u044f \u0430\u0432\u0442\u043e\u043c\u0430\u0442\u0438\u0447\u043d\u043e \u0437\u0430 \u043d\u0430\u044f\u0432\u043d\u0456\u0441\u0442\u044e counter_ids.", "type": "string", "nullable": true, "enum": [ "fixed", "flat_fee", "counters", "as_incurred" ] }, "counter_ids": { "description": "Array of counter IDs to link (replaces existing)", "type": "array", "items": { "type": "integer" }, "nullable": true }, "zone_prices": { "description": "Zone prices for multi-zone counters", "type": "object", "example": "{\"DAY\": \"4.32\", \"NIGHT\": \"2.16\"}", "nullable": true }, "charge_day": { "type": "integer" }, "payment_days": { "type": "integer" }, "reminder_days": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": {}, "400": {}, "403": {} }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Expenses" ], "summary": "Delete expense", "description": "Deletes the expense via ExpenseService with pre-checks (existing charges, linked adjustments). Non-admins cannot delete expenses with charges \u2014 deactivate them instead. Returns 400 with an error message when pre-checks fail.", "operationId": "delete_api_property_expenses_delete", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": {}, "400": {}, "403": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/expenses/{id}/toggle-active": { "post": { "tags": [ "03. Properties / Expenses" ], "summary": "Toggle expense active status", "description": "Activate or deactivate an expense. Deactivated expenses are not used for automatic charge generation.", "operationId": "post_api_property_expenses_toggle_active", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": {}, "403": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/expenses/{id}/refresh": { "post": { "tags": [ "03. Properties / Expenses" ], "summary": "Refresh charges for single expense", "description": "Generates charge for a single expense if period has ended", "operationId": "post_api_property_expenses_refresh", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Refresh result", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "charge_id": { "type": "integer", "nullable": true }, "message": { "type": "string" } }, "type": "object" } } } }, "400": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/expenses/{expenseId}/documents": { "get": { "tags": [ "03. Properties / Expense Config Documents" ], "summary": "List documents for an expense", "operationId": "get_api_expense_documents_list", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "expenseId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Expense Config Documents" ], "summary": "Upload a document to expense", "description": "Uploads a document via DocumentService, links it to the expense, and reassigns the Google Drive path to the expense-type folder. Comment is HTML-sanitized.", "operationId": "post_api_expense_documents_upload", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expenseId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file", "document_type_id" ], "properties": { "file": { "type": "string", "format": "binary" }, "document_type_id": { "type": "integer" }, "comment": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/expenses/{expenseId}/documents/{id}": { "get": { "tags": [ "03. Properties / Expense Config Documents" ], "summary": "Get expense document details", "operationId": "get_api_expense_documents_show", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expenseId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "03. Properties / Expense Config Documents" ], "summary": "Update expense document comment", "description": "Updates the comment on an expense document link. Comment is HTML-sanitized.", "operationId": "put_api_expense_documents_update", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expenseId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "comment": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Expense Config Documents" ], "summary": "Delete expense document", "description": "Removes the link between expense and document, then deletes the document via DocumentService with S3-first cascade.", "operationId": "delete_api_expense_documents_delete", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "expenseId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/messages/unread-count": { "get": { "tags": [ "08. Messages" ], "summary": "Get unread messages count", "description": "Returns total count of unread messages for current user across all properties.", "operationId": "get_api_messages_unread_count", "responses": { "200": { "description": "Unread count", "content": { "application/json": { "schema": { "properties": { "count": { "type": "integer", "example": 5 } }, "type": "object" } } } }, "401": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/messages/recent": { "get": { "tags": [ "08. Messages" ], "summary": "Get recent unread messages", "description": "Returns list of recent unread messages for dropdown menu.", "operationId": "get_api_messages_recent", "responses": { "200": { "description": "Recent messages list", "content": { "application/json": { "schema": { "properties": { "count": { "type": "integer", "example": 5 }, "messages": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "text": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "sender": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "property": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "401": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{id}/messages": { "get": { "tags": [ "08. Messages" ], "summary": "Get property messages", "description": "Returns paginated list of messages for a property. User must have access to the property.", "operationId": "get_api_property_messages_list", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number (default: 1)", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "Items per page (default: 50, max: 100)", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100 } } ], "responses": { "200": { "description": "Messages list", "content": { "application/json": { "schema": { "properties": { "total": { "type": "integer", "example": 42 }, "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 50 }, "pages": { "type": "integer", "example": 1 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/PropertyMessage" } } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "08. Messages" ], "summary": "Create message with files", "description": "Creates a new message with optional file attachments (uploaded or clipboard images) and optional reply reference. Message text is HTML-sanitized. On success sends a bilateral email + Telegram notification to the recipient and marks the message as email-sent. Notification failure is logged but does not block message creation.", "operationId": "post_api_property_messages_create", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "recipient_id", "message" ], "properties": { "recipient_id": { "description": "Recipient user ID", "type": "integer" }, "message": { "description": "Message text (max 1000 characters)", "type": "string", "maxLength": 1000 }, "reply_to_id": { "description": "ID of message being replied to (optional)", "type": "integer", "nullable": true }, "files[]": { "description": "File attachments (max 10 files, 10MB each)", "type": "array", "items": { "type": "string", "format": "binary" } }, "clipboard_images": { "description": "JSON array of base64 clipboard images", "type": "string", "nullable": true } }, "type": "object" } }, "application/json": { "schema": { "required": [ "recipient_id", "message" ], "properties": { "recipient_id": { "type": "integer" }, "message": { "type": "string", "maxLength": 1000 }, "reply_to_id": { "type": "integer", "nullable": true }, "clipboard_images": { "description": "Array of base64 image data", "type": "array", "items": { "properties": { "data": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Message created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyMessage" } } } }, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{id}/messages/{messageId}": { "get": { "tags": [ "08. Messages" ], "summary": "Get message details", "description": "Returns details of a specific message with all files.", "operationId": "get_api_property_messages_get", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "messageId", "in": "path", "description": "Message ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Message details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyMessage" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{id}/messages/{messageId}/read": { "post": { "tags": [ "08. Messages" ], "summary": "Mark message as read", "description": "Marks a message as read by the current user. Only the recipient can mark a message as read.", "operationId": "post_api_property_messages_read", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "messageId", "in": "path", "description": "Message ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Message marked as read", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "readAt": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{id}/messages/unread-count": { "get": { "tags": [ "08. Messages" ], "summary": "Get unread count for property", "description": "Returns count of unread messages for current user in specific property.", "operationId": "get_api_property_messages_unread_count", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Unread count", "content": { "application/json": { "schema": { "properties": { "count": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/property-types": { "get": { "tags": [ "05. References / Property Types" ], "summary": "List all property types", "description": "Returns list of all active property types with their codes, translations and images. No authentication required.", "operationId": "get_api_property_types_list", "responses": { "200": { "description": "List of property types", "content": { "application/json": { "schema": { "properties": { "property_types": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "HOUSE" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "additionalProperties": { "type": "string" } }, "image_url": { "type": "string", "example": "https://fsn1.your-objectstorage.com/llm/property_type/house.svg", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "sort_order": { "type": "integer", "example": 1 } }, "type": "object" } }, "total": { "type": "integer", "example": 4 } }, "type": "object" } } } } } } }, "/api/v1/property-types/{code}": { "get": { "tags": [ "05. References / Property Types" ], "summary": "Get property type by code", "description": "Returns property type details by code", "operationId": "get_api_property_types_show", "parameters": [ { "name": "code", "in": "path", "description": "Property type code (e.g., HOUSE, APARTMENT, GARAGE, LAND)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Property type details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "HOUSE" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "additionalProperties": { "type": "string" } }, "image_url": { "type": "string", "example": "https://fsn1.your-objectstorage.com/llm/property_type/house.svg", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "sort_order": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "404": { "description": "Property type not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Property type not found" } }, "type": "object" } } } } } } }, "/api/v1/properties/{propertyId}/proposals": { "get": { "tags": [ "03. Properties / Proposals" ], "summary": "List property commercial proposals", "description": "Returns list of commercial proposals sent for the property. Landlords and landlord agents only.", "operationId": "get_api_property_proposals_list", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "responded", "expired" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Proposals list", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "recipientEmail": { "type": "string" }, "recipientName": { "type": "string" }, "status": { "type": "string" }, "locale": { "type": "string" }, "currencyCode": { "type": "string", "nullable": true }, "coverMessage": { "type": "string", "nullable": true }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "viewedAt": { "type": "string", "format": "date-time", "nullable": true }, "viewsCount": { "type": "integer" }, "respondedAt": { "type": "string", "format": "date-time", "nullable": true }, "response": { "type": "string", "nullable": true }, "responsePhone": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "isExpired": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "type": "object" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "totalPages": { "type": "integer" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Proposals" ], "summary": "Create and send commercial proposal", "description": "Creates a commercial proposal via PropertyProposalService (persist/flush) and dispatches PropertyProposalSentEvent to send email to the recipient. If email sending fails, the proposal is still created and email_error is returned in the response body.", "operationId": "post_api_property_proposals_create", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "recipient_email", "recipient_name" ], "properties": { "recipient_email": { "type": "string", "format": "email", "example": "tenant@example.com" }, "recipient_name": { "type": "string", "example": "John Doe" }, "currency_id": { "type": "integer", "example": 1 }, "locale": { "type": "string", "example": "uk" }, "cover_message": { "type": "string", "example": "Please review this property..." }, "expires_in_days": { "type": "integer", "example": 14 } }, "type": "object" } } } }, "responses": { "201": { "description": "Proposal created and email sent", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Proposal created and email sent" }, "data": { "type": "object" }, "viewUrl": { "type": "string" } }, "type": "object" } } } }, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/proposals/{id}": { "get": { "tags": [ "03. Properties / Proposals" ], "summary": "Get proposal details", "description": "Returns detailed information about a commercial proposal.", "operationId": "get_api_property_proposals_show", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Proposal details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Proposals" ], "summary": "Delete proposal", "description": "Delete a commercial proposal.", "operationId": "delete_api_property_proposals_delete", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Proposal deleted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Proposal deleted" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/proposals/{id}/resend": { "post": { "tags": [ "03. Properties / Proposals" ], "summary": "Resend proposal email", "description": "Resends the proposal email via PropertyProposalService::resendProposal and updates sent_at. Returns 400 if the proposal is already responded or expired.", "operationId": "post_api_property_proposals_resend", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Email resent", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Email resent successfully" } }, "type": "object" } } } }, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/proposals/stats": { "get": { "tags": [ "03. Properties / Proposals" ], "summary": "Get proposal statistics", "description": "Returns statistics about commercial proposals for the property.", "operationId": "get_api_property_proposals_stats", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Proposal statistics", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "total": { "type": "integer", "example": 10 }, "pending": { "type": "integer", "example": 5 }, "responded": { "type": "integer", "example": 3 }, "expired": { "type": "integer", "example": 2 }, "totalViews": { "type": "integer", "example": 25 } }, "type": "object" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/receipts": { "get": { "tags": [ "Receipts" ], "summary": "List my receipts", "description": "Get all receipts for properties where current user has access", "operationId": "get_api_receipts_my", "parameters": [ { "name": "property_id", "in": "query", "description": "Filter by property ID", "required": false, "schema": { "type": "integer" } }, { "name": "date_from", "in": "query", "description": "Filter receipts from this date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Filter receipts until this date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "amount_from", "in": "query", "description": "Minimum receipt amount", "required": false, "schema": { "type": "number", "format": "float" } }, { "name": "amount_to", "in": "query", "description": "Maximum receipt amount", "required": false, "schema": { "type": "number", "format": "float" } }, { "name": "limit", "in": "query", "description": "Number of items per page (default: 20)", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "description": "Offset for pagination (default: 0)", "required": false, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of receipts", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer", "example": 42 } }, "type": "object" } } } } } } }, "/api/v1/properties/{id}/receipts": { "get": { "tags": [ "Receipts" ], "summary": "List property receipts", "description": "Get all receipts for a specific property", "operationId": "get_api_property_receipts_list", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of property receipts", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer", "example": 15 } }, "type": "object" } } } }, "404": {}, "403": {} } } }, "/api/v1/properties/{id}/receipts/{rid}": { "get": { "tags": [ "Receipts" ], "summary": "Get receipt details", "description": "Retrieve detailed information about a specific receipt", "operationId": "get_api_property_receipt_show", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "rid", "in": "path", "description": "Receipt ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Receipt details", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": {}, "403": {} } } }, "/api/v1/rental-charges": { "get": { "tags": [ "03. Properties / Rental Charges" ], "summary": "Get rental charges list", "operationId": "get_app_api_rentalcharge_index", "parameters": [ { "name": "property_id", "in": "query", "schema": { "type": "integer" } }, { "name": "from_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "min_amount", "in": "query", "schema": { "type": "number" } }, { "name": "max_amount", "in": "query", "schema": { "type": "number" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RentalCharge" } }, "total": { "type": "integer" } }, "type": "object" } } } } } } }, "/api/v1/rental-charges/{id}": { "get": { "tags": [ "03. Properties / Rental Charges" ], "summary": "Get rental charge details", "operationId": "get_app_api_rentalcharge_show", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "404": {} } }, "delete": { "tags": [ "03. Properties / Rental Charges" ], "summary": "Delete rental charge (admin only)", "operationId": "delete_app_api_rentalcharge_delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": {}, "404": {} } } }, "/api/v1/rental-charges/contract/{contractId}": { "get": { "tags": [ "03. Properties / Rental Charges" ], "summary": "Get rental charges for specific contract", "operationId": "get_app_api_rentalcharge_bycontract", "parameters": [ { "name": "contractId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "404": {} } } }, "/api/v1/rental-charges/contract/{contractId}/next": { "get": { "tags": [ "03. Properties / Rental Charges" ], "summary": "Get next rental charge info for contract", "operationId": "get_app_api_rentalcharge_nextchargeinfo", "parameters": [ { "name": "contractId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "404": {} } } }, "/api/v1/rental-charges/contract/{contractId}/generate": { "post": { "tags": [ "03. Properties / Rental Charges" ], "summary": "Manually generate rental charge for contract (admin only)", "operationId": "post_app_api_rentalcharge_generate", "parameters": [ { "name": "contractId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": {}, "400": {}, "404": {} } } }, "/api/v1/rental-types": { "get": { "tags": [ "05. References / Rental Types" ], "summary": "List all rental types", "description": "Returns list of all active rental types with their codes and translations. No authentication required.", "operationId": "get_api_rental_types_list", "responses": { "200": { "description": "List of rental types", "content": { "application/json": { "schema": { "properties": { "rental_types": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "LONG_TERM" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "additionalProperties": { "type": "string" } }, "image_url": { "type": "string", "example": "https://example.com/rental_type/1.svg", "nullable": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } }, "total": { "type": "integer", "example": 2 } }, "type": "object" } } } } } } }, "/api/v1/rental-types/{code}": { "get": { "tags": [ "05. References / Rental Types" ], "summary": "Get rental type by code", "description": "Returns rental type details by code", "operationId": "get_api_rental_types_show", "parameters": [ { "name": "code", "in": "path", "description": "Rental type code (e.g., LONG_TERM, SHORT_TERM)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rental type details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "LONG_TERM" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "additionalProperties": { "type": "string" } }, "image_url": { "type": "string", "example": "https://example.com/rental_type/1.svg", "nullable": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "404": { "description": "Rental type not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Rental type not found" } }, "type": "object" } } } } } } }, "/api/v1/properties/{propertyId}/repair-compensations": { "get": { "tags": [ "03. Properties / Repair Compensations" ], "summary": "List property repair compensations", "description": "Returns list of repair compensations for the property.", "operationId": "get_api_property_repair_compensations_list", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "tenant_id", "in": "query", "schema": { "type": "integer" } }, { "name": "confirmed", "in": "query", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Compensations list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "totalAmount": { "type": "string" }, "page": { "type": "integer" }, "totalPages": { "type": "integer" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Repair Compensations" ], "summary": "Create repair compensation", "description": "Creates a new repair compensation via RepairCompensationService (comment is HTML-sanitized).", "operationId": "post_api_property_repair_compensations_create", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "compensation_date", "amount", "currency_id" ], "properties": { "compensation_date": { "type": "string", "format": "date", "example": "2024-01-15" }, "amount": { "type": "string", "example": "5000.00" }, "currency_id": { "type": "integer", "example": 1 }, "tenant_id": { "type": "integer", "nullable": true }, "comment": { "type": "string", "nullable": true, "maxLength": 2000 } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/repair-compensations/{id}": { "get": { "tags": [ "03. Properties / Repair Compensations" ], "summary": "Get repair compensation details", "description": "Returns compensation details including attached documents.", "operationId": "get_api_property_repair_compensations_show", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Compensation details with documents", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "type": "integer" }, "property_id": { "type": "integer" }, "compensation_date": { "type": "string", "format": "date" }, "amount": { "type": "string" }, "amount_formatted": { "type": "string" }, "currency": { "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "symbol": { "type": "string" } }, "type": "object", "nullable": true }, "tenant": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "owner_confirmed": { "type": "boolean" }, "comment": { "type": "string", "nullable": true }, "documents": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "original_name": { "type": "string" }, "file_size": { "type": "integer" }, "file_url": { "type": "string" } }, "type": "object" } }, "documents_count": { "type": "integer" }, "created_by": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "03. Properties / Repair Compensations" ], "summary": "Update repair compensation", "description": "Updates the compensation via RepairCompensationService (comment is HTML-sanitized). All body fields are optional (partial update).", "operationId": "put_api_property_repair_compensations_update", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "compensation_date": { "type": "string", "format": "date" }, "amount": { "type": "string" }, "currency_id": { "type": "integer" }, "tenant_id": { "type": "integer", "nullable": true }, "comment": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": {}, "400": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Repair Compensations" ], "summary": "Delete repair compensation", "description": "Deletes the compensation with S3-first cascade removal of attached documents. Returns 500 if S3 deletion fails.", "operationId": "delete_api_property_repair_compensations_delete", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "403": {}, "404": {}, "500": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/repair-compensations/{id}/confirm": { "post": { "tags": [ "03. Properties / Repair Compensations" ], "summary": "Confirm repair compensation", "description": "Confirm the compensation by owner.", "operationId": "post_api_property_repair_compensations_confirm", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/repair-compensations/{id}/unconfirm": { "post": { "tags": [ "03. Properties / Repair Compensations" ], "summary": "Remove compensation confirmation", "description": "Remove the confirmation from the compensation.", "operationId": "post_api_property_repair_compensations_unconfirm", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/repair-compensations/{id}/documents": { "post": { "tags": [ "03. Properties / Repair Compensations" ], "summary": "Attach document to compensation", "description": "Upload and attach a document to the repair compensation.", "operationId": "post_api_property_repair_compensations_attach_document", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "document" ], "properties": { "document": { "type": "string", "format": "binary" }, "comment": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/repair-compensations/{id}/documents/{documentId}": { "delete": { "tags": [ "03. Properties / Repair Compensations" ], "summary": "Detach document from compensation", "operationId": "delete_api_property_repair_compensations_detach_document", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{id}/adjustments": { "get": { "tags": [ "03. Properties / Balance Adjustments" ], "summary": "List service provider balance adjustments for a property", "operationId": "get_app_api_serviceprovideradjustment_list", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "Items per page", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of adjustments", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "adjustment_date": { "type": "string", "format": "date" }, "amount": { "type": "number", "format": "float" }, "currency": { "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "symbol": { "type": "string" } }, "type": "object" }, "service_provider": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "notes": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "confirmed_by_landlord", "confirmed_by_tenant", "fully_confirmed" ] }, "is_confirmed_by_landlord": { "type": "boolean" }, "is_confirmed_by_tenant": { "type": "boolean" }, "documents_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "type": "object" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } }, "type": "object" } } } }, "403": {}, "404": {} } }, "post": { "tags": [ "03. Properties / Balance Adjustments" ], "summary": "Create a new service provider balance adjustment", "description": "Creates an adjustment via service layer (notes are HTML-sanitized) and sends bilateral notification to the opposite party.", "operationId": "post_app_api_serviceprovideradjustment_create", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "adjustment_date", "service_provider_id", "amount", "currency_id" ], "properties": { "adjustment_date": { "type": "string", "format": "date", "example": "2026-01-28" }, "service_provider_id": { "type": "integer", "example": 1 }, "amount": { "type": "number", "format": "float", "example": -150.5 }, "currency_id": { "type": "integer", "example": 1 }, "notes": { "type": "string", "example": "Correction for overbilling", "nullable": true }, "property_expense_id": { "type": "integer", "example": 15, "nullable": true }, "contract_id": { "type": "integer", "example": 5, "nullable": true } }, "type": "object" } } } }, "responses": { "500": {}, "201": { "description": "Adjustment created", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer" }, "message": { "type": "string" } }, "type": "object" } } } }, "400": {}, "403": {}, "404": {} } } }, "/api/v1/properties/{id}/adjustments/{aid}": { "get": { "tags": [ "03. Properties / Balance Adjustments" ], "summary": "Get adjustment details", "operationId": "get_app_api_serviceprovideradjustment_show", "parameters": [ { "name": "id", "in": "path", "description": "Property ID", "required": true, "schema": { "type": "integer" } }, { "name": "aid", "in": "path", "description": "Adjustment ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Adjustment details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer" }, "adjustment_date": { "type": "string", "format": "date" }, "amount": { "type": "number", "format": "float" }, "currency": { "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "symbol": { "type": "string" } }, "type": "object" }, "service_provider": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "notes": { "type": "string", "nullable": true }, "status": { "type": "string" }, "is_confirmed_by_landlord": { "type": "boolean" }, "landlord_confirmed_by": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "landlord_confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "is_confirmed_by_tenant": { "type": "boolean" }, "tenant_confirmed_by": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "tenant_confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "property_expense": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "contract": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "documents": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "original_name": { "type": "string" }, "file_size": { "type": "integer" }, "comment": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "403": {}, "404": {} } }, "put": { "tags": [ "03. Properties / Balance Adjustments" ], "summary": "Update an adjustment", "description": "Updates an adjustment via service layer (notes are HTML-sanitized) and sends bilateral update notification to the opposite party. All body fields are optional (partial update). Note: service_provider_id in body is currently a no-op (legacy) \u2014 expenseProvider is managed via separate flow.", "operationId": "put_app_api_serviceprovideradjustment_update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "aid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "adjustment_date": { "type": "string", "format": "date", "example": "2026-01-28" }, "service_provider_id": { "type": "integer", "example": 1 }, "amount": { "type": "number", "format": "float", "example": -150.5 }, "currency_id": { "type": "integer", "example": 1 }, "notes": { "type": "string", "example": "Updated notes", "nullable": true }, "property_expense_id": { "type": "integer", "example": 15, "nullable": true }, "contract_id": { "type": "integer", "example": 5, "nullable": true } }, "type": "object" } } } }, "responses": { "200": {}, "400": {}, "403": {}, "404": {}, "500": {} } }, "delete": { "tags": [ "03. Properties / Balance Adjustments" ], "summary": "Delete an adjustment", "description": "Deletes the adjustment with S3-first cascade removal of attached documents. Returns 500 if S3 deletion fails (DB row is then kept intact).", "operationId": "delete_app_api_serviceprovideradjustment_delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "aid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": {}, "403": {}, "404": {}, "500": {} } } }, "/api/v1/properties/{id}/adjustments/{aid}/documents": { "post": { "tags": [ "03. Properties / Balance Adjustments" ], "summary": "Attach a document to adjustment", "description": "Attaches an existing property document to the adjustment. Comment is HTML-sanitized. Returns 400 if the document is already attached.", "operationId": "post_app_api_serviceprovideradjustment_attachdocument", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "aid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "document_id" ], "properties": { "document_id": { "type": "integer", "example": 42 }, "comment": { "type": "string", "example": "Invoice copy", "nullable": true } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "403": {}, "404": {} } } }, "/api/v1/properties/{id}/adjustments/{aid}/documents/{did}": { "delete": { "tags": [ "03. Properties / Balance Adjustments" ], "summary": "Detach a document from adjustment", "description": "Removes the link between the adjustment and the document. The document itself is not deleted.", "operationId": "delete_app_api_serviceprovideradjustment_detachdocument", "parameters": [ { "name": "did", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "aid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": {}, "403": {}, "404": {} } } }, "/api/v1/properties/{id}/adjustments/{aid}/confirm-landlord": { "post": { "tags": [ "03. Properties / Balance Adjustments" ], "summary": "Confirm adjustment by landlord", "description": "Marks the adjustment as confirmed by the landlord and sends a notification to the tenant. Returns 400 if already confirmed.", "operationId": "post_app_api_serviceprovideradjustment_confirmbylandlord", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "aid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": {}, "400": {}, "403": {}, "404": {} } } }, "/api/v1/properties/{id}/adjustments/{aid}/confirm-tenant": { "post": { "tags": [ "03. Properties / Balance Adjustments" ], "summary": "Confirm adjustment by tenant", "description": "Marks the adjustment as confirmed by the tenant and sends a notification to the landlord. Returns 400 if already confirmed.", "operationId": "post_app_api_serviceprovideradjustment_confirmbytenant", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "aid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": {}, "400": {}, "403": {}, "404": {} } } }, "/api/v1/service-providers": { "get": { "tags": [ "06. Service Providers" ], "summary": "List all service providers", "description": "Returns paginated list of active service providers from official Ukrainian legal entities database.\n\n**Read-only access** - no authentication required, no modifications possible.\n\n**Use cases:**\n- Search for utility companies (electricity, gas, water) by name or EDRPOU\n- Find service providers in specific region\n- Get contact information for management companies\n- Browse official database of legal entities\n\n**Examples:**\n- `GET /api/service-providers` - Get first 50 active providers\n- `GET /api/service-providers?page=2&limit=20` - Get page 2 with 20 items\n- `GET /api/service-providers?search=\u041a\u0438\u0457\u0432\u0435\u043d\u0435\u0440\u0433\u043e` - Search by name\n- `GET /api/service-providers?search=00131305` - Search by EDRPOU code\n- `GET /api/service-providers?region=\u041a\u0438\u0457\u0432` - Filter by region", "operationId": "get_api_service_providers_list", "parameters": [ { "name": "page", "in": "query", "description": "Page number (starts from 1). Use for pagination when result set is large.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of items per page. Maximum 100 items. Default is 50. Use smaller values for faster response.", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 }, "example": 50 }, { "name": "search", "in": "query", "description": "Search query. Searches in: company name, short name, EDRPOU code (8 digits). Case-insensitive partial match.", "required": false, "schema": { "type": "string" }, "examples": { "search_by_name": { "summary": "Search by company name", "value": "\u041a\u0438\u0457\u0432\u0435\u043d\u0435\u0440\u0433\u043e" }, "search_by_edrpou": { "summary": "Search by EDRPOU code", "value": "00131305" } } }, { "name": "region", "in": "query", "description": "Filter by region (oblast). Exact match. Common values: \u041a\u0438\u0457\u0432, \u041b\u044c\u0432\u0456\u0432, \u0425\u0430\u0440\u043a\u0456\u0432, \u041e\u0434\u0435\u0441\u0430, etc.", "required": false, "schema": { "type": "string" }, "example": "\u041a\u0438\u0457\u0432" }, { "name": "country", "in": "query", "description": "Filter by country ID. Use to get providers from specific country only.", "required": false, "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "Successfully retrieved list of service providers", "content": { "application/json": { "schema": { "properties": { "items": { "description": "Array of service provider objects", "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "edrpou": { "type": "string", "example": "00131305" }, "name": { "type": "string", "example": "\u041f\u0423\u0411\u041b\u0406\u0427\u041d\u0415 \u0410\u041a\u0426\u0406\u041e\u041d\u0415\u0420\u041d\u0415 \u0422\u041e\u0412\u0410\u0420\u0418\u0421\u0422\u0412\u041e \"\u041a\u0418\u0407\u0412\u0415\u041d\u0415\u0420\u0413\u041e\"" }, "address": { "type": "string", "example": "\u043c. \u041a\u0438\u0457\u0432, \u0432\u0443\u043b. \u0421\u0430\u0445\u0430\u0440\u043e\u0432\u0430, 139", "nullable": true }, "region": { "type": "string", "example": "\u041a\u0438\u0457\u0432", "nullable": true }, "website": { "type": "string", "example": "https://kyivenergo.ua", "nullable": true }, "description": { "type": "string", "example": "Electricity distribution company serving Kyiv", "nullable": true }, "phone": { "type": "string", "example": "+380 44 467 0067", "nullable": true }, "email": { "type": "string", "example": "info@kyivenergo.ua", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "country": { "description": "Country information", "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "UA" }, "name": { "type": "object", "example": { "uk": "\u0423\u043a\u0440\u0430\u0457\u043d\u0430", "en": "Ukraine", "ru": "\u0423\u043a\u0440\u0430\u0438\u043d\u0430" } } }, "type": "object" } }, "type": "object" } }, "total": { "type": "integer", "example": 1234 }, "pages": { "type": "integer", "example": 25 } }, "type": "object" }, "example": { "items": [ { "id": 1, "edrpou": "00131305", "name": "\u041f\u0423\u0411\u041b\u0406\u0427\u041d\u0415 \u0410\u041a\u0426\u0406\u041e\u041d\u0415\u0420\u041d\u0415 \u0422\u041e\u0412\u0410\u0420\u0418\u0421\u0422\u0412\u041e \"\u041a\u0418\u0407\u0412\u0415\u041d\u0415\u0420\u0413\u041e\"", "address": "\u043c. \u041a\u0438\u0457\u0432, \u0432\u0443\u043b. \u0421\u0430\u0445\u0430\u0440\u043e\u0432\u0430, 139", "region": "\u041a\u0438\u0457\u0432", "website": "https://kyivenergo.ua", "description": "Electricity distribution company serving Kyiv", "phone": "+380 44 467 0067", "email": "info@kyivenergo.ua", "is_active": true, "country": { "id": 1, "code": "UA", "name": { "uk": "\u0423\u043a\u0440\u0430\u0457\u043d\u0430", "en": "Ukraine", "ru": "\u0423\u043a\u0440\u0430\u0438\u043d\u0430", "pl": "Ukraina", "de": "Ukraine" } } } ], "total": 1234, "pages": 25 } } } } } } }, "/api/v1/service-providers/{id}": { "get": { "tags": [ "06. Service Providers" ], "summary": "Get service provider by ID", "description": "Returns detailed information about a specific service provider by its ID.\n\n**Read-only access** - no authentication required.\n\n**Use cases:**\n- Get full details about a specific company after selecting from list\n- Display company information on property expense page\n- Show contact details for utility provider\n\n**Example:**\n`GET /api/service-providers/1` - Get details for provider with ID 1", "operationId": "get_api_service_providers_show", "parameters": [ { "name": "id", "in": "path", "description": "Unique identifier of the service provider. You get this ID from the list endpoint.", "required": true, "schema": { "type": "integer", "pattern": "\\d+", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "Successfully retrieved service provider details", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "edrpou": { "type": "string", "example": "00131305" }, "name": { "type": "string", "example": "\u041f\u0423\u0411\u041b\u0406\u0427\u041d\u0415 \u0410\u041a\u0426\u0406\u041e\u041d\u0415\u0420\u041d\u0415 \u0422\u041e\u0412\u0410\u0420\u0418\u0421\u0422\u0412\u041e \"\u041a\u0418\u0407\u0412\u0415\u041d\u0415\u0420\u0413\u041e\"" }, "website": { "type": "string", "example": "https://kyivenergo.ua", "nullable": true }, "description": { "type": "string", "example": "Electricity distribution company serving Kyiv", "nullable": true }, "phone": { "type": "string", "example": "+380 44 467 0067", "nullable": true }, "country": { "description": "Country information", "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "UA" }, "name": { "type": "object", "example": { "uk": "\u0423\u043a\u0440\u0430\u0457\u043d\u0430", "en": "Ukraine" } } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00+02:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-06-20T14:45:00+02:00" } }, "type": "object" }, "example": { "id": 1, "edrpou": "00131305", "name": "\u041f\u0423\u0411\u041b\u0406\u0427\u041d\u0415 \u0410\u041a\u0426\u0406\u041e\u041d\u0415\u0420\u041d\u0415 \u0422\u041e\u0412\u0410\u0420\u0418\u0421\u0422\u0412\u041e \"\u041a\u0418\u0407\u0412\u0415\u041d\u0415\u0420\u0413\u041e\"", "website": "https://kyivenergo.ua", "description": "Electricity distribution company serving Kyiv", "phone": "+380 44 467 0067", "country": { "id": 1, "code": "UA", "name": { "uk": "\u0423\u043a\u0440\u0430\u0457\u043d\u0430", "en": "Ukraine", "ru": "\u0423\u043a\u0440\u0430\u0438\u043d\u0430", "pl": "Ukraina", "de": "Ukraine" } }, "created_at": "2024-01-15T10:30:00+02:00", "updated_at": "2024-06-20T14:45:00+02:00" } } } }, "404": { "description": "Service provider not found or inactive", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Service provider not found" } }, "type": "object" }, "example": { "error": "Service provider not found" } } } } } } }, "/api/v1/service-providers/autocomplete": { "get": { "tags": [ "06. Service Providers" ], "summary": "Autocomplete search for service providers", "description": "Fast autocomplete search for forms. Searches from the beginning of name or EDRPOU code.\nReturns maximum 10 results for quick response.\n\n**Search logic:**\n- If query contains only digits: searches in EDRPOU from the beginning\n- Otherwise: searches in name from the beginning (case-insensitive)\n\n**Examples:**\n- `GET /api/service-providers/autocomplete?q=\u041a\u0438\u0457\u0432` - Search \"\u041a\u0438\u0457\u0432\" in names\n- `GET /api/service-providers/autocomplete?q=0013` - Search \"0013\" in EDRPOU codes\n- Search \"\u0440\u043e\u0441\" will find \"\u0420\u043e\u0441\u043a\u043e\u043c\u0443\u043d\u0441\u0435\u0440\u0432\u0456\u0441\" but NOT \"\u0414\u043d\u0456\u043f\u0440\u043e\u0441\u043f\u0435\u0446\u043e\u0431\u0441\u043b\u0443\u0433\u043e\u0432\u0443\u0432\u0430\u043d\u043d\u044f\"", "operationId": "get_api_service_providers_autocomplete", "parameters": [ { "name": "q", "in": "query", "description": "Search query. Minimum 2 characters. Searches from the beginning of name or EDRPOU.", "required": true, "schema": { "type": "string", "minLength": 2 }, "examples": { "search_name": { "summary": "Search by name", "value": "\u041a\u0438\u0457\u0432" }, "search_edrpou": { "summary": "Search by EDRPOU", "value": "0013" } } } ], "responses": { "200": { "description": "Array of matching providers (max 10 items)", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 123 }, "name": { "type": "string", "example": "\u041a\u0438\u0457\u0432\u0435\u043d\u0435\u0440\u0433\u043e" }, "edrpou": { "type": "string", "example": "00131305" } }, "type": "object" } } } } }, "400": {} } } }, "/api/v1/tariff-zones": { "get": { "tags": [ "05. References / Tariff Zones" ], "summary": "List tariff zones", "description": "Returns list of tariff zones filtered by country and expense type. Used for multi-zone electricity metering.", "operationId": "get_api_tariff_zones_list", "parameters": [ { "name": "country", "in": "query", "description": "Country code (ISO 3166-1 alpha-2)", "required": true, "schema": { "type": "string", "example": "UA" } }, { "name": "expense_type_id", "in": "query", "description": "Expense type ID", "required": true, "schema": { "type": "integer", "example": 3 } } ], "responses": { "200": { "description": "List of tariff zones", "content": { "application/json": { "schema": { "properties": { "tariff_zones": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "country_code": { "type": "string", "example": "UA" }, "expense_type_id": { "type": "integer", "example": 3 }, "tariff_type": { "type": "string", "example": "TWO_ZONE" }, "zone_code": { "type": "string", "example": "DAY" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "additionalProperties": { "type": "string" } }, "coefficient": { "type": "integer", "example": 100 }, "time_ranges": { "type": "array", "items": { "properties": { "from": { "type": "string", "example": "07:00" }, "to": { "type": "string", "example": "23:00" } }, "type": "object" }, "nullable": true }, "meter_index": { "type": "string", "example": "T1", "nullable": true }, "sort_order": { "type": "integer", "example": 0 } }, "type": "object" } }, "total": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "400": { "description": "Missing required parameters", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Missing required parameter: country" } }, "type": "object" } } } } } } }, "/api/v1/tariff-zones/tariff-types": { "get": { "tags": [ "05. References / Tariff Zones" ], "summary": "Get available tariff types", "description": "Returns list of available tariff types (SINGLE_ZONE, TWO_ZONE, THREE_ZONE) for a country and expense type.", "operationId": "get_api_tariff_zones_types", "parameters": [ { "name": "country", "in": "query", "description": "Country code (ISO 3166-1 alpha-2)", "required": true, "schema": { "type": "string", "example": "UA" } }, { "name": "expense_type_id", "in": "query", "description": "Expense type ID", "required": true, "schema": { "type": "integer", "example": 3 } } ], "responses": { "200": { "description": "List of tariff types", "content": { "application/json": { "schema": { "properties": { "tariff_types": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "TWO_ZONE" }, "name": { "type": "object", "additionalProperties": { "type": "string" } } }, "type": "object" } }, "has_tariff_zones": { "type": "boolean", "example": true } }, "type": "object" } } } } } } }, "/api/v1/tariff-zones/by-tariff-type": { "get": { "tags": [ "05. References / Tariff Zones" ], "summary": "Get zones by tariff type", "description": "Returns tariff zones for a specific tariff type (e.g., all zones for TWO_ZONE tariff).", "operationId": "get_api_tariff_zones_by_type", "parameters": [ { "name": "country", "in": "query", "description": "Country code (ISO 3166-1 alpha-2)", "required": true, "schema": { "type": "string", "example": "UA" } }, { "name": "expense_type_id", "in": "query", "description": "Expense type ID", "required": true, "schema": { "type": "integer", "example": 3 } }, { "name": "tariff_type", "in": "query", "description": "Tariff type code", "required": true, "schema": { "type": "string", "example": "TWO_ZONE", "enum": [ "SINGLE_ZONE", "TWO_ZONE", "THREE_ZONE" ] } } ], "responses": { "200": { "description": "List of zones for the tariff type", "content": { "application/json": { "schema": { "properties": { "tariff_type": { "type": "string", "example": "TWO_ZONE" }, "tariff_type_name": { "type": "object", "additionalProperties": { "type": "string" } }, "zones": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 2 }, "zone_code": { "type": "string", "example": "DAY" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "additionalProperties": { "type": "string" } }, "coefficient": { "type": "integer", "example": 100 }, "time_ranges": { "type": "array", "items": { "type": "object" }, "nullable": true }, "meter_index": { "type": "string", "example": "T1", "nullable": true } }, "type": "object" } } }, "type": "object" } } } } } } }, "/api/v1/tariff-zones/has-zones": { "get": { "tags": [ "05. References / Tariff Zones" ], "summary": "Check if tariff zones exist", "description": "Returns whether tariff zones are configured for a country and expense type.", "operationId": "get_api_tariff_zones_check", "parameters": [ { "name": "country", "in": "query", "description": "Country code (ISO 3166-1 alpha-2)", "required": true, "schema": { "type": "string", "example": "UA" } }, { "name": "expense_type_id", "in": "query", "description": "Expense type ID", "required": true, "schema": { "type": "integer", "example": 3 } } ], "responses": { "200": { "description": "Tariff zones availability", "content": { "application/json": { "schema": { "properties": { "has_tariff_zones": { "type": "boolean", "example": true } }, "type": "object" } } } } } } }, "/api/v1/tasks": { "get": { "tags": [ "13. CRM Tasks" ], "summary": "List tasks", "description": "Returns paginated list of tasks. By default returns only tasks owned by the current user (scope=mine). Use scope=all to get all tasks in the system. Combine with owner_id to filter by a specific owner when scope=all.", "operationId": "get_api_tasks_list", "parameters": [ { "name": "scope", "in": "query", "description": "mine (default) \u2014 only current user tasks; all \u2014 all tasks in the system", "required": false, "schema": { "type": "string", "default": "mine", "enum": [ "mine", "all" ] } }, { "name": "owner_id", "in": "query", "description": "Filter by owner user ID. Only applied when scope=all.", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter by status (comma-separated). Omit for open tasks only.", "required": false, "schema": { "type": "string", "example": "new,in_progress", "enum": [ "new", "planned", "in_progress", "blocked", "review", "done", "cancelled" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "status[]", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CrmTaskStatus" }, "nullable": true, "default": null } } ], "responses": { "200": { "description": "Paginated list of tasks" }, "400": { "description": "Invalid query parameter" } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "13. CRM Tasks" ], "summary": "Create a task or subtask", "description": "Creates a new root task or subtask. If parent_task_id is provided, the caller must have COMMENT permission on the parent task. If owner_id is not specified, the task is assigned to the creator (current user).", "operationId": "post_api_tasks_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title" ], "properties": { "title": { "type": "string", "example": "Fix critical bug", "maxLength": 255 }, "description": { "type": "string", "example": "Detailed description", "nullable": true }, "priority": { "type": "string", "default": "normal", "enum": [ "low", "normal", "high", "critical" ] }, "owner_id": { "type": "integer", "example": 7, "nullable": true }, "parent_task_id": { "type": "integer", "example": 42, "nullable": true }, "due_at": { "type": "string", "example": "2026-07-01T00:00:00+00:00", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Task created" }, "400": { "description": "Validation error or invalid due_at format" }, "403": { "description": "Access denied to parent task" }, "404": { "description": "Parent task or owner not found" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/tasks/owners": { "get": { "tags": [ "13. CRM Tasks" ], "summary": "List users who own tasks", "description": "Returns users who have tasks, with task count. Sorted by task_count DESC, then by name ASC.\nUse `with_tasks=true` to include the task list per owner (same status filter applied).\nPagination fields (`total`/`page`/`totalPages`) are returned for envelope consistency but are static \u2014 endpoint has no pagination.\n\nDefault: only non-closed statuses (`new`, `planned`, `in_progress`, `blocked`, `review`).\n\nExamples:\n- `GET /api/v1/tasks/owners` \u2014 users with open tasks\n- `GET /api/v1/tasks/owners?status=blocked` \u2014 users who have blocked tasks\n- `GET /api/v1/tasks/owners?status=blocked&with_tasks=true` \u2014 users with blocked tasks + task list", "operationId": "get_api_tasks_owners", "parameters": [ { "name": "status", "in": "query", "description": "Filter by status (comma-separated). Omit for open tasks only.", "required": false, "schema": { "type": "string", "example": "blocked,in_progress", "enum": [ "new", "planned", "in_progress", "blocked", "review", "done", "cancelled" ] } }, { "name": "with_tasks", "in": "query", "description": "Include tasks subarray per owner", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "status[]", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CrmTaskStatus" }, "nullable": true, "default": null } } ], "responses": { "200": { "description": "List of users with task counts" }, "400": { "description": "Invalid query parameter" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/tasks/{id}": { "get": { "tags": [ "13. CRM Tasks" ], "summary": "Get task with full context", "description": "Returns task details including all ancestors (up to root), all descendants (recursive), and comments for every node in the tree.", "operationId": "get_api_tasks_show", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "200": { "description": "Task with full context tree" }, "403": { "description": "Access denied" }, "404": { "description": "Task not found" } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "13. CRM Tasks" ], "summary": "Delete a task (cascade)", "description": "Deletes the task and all its descendants. S3 files are removed first, then Drive sync rows, then SQL records in a transaction. Requires ROLE_SUPER_USER.", "operationId": "delete_api_tasks_delete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "responses": { "204": { "description": "Task deleted" }, "403": { "description": "Access denied" }, "404": { "description": "Task not found" }, "500": { "description": "Deletion failed" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/tasks/{id}/comments": { "post": { "tags": [ "13. CRM Tasks" ], "summary": "Add a comment to a task", "description": "Creates a new comment on the task via CrmTaskService. Body is HTML-sanitized. Activity log is updated and email + Telegram notifications are dispatched to every non-initiator participant. If the task was closed, a new comment reopens the chain. Requires COMMENT permission (owner, creator, or participant).", "operationId": "post_api_tasks_add_comment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "type": "string", "example": "\u041f\u0440\u043e\u0432\u0435\u0440\u0438\u043b \u2014 \u0432\u0441\u0451 \u0440\u0430\u0431\u043e\u0442\u0430\u0435\u0442 \u043a\u043e\u0440\u0440\u0435\u043a\u0442\u043d\u043e." } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment created" }, "400": { "description": "Missing or empty body" }, "403": { "description": "Access denied" }, "404": { "description": "Task not found" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/tasks/{id}/status": { "patch": { "tags": [ "13. CRM Tasks" ], "summary": "Change task status", "description": "Changes the status of a task via CrmTaskService. Validates the transition (invalid transitions return 400), appends a system comment about the change, and dispatches notifications to every non-initiator participant. Requires EDIT permission (owner or participant with EDITOR role).", "operationId": "patch_api_tasks_change_status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "pattern": "\\d+" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "status" ], "properties": { "status": { "type": "string", "example": "in_progress", "enum": [ "new", "planned", "in_progress", "blocked", "review", "done", "cancelled" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Status changed, returns updated task" }, "400": { "description": "Invalid or missing status" }, "403": { "description": "Access denied" }, "404": { "description": "Task not found" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/tenant-assets": { "get": { "tags": [ "03. Properties / Tenant Assets" ], "summary": "List tenant assets", "description": "Returns list of tenant assets for the property.", "operationId": "get_api_property_tenant_assets_list", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Assets list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "totalPages": { "type": "integer" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Tenant Assets" ], "summary": "Create tenant asset", "description": "Creates a tenant asset via TenantAssetService (name/description are HTML-sanitized). Returns 400 if validation fails.", "operationId": "post_api_property_tenant_assets_create", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "asset_date" ], "properties": { "name": { "type": "string", "maxLength": 300 }, "description": { "type": "string", "nullable": true, "maxLength": 1000 }, "asset_date": { "type": "string", "format": "date", "example": "2024-01-15" }, "estimated_value": { "type": "number", "format": "float", "nullable": true }, "currency_id": { "type": "integer", "nullable": true } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/tenant-assets/{id}": { "get": { "tags": [ "03. Properties / Tenant Assets" ], "summary": "Get tenant asset details", "description": "Returns asset details including documents and translations.", "operationId": "get_api_property_tenant_assets_show", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "03. Properties / Tenant Assets" ], "summary": "Update tenant asset", "description": "Updates the asset via TenantAssetService (name/description are HTML-sanitized). All body fields are optional (partial update).", "operationId": "put_api_property_tenant_assets_update", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 300 }, "description": { "type": "string", "maxLength": 1000 }, "asset_date": { "type": "string", "format": "date" }, "estimated_value": { "type": "number", "format": "float" }, "currency_id": { "type": "integer" } }, "type": "object" } } } }, "responses": { "200": {}, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Tenant Assets" ], "summary": "Delete tenant asset", "description": "Deletes the tenant asset with S3-first cascade removal of attached documents. Returns 500 if S3 deletion fails.", "operationId": "delete_api_property_tenant_assets_delete", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/tenant-assets/{id}/documents": { "post": { "tags": [ "03. Properties / Tenant Assets" ], "summary": "Attach document to asset", "description": "Uploads a file via DocumentService, attaches it to the asset via TenantAssetService::attachDocument, then reassigns drive sync to the asset-specific path.", "operationId": "post_api_property_tenant_assets_attach_document", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "properties": { "file": { "type": "string", "format": "binary" }, "comment": { "type": "string", "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/tenant-assets/{id}/documents/{documentId}": { "delete": { "tags": [ "03. Properties / Tenant Assets" ], "summary": "Detach document from asset", "description": "Remove a document from the asset.", "operationId": "delete_api_property_tenant_assets_detach_document", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/tenant-assets/{id}/translations": { "get": { "tags": [ "03. Properties / Tenant Assets" ], "summary": "Get asset translations", "description": "Returns all translations for the asset.", "operationId": "get_api_property_tenant_assets_translations_list", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Tenant Assets" ], "summary": "Save asset translation", "description": "Creates or updates a translation for the asset via TenantAssetService::saveTranslation (name is HTML-sanitized).", "operationId": "post_api_property_tenant_assets_translations_save", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "locale", "name" ], "properties": { "locale": { "type": "string", "example": "en" }, "name": { "type": "string", "maxLength": 300 } }, "type": "object" } } } }, "responses": { "200": {}, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/tenant-assets/{id}/translations/{translationId}": { "delete": { "tags": [ "03. Properties / Tenant Assets" ], "summary": "Delete asset translation", "description": "Delete a translation for the asset.", "operationId": "delete_api_property_tenant_assets_translations_delete", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "translationId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/tickets": { "get": { "tags": [ "12. Support Tickets" ], "summary": "List user tickets", "description": "Returns paginated list of tickets created by the current user. Admins see all tickets.", "operationId": "get_api_tickets_list", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "in_progress", "waiting_user", "waiting_admin", "resolved", "closed" ] } } ], "responses": { "200": { "description": "Paginated list of tickets", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "category": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "totalPages": { "type": "integer" } }, "type": "object" } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "12. Support Tickets" ], "summary": "Create a new ticket", "operationId": "post_api_tickets_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "description" ], "properties": { "title": { "type": "string", "example": "Water leak in bathroom" }, "description": { "type": "string", "example": "There is a water leak under the sink in the main bathroom." }, "priority": { "type": "string", "example": "normal", "enum": [ "low", "normal", "high", "critical" ] }, "category": { "type": "string", "example": "maintenance", "enum": [ "bug", "maintenance", "billing", "feature_request", "other" ] }, "property_id": { "type": "integer", "example": 1, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Ticket created" }, "400": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/tickets/{id}": { "get": { "tags": [ "12. Support Tickets" ], "summary": "Get ticket with comments", "description": "Returns ticket details including public comments. Admins also see internal comments.", "operationId": "get_api_tickets_show", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ticket details with comments", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string" }, "priority": { "type": "string" }, "category": { "type": "string" }, "comments": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "body": { "type": "string" }, "visibility": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/tickets/{id}/comments": { "post": { "tags": [ "12. Support Tickets" ], "summary": "Add comment to ticket", "operationId": "post_api_tickets_add_comment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "body" ], "properties": { "body": { "type": "string", "example": "Could you provide more details?" }, "visibility": { "type": "string", "example": "public", "enum": [ "public", "internal" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Comment added" }, "400": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/tickets/{id}/status": { "patch": { "tags": [ "12. Support Tickets" ], "summary": "Change ticket status (admin only)", "operationId": "patch_api_tickets_change_status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "status" ], "properties": { "status": { "type": "string", "example": "in_progress", "enum": [ "open", "in_progress", "waiting_user", "waiting_admin", "resolved", "closed" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Status changed" }, "400": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/translations/{locale}": { "get": { "tags": [ "07. Tools / Translations" ], "summary": "Get translations by locale", "description": "Returns all translations for a specific locale. Useful for client-side localization.", "operationId": "get_api_translations_locale", "parameters": [ { "name": "locale", "in": "path", "description": "Language code (e.g., en, uk, ru)", "required": true, "schema": { "type": "string", "maxLength": 5, "minLength": 2 } }, { "name": "domain", "in": "query", "description": "Translation domain (default: messages)", "required": false, "schema": { "type": "string", "default": "messages" } }, { "name": "prefix", "in": "query", "description": "Filter by key prefix (e.g., \"common.\" to get only common.* keys)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Translation strings", "content": { "application/json": { "schema": { "properties": { "locale": { "type": "string", "example": "en" }, "domain": { "type": "string", "example": "messages" }, "translations": { "type": "object", "example": { "common.save": "Save", "common.cancel": "Cancel" }, "additionalProperties": { "type": "string" } }, "total": { "type": "integer", "example": 150 } }, "type": "object" } } } }, "401": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/translations": { "post": { "tags": [ "07. Tools / Translations" ], "summary": "Get specific translation keys", "description": "Returns translations for specific keys. Useful when you need only certain strings.", "operationId": "post_api_translations_keys", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "locale", "keys" ], "properties": { "locale": { "type": "string", "example": "en" }, "keys": { "type": "array", "items": { "type": "string" }, "example": [ "common.save", "common.cancel", "auth.login" ] }, "domain": { "type": "string", "example": "messages", "default": "messages" } }, "type": "object" } } } }, "responses": { "200": { "description": "Translation strings", "content": { "application/json": { "schema": { "properties": { "locale": { "type": "string", "example": "en" }, "translations": { "type": "object", "example": { "common.save": "Save", "common.cancel": "Cancel" }, "additionalProperties": { "type": "string" } }, "missing": { "description": "Keys that were not found", "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "400": {}, "401": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/user/profile": { "get": { "tags": [ "02. User Profile" ], "summary": "Get user profile", "description": "Returns full profile information of the authenticated user", "operationId": "get_api_user_profile", "responses": { "200": { "description": "User profile", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Smith" }, "email": { "type": "string", "example": "john@example.com" }, "phone": { "type": "string", "example": "+48501234567", "nullable": true }, "locale": { "type": "string", "example": "en" }, "country": { "properties": { "code": { "type": "string", "example": "PL" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "phone_code": { "type": "string", "example": "+48" } }, "type": "object" }, "currency": { "properties": { "code": { "type": "string", "example": "EUR" }, "symbol": { "type": "string", "example": "\\u20AC" }, "name": { "type": "object", "additionalProperties": { "type": "string" } } }, "type": "object", "nullable": true }, "roles": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "notify_by_telegram": { "type": "boolean" }, "notify_by_email": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": {} }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "02. User Profile" ], "summary": "Update user profile", "description": "Update profile fields. Only provided fields will be updated.", "operationId": "put_api_user_update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "John Smith" }, "phone": { "type": "string", "example": "+48501234567", "nullable": true }, "locale": { "type": "string", "example": "en" }, "country_code": { "type": "string", "example": "PL" }, "currency_code": { "type": "string", "example": "EUR" }, "notify_by_telegram": { "type": "boolean", "example": true }, "notify_by_email": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Profile updated successfully" }, "user": { "type": "object" } }, "type": "object" } } } }, "400": {}, "401": {} }, "security": [ { "Bearer": [] } ] }, "patch": { "tags": [ "02. User Profile" ], "summary": "Partially update user profile", "description": "Update specific profile fields. Same as PUT.", "operationId": "patch_api_user_update", "responses": { "default": { "description": "" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/user/password": { "put": { "tags": [ "02. User Profile" ], "summary": "Change password", "description": "Change the current user password. Requires current password verification.", "operationId": "put_api_user_password", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "current_password", "new_password" ], "properties": { "current_password": { "type": "string", "format": "password" }, "new_password": { "type": "string", "format": "password" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password changed successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Password changed successfully" } }, "type": "object" } } } }, "400": {}, "401": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/user/roles": { "get": { "tags": [ "02. User Profile" ], "summary": "Get all roles", "description": "Returns list of all system roles with translations. Each role indicates if assigned to current user.", "operationId": "get_api_user_roles", "responses": { "200": { "description": "All system roles", "content": { "application/json": { "schema": { "properties": { "roles": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "ROLE_ADMIN" }, "name": { "type": "object", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "assigned": { "type": "boolean", "example": true } }, "type": "object" } } }, "type": "object" } } } }, "401": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/user/requisites/ukraine": { "get": { "tags": [ "02. User Profile" ], "summary": "Get Ukrainian requisites", "description": "Returns Ukrainian-specific requisites for the authenticated user. Only available if user country is Ukraine.", "operationId": "get_api_user_requisites_ukraine", "responses": { "200": { "description": "Ukrainian requisites", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "tax_id": { "type": "string", "example": "1234567890", "nullable": true }, "passport": { "type": "string", "nullable": true }, "iban": { "type": "string", "example": "UA213223130000026007233566001", "nullable": true }, "card_number": { "type": "string", "example": "**** **** **** 1234", "nullable": true }, "card_holder_name": { "type": "string", "example": "JOHN SMITH", "nullable": true }, "preferred_payment_method": { "type": "string", "example": "iban", "nullable": true, "enum": [ "iban", "card" ] }, "is_fop": { "type": "boolean", "example": false }, "fop_registry_number": { "type": "string", "nullable": true }, "fop_registration_date": { "type": "string", "format": "date", "nullable": true }, "fop_group": { "type": "integer", "example": 3, "nullable": true, "enum": [ 1, 2, 3 ] }, "address": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } }, "401": {}, "403": {} }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "02. User Profile" ], "summary": "Update Ukrainian requisites", "description": "Update Ukrainian-specific requisites. Only available if user country is Ukraine. Only provided fields will be updated.", "operationId": "put_api_user_requisites_ukraine_update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "tax_id": { "type": "string", "example": "1234567890", "nullable": true }, "passport": { "type": "string", "nullable": true }, "iban": { "type": "string", "example": "UA213223130000026007233566001", "nullable": true }, "card_number": { "type": "string", "example": "5168742000000000", "nullable": true }, "card_holder_name": { "type": "string", "example": "JOHN SMITH", "nullable": true }, "preferred_payment_method": { "type": "string", "example": "iban", "nullable": true, "enum": [ "iban", "card" ] }, "is_fop": { "type": "boolean", "example": false }, "fop_registry_number": { "type": "string", "nullable": true }, "fop_registration_date": { "type": "string", "format": "date", "example": "2020-01-15", "nullable": true }, "fop_group": { "type": "integer", "example": 3, "nullable": true, "enum": [ 1, 2, 3 ] }, "address": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Requisites updated successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Requisites updated successfully" }, "requisites": { "type": "object" } }, "type": "object" } } } }, "400": {}, "401": {}, "403": {} }, "security": [ { "Bearer": [] } ] }, "patch": { "tags": [ "02. User Profile" ], "summary": "Partially update Ukrainian requisites", "description": "Update specific fields. Same as PUT.", "operationId": "patch_api_user_requisites_ukraine_update", "responses": { "default": { "description": "" } }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/violations": { "get": { "tags": [ "03. Properties / Violations" ], "summary": "List property contract violations", "description": "Returns list of contract violations for the property.", "operationId": "get_api_property_violations_list", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "severity", "in": "query", "schema": { "type": "integer", "maximum": 10, "minimum": 1 } }, { "name": "contract_id", "in": "query", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Violations list", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "totalPages": { "type": "integer" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "03. Properties / Violations" ], "summary": "Create contract violation", "description": "Creates a new contract violation via ViolationService (description is HTML-sanitized, block and overdue-payment links are attached). If the contract has a tenant, it is auto-assigned as violator.", "operationId": "post_api_property_violations_create", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "contract_id", "violation_date", "severity", "description" ], "properties": { "contract_id": { "type": "integer", "example": 1 }, "violation_date": { "type": "string", "format": "date", "example": "2024-01-15" }, "severity": { "type": "integer", "example": 5, "maximum": 10, "minimum": 1 }, "description": { "type": "string", "maxLength": 5000 }, "block_ids": { "type": "array", "items": { "type": "integer" }, "nullable": true }, "payment_ids": { "description": "Overdue payment IDs to link", "type": "array", "items": { "type": "integer" }, "nullable": true } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/violations/{id}": { "get": { "tags": [ "03. Properties / Violations" ], "summary": "Get contract violation details", "description": "Returns violation details including attached documents and linked contract blocks.", "operationId": "get_api_property_violations_show", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Violation details with documents", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "id": { "type": "integer" }, "property_id": { "type": "integer" }, "contract_id": { "type": "integer" }, "violation_date": { "type": "string", "format": "date" }, "severity": { "type": "integer" }, "severity_level": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "description": { "type": "string" }, "violator": { "type": "object", "nullable": true }, "contract": { "type": "object", "nullable": true }, "documents": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "original_name": { "type": "string" }, "file_size": { "type": "integer" }, "file_url": { "type": "string" } }, "type": "object" } }, "blocks": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "name": { "type": "string" } }, "type": "object" } }, "documents_count": { "type": "integer" }, "blocks_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "03. Properties / Violations" ], "summary": "Update contract violation", "description": "Updates the violation via ViolationService (description is HTML-sanitized, block links and overdue-payment links are re-synced). If contract_id changes, violator is re-assigned to the new contract tenant. All body fields are optional (partial update).", "operationId": "put_api_property_violations_update", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "contract_id": { "type": "integer" }, "violation_date": { "type": "string", "format": "date" }, "severity": { "type": "integer", "maximum": 10, "minimum": 1 }, "description": { "type": "string" }, "block_ids": { "type": "array", "items": { "type": "integer" }, "nullable": true }, "payment_ids": { "description": "Overdue payment IDs to link (replaces existing)", "type": "array", "items": { "type": "integer" }, "nullable": true } }, "type": "object" } } } }, "responses": { "200": {}, "400": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "03. Properties / Violations" ], "summary": "Delete contract violation", "description": "Deletes the violation with S3-first cascade removal of attached documents. Returns 500 if S3 deletion fails.", "operationId": "delete_api_property_violations_delete", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "403": {}, "404": {}, "500": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/violations/{id}/documents": { "post": { "tags": [ "03. Properties / Violations" ], "summary": "Attach document to violation", "description": "Upload and attach a photo document to the contract violation.", "operationId": "post_api_property_violations_attach_document", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "document" ], "properties": { "document": { "type": "string", "format": "binary" }, "comment": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": {}, "400": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/violations/{id}/documents/{documentId}": { "delete": { "tags": [ "03. Properties / Violations" ], "summary": "Detach document from violation", "operationId": "delete_api_property_violations_detach_document", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": {}, "403": {}, "404": {} }, "security": [ { "Bearer": [] } ] } }, "/api/v1/properties/{propertyId}/violations/{id}/overdue-payments": { "get": { "tags": [ "03. Properties / Violations" ], "summary": "List overdue payments linked to violation", "operationId": "get_api_property_violations_overdue_payments", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "" } } }, "post": { "tags": [ "03. Properties / Violations" ], "summary": "Link overdue payments to violation", "operationId": "post_api_property_violations_attach_payments", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "payment_ids": { "type": "array", "items": { "type": "integer" } } }, "type": "object" } } } }, "responses": { "default": { "description": "" } } } }, "/api/v1/properties/{propertyId}/violations/{id}/overdue-payments/{paymentId}": { "delete": { "tags": [ "03. Properties / Violations" ], "summary": "Unlink overdue payment from violation", "operationId": "delete_api_property_violations_detach_payment", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "" } } } }, "/api/v1/properties/{propertyId}/overdue-payments": { "get": { "tags": [ "03. Properties / Violations" ], "summary": "List overdue payments not linked to any violation", "operationId": "get_api_property_overdue_payments", "parameters": [ { "name": "propertyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "" } } } } }, "components": { "schemas": { "PropertyMessage": { "properties": { "id": { "type": "integer", "example": 1 }, "message": { "type": "string", "example": "Hello, this is a test message", "maxLength": 1000 }, "createdAt": { "type": "string", "format": "date-time" }, "readAt": { "type": "string", "format": "date-time", "nullable": true }, "sender": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "type": "object" }, "recipient": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "type": "object" }, "property": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" }, "replyTo": { "properties": { "id": { "type": "integer" }, "message": { "type": "string" }, "sender": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "type": "object" } }, "type": "object", "nullable": true }, "hasFiles": { "type": "boolean", "example": true }, "filesCount": { "type": "integer", "example": 2 }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/PropertyMessageFile" } } }, "type": "object" }, "PropertyMessageFile": { "properties": { "id": { "type": "integer", "example": 1 }, "originalName": { "type": "string", "example": "document.pdf" }, "mimeType": { "type": "string", "example": "application/pdf" }, "fileSize": { "type": "integer", "example": 102400 }, "fileSizeFormatted": { "type": "string", "example": "100 KB" }, "isImage": { "type": "boolean", "example": false }, "isDocument": { "type": "boolean", "example": true }, "isArchive": { "type": "boolean", "example": false }, "url": { "type": "string", "format": "uri", "example": "https://s3.example.com/messages_chat/1/abc123.pdf" }, "createdAt": { "type": "string", "format": "date-time" } }, "type": "object" }, "ContractPrintRequest": { "required": [ "locales" ], "properties": { "locales": { "description": "Languages for print (max 2)", "type": "array", "items": { "type": "string", "enum": [ "uk", "en", "ru", "pl", "de" ] }, "example": [ "uk", "en" ] }, "layout": { "description": "Layout mode (only for main contract)", "type": "string", "example": "columns", "enum": [ "columns", "separate" ] } }, "type": "object" }, "ContractPrintResponse": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "html": { "description": "Base64-encoded HTML", "type": "string" }, "filename": { "type": "string", "example": "contract_Apartment1_2026-01-10_uk_en.html" } }, "type": "object" } }, "type": "object" }, "Scope": { "type": "string", "enum": [ "mine", "all" ] }, "CrmTaskStatus": { "type": "string", "enum": [ "new", "planned", "in_progress", "blocked", "review", "done", "cancelled" ] }, "ListTasksQuery": { "properties": { "scope": { "$ref": "#/components/schemas/Scope" }, "owner_id": { "type": "integer", "nullable": true, "default": null, "minimum": 0, "exclusiveMinimum": true }, "status": { "type": "array", "items": { "$ref": "#/components/schemas/CrmTaskStatus" }, "nullable": true, "default": null }, "page": { "type": "integer", "default": 1, "minimum": 0, "exclusiveMinimum": true }, "limit": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, "type": "object" }, "CreateTaskRequest": { "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "nullable": true, "default": null, "maxLength": 65535 }, "priority": { "type": "string", "default": "normal", "enum": [ "low", "normal", "high", "critical" ] }, "owner_id": { "type": "integer", "nullable": true, "default": null, "minimum": 0, "exclusiveMinimum": true }, "parent_task_id": { "type": "integer", "nullable": true, "default": null, "minimum": 0, "exclusiveMinimum": true }, "due_at": { "type": "string", "nullable": true, "default": null } }, "type": "object" }, "ListOwnersQuery": { "properties": { "status": { "type": "array", "items": { "$ref": "#/components/schemas/CrmTaskStatus" }, "nullable": true, "default": null }, "with_tasks": { "type": "boolean", "default": false } }, "type": "object" }, "AddCommentRequest": { "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 65535 } }, "type": "object" }, "ChangeStatusRequest": { "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "new", "planned", "in_progress", "blocked", "review", "done", "cancelled" ] } }, "type": "object" } }, "securitySchemes": { "Bearer": { "type": "http", "description": "Enter JWT token obtained from /api/v1/auth/login", "bearerFormat": "JWT", "scheme": "bearer" } } }, "security": [ { "Bearer": [] } ], "tags": [ { "name": "03. Properties / Expenses", "description": "Recurring property expenses configuration" }, { "name": "04. Contracts / Agreement Blocks", "description": "Contract terms and conditions" }, { "name": "07. Tools", "description": "General utilities" }, { "name": "01. Authentication", "description": "Login, registration, JWT tokens, Google OAuth" }, { "name": "14. Backup", "description": "Database backup: create, status, download, delete" }, { "name": "10. Billing", "description": "Subscription and invoices" }, { "name": "03. Properties / Communication Access", "description": "User access control for communications" }, { "name": "05. References / Communication Types", "description": "Communication type directory" }, { "name": "04. Contracts", "description": "Rental contract management" }, { "name": "04. Contracts / Print Forms", "description": "PDF generation for contracts" }, { "name": "03. Properties / Counters", "description": "Utility meters: water, gas, electricity readings" }, { "name": "05. References / Countries", "description": "Country directory" }, { "name": "05. References / Currencies", "description": "Currency directory with exchange rates" }, { "name": "06. Custom Contragents", "description": "User-created counterparties" }, { "name": "15. Diagnostics", "description": "Read-only production diagnostics via an isolated headless Claude run" }, { "name": "03. Properties / Documents", "description": "Property documents: upload, download, delete" }, { "name": "05. References / Document Types", "description": "Document type directory" }, { "name": "03. Properties / Expense Charges", "description": "Utility billing records" }, { "name": "03. Properties / Expense Documents", "description": "Documents attached to expense charges" }, { "name": "03. Properties / Expense Providers", "description": "Service providers linked to expenses" }, { "name": "05. References / Expense Types", "description": "Expense type directory" }, { "name": "07. Tools / Geolocation", "description": "IP-based country detection" }, { "name": "03. Properties / Landlord-Tenant Adjustments", "description": "Financial adjustments between parties" }, { "name": "05. References / Languages", "description": "Supported UI languages" }, { "name": "05. References / Units", "description": "Measurement units" }, { "name": "03. Properties / Negotiations", "description": "Rental price negotiations" }, { "name": "07. Tools / Nova Poshta", "description": "Address autocomplete" }, { "name": "11. Partner Invitations", "description": "Referral program" }, { "name": "03. Properties / Payments", "description": "Payments for utility charges and rent" }, { "name": "03. Properties / Penalties", "description": "Contract violation penalties" }, { "name": "03. Properties / Communications", "description": "Property communications: phone, email, addresses" }, { "name": "03. Properties", "description": "Property CRUD, property users, roles management" }, { "name": "05. References / Property Data Types", "description": "Property characteristic types" }, { "name": "03. Properties / Characteristics", "description": "Property data values: area, rooms, floors" }, { "name": "03. Properties / Expense Config Documents", "description": "Documents attached to expense configuration" }, { "name": "08. Messages", "description": "Property messaging system" }, { "name": "05. References / Property Types", "description": "Property type directory" }, { "name": "03. Properties / Proposals", "description": "Commercial rental proposals" }, { "name": "03. Properties / Rental Charges", "description": "Monthly rent billing records" }, { "name": "05. References / Rental Types", "description": "Rental type directory" }, { "name": "03. Properties / Repair Compensations", "description": "Tenant repair cost compensations" }, { "name": "03. Properties / Balance Adjustments", "description": "Service provider balance adjustments" }, { "name": "06. Service Providers", "description": "Service provider directory" }, { "name": "05. References / Tariff Zones", "description": "Utility tariff zones" }, { "name": "13. CRM Tasks", "description": "CRM internal tasks: list, detail, status change" }, { "name": "03. Properties / Tenant Assets", "description": "Landlord property inventory" }, { "name": "12. Support Tickets", "description": "CRM support tickets: create, comment, manage" }, { "name": "07. Tools / Translations", "description": "Translation management" }, { "name": "02. User Profile", "description": "User settings, locale, currency, notifications preferences" }, { "name": "03. Properties / Violations", "description": "Contract violation records" }, { "name": "12. Bonus & Referral", "description": "12. Bonus & Referral" }, { "name": "Calendar", "description": "Calendar" }, { "name": "06. References / Custom Contragents", "description": "06. References / Custom Contragents" }, { "name": "07. Properties", "description": "07. Properties" }, { "name": "Help Links", "description": "Help Links" }, { "name": "Receipts", "description": "Receipts" } ] }