{
    "openapi": "3.0.0",
    "info": {
        "title": "API Resyde Mobile Usuarios",
        "description": "Backend API para aplicación móvil de usuarios Resyde - reemplaza el acceso SQL directo a producción que hacía la app Flutter por endpoints REST autenticados con JWT.",
        "contact": {
            "email": "support@resyde.com"
        },
        "version": "1.0.0"
    },
    "servers": [
        {
            "url": "http://localhost:8000"
        }
    ],
    "paths": {
        "/api/activities": {
            "get": {
                "tags": [
                    "Activities"
                ],
                "summary": "Listar las últimas 5 actividades de la residencia",
                "operationId": "53e7a0b67f6097ed90245000764b2e5e",
                "responses": {
                    "200": {
                        "description": "Lista de actividades"
                    },
                    "401": {
                        "description": "No autenticado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/auth/login": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Login de residente",
                "operationId": "8dcb70df1020986038d098cc08d05dae",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "residencia_id",
                                    "member_id",
                                    "password"
                                ],
                                "properties": {
                                    "residencia_id": {
                                        "description": "id_esquema_principal obtenido de GET /api/residencias",
                                        "type": "integer",
                                        "example": 8
                                    },
                                    "member_id": {
                                        "type": "string",
                                        "example": "jperez"
                                    },
                                    "password": {
                                        "type": "string",
                                        "example": "secret123"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Login exitoso"
                    },
                    "401": {
                        "description": "Credenciales inválidas"
                    },
                    "404": {
                        "description": "Residencia no encontrada"
                    },
                    "422": {
                        "description": "Error de validación"
                    }
                }
            }
        },
        "/api/auth/refresh": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Obtener un nuevo access token a partir de un refresh token vigente",
                "operationId": "b2eae7a8032954d25b46c7ec6f489c68",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "refresh_token"
                                ],
                                "properties": {
                                    "refresh_token": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Nuevo access token"
                    },
                    "401": {
                        "description": "Refresh token inválido o expirado"
                    }
                }
            }
        },
        "/api/auth/change-password": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Cambiar contraseña del residente autenticado",
                "operationId": "08c9518b6810698f562d5e627d58ba9e",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "current_password",
                                    "new_password",
                                    "new_password_confirmation"
                                ],
                                "properties": {
                                    "current_password": {
                                        "type": "string"
                                    },
                                    "new_password": {
                                        "type": "string"
                                    },
                                    "new_password_confirmation": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Contraseña actualizada"
                    },
                    "400": {
                        "description": "Contraseña actual incorrecta"
                    },
                    "401": {
                        "description": "No autenticado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/consolidados": {
            "get": {
                "tags": [
                    "Consolidados"
                ],
                "summary": "Listar los últimos 3 consolidados mensuales de la residencia",
                "operationId": "0dc0b65490717a50a04d10b0b37c707d",
                "responses": {
                    "200": {
                        "description": "Lista de consolidados (vacía si la residencia no tiene esta tabla)"
                    },
                    "401": {
                        "description": "No autenticado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/contacts": {
            "get": {
                "tags": [
                    "Contacts"
                ],
                "summary": "Listar contactos de la residencia del usuario",
                "operationId": "0f9efb5609dbb039b35ecafb28e492a2",
                "responses": {
                    "200": {
                        "description": "Lista de contactos"
                    },
                    "401": {
                        "description": "No autenticado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/documents": {
            "get": {
                "tags": [
                    "Documents"
                ],
                "summary": "Listar documentos vigentes de la residencia del usuario",
                "operationId": "479e53af7d4820aecb8f9534fdbe21aa",
                "responses": {
                    "200": {
                        "description": "Lista de documentos"
                    },
                    "401": {
                        "description": "No autenticado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/documents/{id}/download": {
            "get": {
                "tags": [
                    "Documents"
                ],
                "summary": "Descargar el archivo de un documento",
                "operationId": "9c3894d9d7b13268e679345d76550898",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Archivo del documento"
                    },
                    "404": {
                        "description": "Documento no encontrado"
                    },
                    "401": {
                        "description": "No autenticado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/documents/{id}/text": {
            "get": {
                "tags": [
                    "Documents"
                ],
                "summary": "Extraer el texto de un documento PDF",
                "operationId": "74de261e7c114a5f9bd3460baff1e917",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Texto extraído"
                    },
                    "404": {
                        "description": "Documento no encontrado"
                    },
                    "422": {
                        "description": "El documento no es un PDF"
                    },
                    "401": {
                        "description": "No autenticado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/invoices": {
            "get": {
                "tags": [
                    "Invoices"
                ],
                "summary": "Listar recibos del residente autenticado",
                "operationId": "0b8e5b661b472432febe76177e627e86",
                "responses": {
                    "200": {
                        "description": "Lista de recibos"
                    },
                    "401": {
                        "description": "No autenticado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/invoices/meter-image": {
            "get": {
                "tags": [
                    "Invoices"
                ],
                "summary": "Obtener la imagen del medidor de un recibo",
                "operationId": "8653fcc9c0d3d3b7eeac5e8c9c87448c",
                "parameters": [
                    {
                        "name": "invoice_id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Imagen del medidor"
                    },
                    "404": {
                        "description": "Recibo o imagen no encontrada"
                    },
                    "401": {
                        "description": "No autenticado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/maintenance": {
            "get": {
                "tags": [
                    "Maintenance"
                ],
                "summary": "Listar los últimos 5 mantenimientos de la residencia",
                "operationId": "aad24331808cb5a4d92e1ef5a306c775",
                "responses": {
                    "200": {
                        "description": "Lista de mantenimientos"
                    },
                    "401": {
                        "description": "No autenticado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/payments": {
            "get": {
                "tags": [
                    "Payments"
                ],
                "summary": "Listar pagos del residente autenticado",
                "operationId": "826dc6b24dd704607aa018a59207dd96",
                "responses": {
                    "200": {
                        "description": "Lista de pagos"
                    },
                    "401": {
                        "description": "No autenticado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/residencias": {
            "get": {
                "tags": [
                    "Residencias"
                ],
                "summary": "Listar residencias disponibles",
                "operationId": "e7486b3539f9c9176bd5c7950ee9efe8",
                "responses": {
                    "200": {
                        "description": "Lista de residencias",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "description": "Autenticación mediante JWT propio (firebase/php-jwt). Incluye el token obtenido en /api/auth/login en el header: Authorization: Bearer {token}",
                "bearerFormat": "JWT",
                "scheme": "bearer"
            }
        }
    },
    "tags": [
        {
            "name": "Activities",
            "description": "Actividades recientes de la residencia"
        },
        {
            "name": "Auth",
            "description": "Autenticación de residentes (membership_users) por residencia"
        },
        {
            "name": "Consolidados",
            "description": "Consolidados mensuales de la residencia"
        },
        {
            "name": "Contacts",
            "description": "Contactos de la residencia"
        },
        {
            "name": "Documents",
            "description": "Documentos (reglamentos, actas, comunicados) de la residencia"
        },
        {
            "name": "Invoices",
            "description": "Recibos del residente autenticado"
        },
        {
            "name": "Maintenance",
            "description": "Mantenimientos recientes de la residencia"
        },
        {
            "name": "Payments",
            "description": "Pagos del residente autenticado"
        },
        {
            "name": "Residencias",
            "description": "Listado público de residencias para el selector de login"
        }
    ]
}