{
    "openapi": "3.0.0",
    "info": {
        "title": "API EcofemPeru Asistencia",
        "description": "Backend API para la app movil de asistencia del consultorio ginecologico EcofemPeru. Expone usuario, asignacion_recurrente y registro_asistencia mediante endpoints REST autenticados con JWT.",
        "contact": {
            "email": "support@ecofemperu.com"
        },
        "version": "1.0.0"
    },
    "servers": [
        {
            "url": "http://localhost:8000"
        }
    ],
    "paths": {
        "/api/usuarios/{usuario}/asignaciones": {
            "get": {
                "tags": [
                    "Asignaciones"
                ],
                "summary": "Listar asignaciones (activas e historicas) de un trabajador",
                "operationId": "b71b7d2e7a27de52ae12e0cecd071b6e",
                "parameters": [
                    {
                        "name": "usuario",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lista de asignaciones (vacia si el usuario no tiene personal asociado)"
                    },
                    "404": {
                        "description": "Usuario no encontrado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/asistencia/hoy": {
            "get": {
                "tags": [
                    "Asistencia"
                ],
                "summary": "Registro de asistencia de hoy del usuario autenticado",
                "operationId": "c198adebbb859512ec1d56cf592fe12d",
                "responses": {
                    "200": {
                        "description": "Registro de hoy o null si aun no marco entrada"
                    },
                    "401": {
                        "description": "No autenticado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/asistencia/entrada": {
            "post": {
                "tags": [
                    "Asistencia"
                ],
                "summary": "Marcar entrada del usuario autenticado",
                "operationId": "9f34ed1cb89120b5624d324ff07362ad",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "required": [
                                    "latitud",
                                    "longitud"
                                ],
                                "properties": {
                                    "latitud": {
                                        "type": "number",
                                        "example": -12.0464
                                    },
                                    "longitud": {
                                        "type": "number",
                                        "example": -77.0428
                                    },
                                    "foto": {
                                        "type": "string",
                                        "format": "binary"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Entrada registrada"
                    },
                    "409": {
                        "description": "Ya marco entrada hoy"
                    },
                    "422": {
                        "description": "Error de validacion"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/asistencia/salida": {
            "post": {
                "tags": [
                    "Asistencia"
                ],
                "summary": "Marcar salida del usuario autenticado",
                "operationId": "221331b02000b0ca749635a5384ab514",
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "required": [
                                    "latitud",
                                    "longitud"
                                ],
                                "properties": {
                                    "latitud": {
                                        "type": "number",
                                        "example": -12.0464
                                    },
                                    "longitud": {
                                        "type": "number",
                                        "example": -77.0428
                                    },
                                    "foto": {
                                        "type": "string",
                                        "format": "binary"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Salida registrada"
                    },
                    "404": {
                        "description": "Aun no marco entrada hoy"
                    },
                    "409": {
                        "description": "Ya marco salida hoy"
                    },
                    "422": {
                        "description": "Error de validacion"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/asistencia/historial": {
            "get": {
                "tags": [
                    "Asistencia"
                ],
                "summary": "Historial de asistencia del usuario autenticado",
                "operationId": "a9a208e2bc2d24a489917b7149a74367",
                "parameters": [
                    {
                        "name": "desde",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "hasta",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page_size",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Historial paginado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/asistencia": {
            "get": {
                "tags": [
                    "Asistencia"
                ],
                "summary": "Listar registros de asistencia (panel administrativo)",
                "operationId": "9a3657c83f95bd1f23216e0af66099fc",
                "parameters": [
                    {
                        "name": "id_personal",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "desde",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "hasta",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "estado",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lista de registros"
                    },
                    "403": {
                        "description": "Sin permiso (requiere rol Administrador o Supervisor)"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/asistencia/{registro}": {
            "put": {
                "tags": [
                    "Asistencia"
                ],
                "summary": "Corregir un registro de asistencia (panel administrativo)",
                "operationId": "0c8f6db44f729943b8136a94b2b40557",
                "parameters": [
                    {
                        "name": "registro",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "motivo_modificacion"
                                ],
                                "properties": {
                                    "hora_entrada": {
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "hora_salida": {
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "estado": {
                                        "type": "string"
                                    },
                                    "observaciones": {
                                        "type": "string"
                                    },
                                    "motivo_modificacion": {
                                        "type": "string",
                                        "example": "Trabajador olvido marcar, ajustado por RRHH"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Registro corregido"
                    },
                    "403": {
                        "description": "Sin permiso (requiere rol Administrador o Supervisor)"
                    },
                    "404": {
                        "description": "No encontrado"
                    },
                    "422": {
                        "description": "Error de validacion"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/auth/login": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Login de trabajador",
                "operationId": "8dcb70df1020986038d098cc08d05dae",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "username",
                                    "password"
                                ],
                                "properties": {
                                    "username": {
                                        "type": "string",
                                        "example": "jperez"
                                    },
                                    "password": {
                                        "type": "string",
                                        "example": "1234"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Login exitoso"
                    },
                    "401": {
                        "description": "Credenciales invalidas"
                    },
                    "403": {
                        "description": "Usuario deshabilitado"
                    },
                    "422": {
                        "description": "Error de validacion"
                    }
                }
            }
        },
        "/api/auth/me": {
            "get": {
                "tags": [
                    "Auth"
                ],
                "summary": "Obtener el usuario autenticado segun el token",
                "operationId": "b9abb1a7a74670a19c215c2c133f14d8",
                "responses": {
                    "200": {
                        "description": "Usuario autenticado"
                    },
                    "401": {
                        "description": "No autenticado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/auth/logout": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "summary": "Cerrar sesion (el cliente descarta el token)",
                "operationId": "69281b12abb272c76871f19cb17ca563",
                "responses": {
                    "200": {
                        "description": "Sesion cerrada"
                    },
                    "401": {
                        "description": "No autenticado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/usuarios": {
            "get": {
                "tags": [
                    "Usuarios"
                ],
                "summary": "Listar trabajadores",
                "operationId": "e9d4d8b419dbef04b5748fbf9ccf3881",
                "parameters": [
                    {
                        "name": "activo",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Busca en nombre_completo, dni, codigo o username",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lista de trabajadores"
                    },
                    "401": {
                        "description": "No autenticado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/usuarios/{usuario}": {
            "get": {
                "tags": [
                    "Usuarios"
                ],
                "summary": "Detalle de un trabajador",
                "operationId": "0f23afcf09c72acc26c2106f9157305a",
                "parameters": [
                    {
                        "name": "usuario",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Detalle del trabajador"
                    },
                    "404": {
                        "description": "No encontrado"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/usuario/{usuario}/firma": {
            "get": {
                "tags": [
                    "Usuarios"
                ],
                "summary": "Descargar la firma (imagen) de un trabajador",
                "operationId": "36a697b90c95ced142ec53731f93c65b",
                "parameters": [
                    {
                        "name": "usuario",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Imagen binaria de la firma"
                    },
                    "404": {
                        "description": "Sin firma registrada"
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "description": "Autenticacion 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": "Asignaciones",
            "description": "Horarios recurrentes asignados a cada trabajador (solo lectura; se administran desde la web ERP)"
        },
        {
            "name": "Asistencia",
            "description": "Marcacion de entrada/salida y consulta de registros de asistencia"
        },
        {
            "name": "Auth",
            "description": "Autenticacion de trabajadores del consultorio (tabla usuario)"
        },
        {
            "name": "Usuarios",
            "description": "Consulta de trabajadores del consultorio (tabla usuario). La creacion/edicion se administra desde la web ERP."
        }
    ]
}