{
    "swagger": "2.0",
    "info": {
        "description": "API for managing citizen data with self-declared information. This API provides endpoints for retrieving and updating citizen information, with support for caching and data validation. Self-declared data takes precedence over base data when available.",
        "title": "RMI API",
        "contact": {
            "name": "API Support",
            "url": "http://www.swagger.io/support",
            "email": "support@swagger.io"
        },
        "license": {
            "name": "Apache 2.0",
            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
        },
        "version": "1.0"
    },
    "host": "localhost:8080",
    "basePath": "/v1",
    "paths": {
        "/citizen/{cpf}": {
            "get": {
                "description": "Retrieves citizen data by CPF, combining base data with any self-declared updates. Self-declared data takes precedence over base data. Results are cached using Redis with configurable TTL.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "citizen"
                ],
                "summary": "Get citizen data",
                "parameters": [
                    {
                        "maxLength": 11,
                        "minLength": 11,
                        "type": "string",
                        "description": "Citizen CPF (11 digits)",
                        "name": "cpf",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Complete citizen data",
                        "schema": {
                            "$ref": "#/definitions/models.Citizen"
                        }
                    },
                    "400": {
                        "description": "Invalid CPF format",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    },
                    "404": {
                        "description": "Citizen not found",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal server error",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    }
                }
            }
        },
        "/citizen/{cpf}/address": {
            "put": {
                "description": "Updates or creates the self-declared address for a citizen by CPF. Only the address field is updated.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "citizen"
                ],
                "summary": "Update self-declared address for a citizen",
                "parameters": [
                    {
                        "type": "string",
                        "description": "CPF number",
                        "name": "cpf",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Self-declared address",
                        "name": "data",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/models.SelfDeclaredAddressInput"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/handlers.SuccessResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    }
                }
            }
        },
        "/citizen/{cpf}/email": {
            "put": {
                "description": "Updates or creates the self-declared email for a citizen by CPF. Only the email field is updated.",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "citizen"
                ],
                "summary": "Update self-declared email for a citizen",
                "parameters": [
                    {
                        "type": "string",
                        "description": "CPF number",
                        "name": "cpf",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Self-declared email",
                        "name": "data",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/models.SelfDeclaredEmailInput"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/handlers.SuccessResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    }
                }
            }
        },
        "/citizen/{cpf}/firstlogin": {
            "get": {
                "description": "Checks if this is the user's first login",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "citizen"
                ],
                "summary": "Get first login status",
                "parameters": [
                    {
                        "type": "string",
                        "description": "CPF number",
                        "name": "cpf",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/models.UserConfigResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    }
                }
            },
            "put": {
                "description": "Sets the first login status to false for a user",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "citizen"
                ],
                "summary": "Update first login status",
                "parameters": [
                    {
                        "type": "string",
                        "description": "CPF number",
                        "name": "cpf",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/models.UserConfigResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    }
                }
            }
        },
        "/citizen/{cpf}/optin": {
            "get": {
                "description": "Checks if the user has opted in for notifications",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "citizen"
                ],
                "summary": "Get opt-in status",
                "parameters": [
                    {
                        "type": "string",
                        "description": "CPF number",
                        "name": "cpf",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/models.UserConfigOptInResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    }
                }
            },
            "put": {
                "description": "Updates the user's opt-in status for notifications",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "citizen"
                ],
                "summary": "Update opt-in status",
                "parameters": [
                    {
                        "type": "string",
                        "description": "CPF number",
                        "name": "cpf",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Opt-in status",
                        "name": "data",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/models.UserConfigOptInResponse"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/models.UserConfigOptInResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    }
                }
            }
        },
        "/citizen/{cpf}/phone": {
            "put": {
                "description": "Updates or creates the self-declared phone for a citizen by CPF. Only the phone field is updated (stored as pending until verified).",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "citizen"
                ],
                "summary": "Update self-declared phone for a citizen",
                "parameters": [
                    {
                        "type": "string",
                        "description": "CPF number",
                        "name": "cpf",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Self-declared phone",
                        "name": "data",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/models.SelfDeclaredPhoneInput"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/handlers.SuccessResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    }
                }
            }
        },
        "/citizen/{cpf}/phone/validate": {
            "post": {
                "description": "Validates the verification code sent to the phone number",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "citizen"
                ],
                "summary": "Validate phone verification",
                "parameters": [
                    {
                        "type": "string",
                        "description": "CPF number",
                        "name": "cpf",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "Verification code and phone",
                        "name": "data",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/models.PhoneVerificationValidateRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/handlers.SuccessResponse"
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/handlers.ErrorResponse"
                        }
                    }
                }
            }
        },
        "/health": {
            "get": {
                "description": "Checks the health of the API and its dependencies (MongoDB and Redis). Returns detailed status for each service.",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "health"
                ],
                "summary": "Health check endpoint",
                "responses": {
                    "200": {
                        "description": "All services are healthy",
                        "schema": {
                            "$ref": "#/definitions/handlers.HealthResponse"
                        }
                    },
                    "503": {
                        "description": "One or more services are unhealthy",
                        "schema": {
                            "$ref": "#/definitions/handlers.HealthResponse"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "handlers.ErrorResponse": {
            "type": "object",
            "properties": {
                "error": {
                    "type": "string"
                }
            }
        },
        "handlers.HealthResponse": {
            "type": "object",
            "properties": {
                "services": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "string"
                    }
                },
                "status": {
                    "type": "string"
                },
                "timestamp": {
                    "type": "string"
                }
            }
        },
        "handlers.SuccessResponse": {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string"
                }
            }
        },
        "models.Citizen": {
            "type": "object",
            "properties": {
                "cpf": {
                    "type": "string"
                },
                "cpf_particao": {
                    "type": "integer"
                },
                "datalake": {
                    "$ref": "#/definitions/models.Datalake"
                },
                "documentos": {
                    "$ref": "#/definitions/models.Documentos"
                },
                "email": {
                    "$ref": "#/definitions/models.Email"
                },
                "endereco": {
                    "$ref": "#/definitions/models.Endereco"
                },
                "mae": {
                    "$ref": "#/definitions/models.Mae"
                },
                "menor_idade": {
                    "type": "boolean"
                },
                "nascimento": {
                    "$ref": "#/definitions/models.Nascimento"
                },
                "nome": {
                    "type": "string"
                },
                "nome_social": {
                    "type": "string"
                },
                "obito": {
                    "$ref": "#/definitions/models.Obito"
                },
                "raca": {
                    "type": "string"
                },
                "row_number": {
                    "type": "integer"
                },
                "saude": {
                    "$ref": "#/definitions/models.Saude"
                },
                "sexo": {
                    "type": "string"
                },
                "telefone": {
                    "$ref": "#/definitions/models.Telefone"
                }
            }
        },
        "models.ClinicaFamilia": {
            "type": "object",
            "properties": {
                "id_cnes": {
                    "type": "string"
                },
                "indicador": {
                    "type": "boolean"
                },
                "nome": {
                    "type": "string"
                },
                "telefone": {
                    "type": "string"
                }
            }
        },
        "models.Datalake": {
            "type": "object",
            "properties": {
                "last_updated": {
                    "type": "string"
                }
            }
        },
        "models.Documentos": {
            "type": "object",
            "properties": {
                "cns": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "models.Email": {
            "type": "object",
            "properties": {
                "alternativo": {
                    "type": "array",
                    "items": {
                        "type": "integer"
                    }
                },
                "indicador": {
                    "type": "boolean"
                },
                "principal": {
                    "$ref": "#/definitions/models.EmailPrincipal"
                }
            }
        },
        "models.EmailPrincipal": {
            "type": "object",
            "properties": {
                "origem": {
                    "type": "string"
                },
                "sistema": {
                    "type": "string"
                },
                "valor": {
                    "type": "string"
                }
            }
        },
        "models.Endereco": {
            "type": "object",
            "properties": {
                "alternativo": {
                    "type": "array",
                    "items": {
                        "type": "integer"
                    }
                },
                "indicador": {
                    "type": "boolean"
                },
                "principal": {
                    "$ref": "#/definitions/models.EnderecoPrincipal"
                }
            }
        },
        "models.EnderecoPrincipal": {
            "type": "object",
            "properties": {
                "bairro": {
                    "type": "string"
                },
                "cep": {
                    "type": "string"
                },
                "complemento": {
                    "type": "string"
                },
                "estado": {
                    "type": "string"
                },
                "logradouro": {
                    "type": "string"
                },
                "municipio": {
                    "type": "string"
                },
                "numero": {
                    "type": "string"
                },
                "origem": {
                    "type": "string"
                },
                "sistema": {
                    "type": "string"
                },
                "tipo_logradouro": {
                    "type": "string"
                }
            }
        },
        "models.EquipeSaudeFamilia": {
            "type": "object",
            "properties": {
                "id_ine": {
                    "type": "string"
                },
                "indicador": {
                    "type": "boolean"
                },
                "nome": {
                    "type": "string"
                },
                "telefone": {
                    "type": "string"
                }
            }
        },
        "models.Mae": {
            "type": "object",
            "properties": {
                "cpf": {
                    "type": "integer"
                },
                "nome": {
                    "type": "string"
                }
            }
        },
        "models.Nascimento": {
            "type": "object",
            "properties": {
                "data": {
                    "type": "string"
                },
                "municipio": {
                    "type": "string"
                },
                "municipio_id": {
                    "type": "string"
                },
                "pais": {
                    "type": "string"
                },
                "pais_id": {
                    "type": "string"
                },
                "uf": {
                    "type": "string"
                }
            }
        },
        "models.Obito": {
            "type": "object",
            "properties": {
                "ano": {
                    "type": "integer"
                },
                "indicador": {
                    "type": "boolean"
                }
            }
        },
        "models.PhoneVerificationValidateRequest": {
            "type": "object",
            "required": [
                "code",
                "ddd",
                "ddi",
                "valor"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "ddd": {
                    "type": "string"
                },
                "ddi": {
                    "type": "string"
                },
                "valor": {
                    "type": "string"
                }
            }
        },
        "models.Saude": {
            "type": "object",
            "properties": {
                "clinica_familia": {
                    "$ref": "#/definitions/models.ClinicaFamilia"
                },
                "equipe_saude_familia": {
                    "$ref": "#/definitions/models.EquipeSaudeFamilia"
                }
            }
        },
        "models.SelfDeclaredAddressInput": {
            "type": "object",
            "required": [
                "bairro",
                "cep",
                "estado",
                "logradouro",
                "municipio",
                "numero"
            ],
            "properties": {
                "bairro": {
                    "type": "string"
                },
                "cep": {
                    "type": "string"
                },
                "complemento": {
                    "type": "string"
                },
                "estado": {
                    "type": "string"
                },
                "logradouro": {
                    "type": "string"
                },
                "municipio": {
                    "type": "string"
                },
                "numero": {
                    "type": "string"
                },
                "tipo_logradouro": {
                    "type": "string"
                }
            }
        },
        "models.SelfDeclaredEmailInput": {
            "type": "object",
            "required": [
                "valor"
            ],
            "properties": {
                "valor": {
                    "type": "string"
                }
            }
        },
        "models.SelfDeclaredPhoneInput": {
            "type": "object",
            "required": [
                "ddd",
                "ddi",
                "valor"
            ],
            "properties": {
                "ddd": {
                    "type": "string"
                },
                "ddi": {
                    "type": "string"
                },
                "valor": {
                    "type": "string"
                }
            }
        },
        "models.Telefone": {
            "type": "object",
            "properties": {
                "alternativo": {
                    "type": "array",
                    "items": {
                        "type": "integer"
                    }
                },
                "indicador": {
                    "type": "boolean"
                },
                "principal": {
                    "$ref": "#/definitions/models.TelefonePrincipal"
                }
            }
        },
        "models.TelefonePrincipal": {
            "type": "object",
            "properties": {
                "ddd": {
                    "type": "string"
                },
                "ddi": {
                    "type": "string"
                },
                "origem": {
                    "type": "string"
                },
                "sistema": {
                    "type": "string"
                },
                "valor": {
                    "type": "string"
                }
            }
        },
        "models.UserConfigOptInResponse": {
            "type": "object",
            "properties": {
                "optin": {
                    "type": "boolean"
                }
            }
        },
        "models.UserConfigResponse": {
            "type": "object",
            "properties": {
                "firstlogin": {
                    "type": "boolean"
                }
            }
        }
    },
    "securityDefinitions": {
        "ApiKeyAuth": {
            "type": "apiKey",
            "name": "Authorization",
            "in": "header"
        }
    },
    "tags": [
        {
            "description": "Operations about citizens",
            "name": "citizen"
        },
        {
            "description": "Health check operations",
            "name": "health"
        }
    ]
}