API REST desenvolvida com Java e Spring Boot para geração de análises financeiras por meio da integração com a OpenAI.
A aplicação recebe uma massa de dados financeiros, solicita a geração de um relatório estruturado à inteligência artificial e armazena o histórico da análise no MongoDB.
A API Agentes IA implementa um agente especializado em finanças pessoais.
O agente analisa dados relacionados a:
- receitas e despesas;
- contas pagas e pendentes;
- valores recebidos e a receber;
- fluxo financeiro;
- categorias de gastos;
- saldo do período;
- pontos positivos;
- pontos de atenção;
- recomendações financeiras;
- plano de melhoria.
A análise é produzida exclusivamente com base nos dados enviados na requisição, seguindo instruções que impedem a criação de informações ausentes ou o uso de comandos encontrados dentro da própria massa de dados.
A análise gerada possui caráter informativo e não substitui a orientação de um profissional financeiro.
- Geração de relatórios financeiros com a OpenAI;
- Integração com a Responses API;
- Instruções personalizadas para o agente financeiro;
- Proteção contra instruções maliciosas presentes nos dados analisados;
- Validação de dados vazios;
- Limitação do tamanho da entrada;
- Limitação da quantidade máxima de tokens da resposta;
- Tratamento de respostas vazias, incompletas ou recusadas;
- Tratamento de erros retornados pela OpenAI;
- Persistência do histórico de relatórios no MongoDB;
- Documentação dos endpoints com Swagger/OpenAPI;
- Configuração global de CORS para integração com o frontend;
- Ambiente Docker com MongoDB, Mongo Express e MailHog;
- Configuração externa da chave da OpenAI por variável de ambiente.
Cliente
│
▼
RelatorioController
│
▼
RelatorioService
│
├──────────────► OpenAiComponent
│ │
│ ▼
│ OpenAI Responses API
│ │
│ ▼
│ Análise financeira
│
├──────────────► HistoricoRelatorioRepository
│ │
│ ▼
│ MongoDB
│
▼
RelatorioResponse
- O cliente envia os dados financeiros para a API;
- O controller encaminha a requisição para a camada de serviço;
- O serviço envia os dados para o componente de integração com a OpenAI;
- A OpenAI gera uma análise financeira estruturada;
- Os dados enviados e o resultado são armazenados no MongoDB;
- A análise é devolvida ao cliente.
| Tecnologia | Utilização |
|---|---|
| Java | Linguagem principal |
| Spring Boot | Desenvolvimento da API |
| Spring Web | Criação dos endpoints REST |
| Spring MVC | Configuração global de CORS |
| RestClient | Comunicação com a OpenAI |
| Spring Data MongoDB | Persistência dos relatórios |
| MongoDB | Banco de dados NoSQL |
| Jackson | Leitura e processamento de JSON |
| Lombok | Redução de código repetitivo |
| Swagger/OpenAPI | Documentação da API |
| Maven | Gerenciamento de dependências |
| Docker Compose | Orquestração do ambiente |
| Mongo Express | Administração visual do MongoDB |
| MailHog | Ambiente preparado para testes de e-mail |
| OpenAI Responses API | Geração das análises financeiras |
src
└── main
├── java
│ └── br.com.cotiinformatica.api_agentesia
│ ├── components
│ │ └── OpenAiComponent.java
│ ├── configurations
│ │ ├── CorsConfiguration.java
│ │ ├── ObjectMapperConfiguration.java
│ │ ├── RestClientConfiguration.java
│ │ └── SwaggerConfiguration.java
│ ├── controllers
│ │ └── RelatorioController.java
│ ├── dtos
│ │ ├── RelatorioRequest.java
│ │ └── RelatorioResponse.java
│ ├── entities
│ │ └── HistoricoRelatorio.java
│ ├── repositories
│ │ └── HistoricoRelatorioRepository.java
│ └── services
│ └── RelatorioService.java
└── resources
└── application.yaml
Antes de executar o projeto, tenha instalado:
- Java;
- Maven ou Maven Wrapper;
- Docker Desktop;
- Git;
- uma chave válida da API da OpenAI.
A chave da OpenAI não deve ser escrita diretamente no código-fonte.
O projeto utiliza a variável de ambiente:
OPENAI_API_KEY
A configuração correspondente no application.yaml deve permanecer desta forma:
openai:
apikey: ${OPENAI_API_KEY}
model: ${OPENAI_MODEL:gpt-4o-mini}Acesse:
Run → Edit Configurations → Environment variables
Cadastre:
OPENAI_API_KEY=sua_chave_da_openai
Opcionalmente, o modelo também pode ser alterado pela variável:
OPENAI_MODEL
Na raiz do projeto, execute:
docker compose up -dPara verificar os containers:
docker compose psO ambiente Docker inicia os seguintes serviços:
| Serviço | Endereço |
|---|---|
| MongoDB | localhost:27018 |
| Mongo Express | http://localhost:5058 |
| MailHog | http://localhost:8025 |
| Servidor SMTP do MailHog | localhost:1025 |
Usuário: coti
Senha: coti
Para encerrar os containers:
docker compose downPara encerrar e remover os volumes:
docker compose down -vO comando com
-vtambém remove os dados armazenados nos volumes do MongoDB.
A aplicação possui uma configuração global de CORS preparada para permitir a comunicação com o projeto frontend.
Origem autorizada:
http://localhost:8083
A configuração é aplicada a todos os endpoints da API:
/**
Métodos HTTP permitidos:
GET;POST;PUT;DELETE.
Também são permitidos todos os cabeçalhos enviados nas requisições.
A configuração está localizada na classe:
CorsConfiguration.java
No Windows PowerShell:
.\mvnw.cmd spring-boot:runTambém é possível executar a classe principal diretamente pelo IntelliJ IDEA.
A aplicação ficará disponível em:
http://localhost:8084
Com a aplicação em execução, acesse:
http://localhost:8084/swagger-ui/index.html
A especificação OpenAPI pode ser consultada em:
http://localhost:8084/v3/api-docs
POST /api/relatorios{
"usuario": "beatriz",
"dataInicio": "2026-07-01",
"dataFim": "2026-07-31",
"dadosAnalise": "Receita de R$ 5.000,00. Aluguel de R$ 1.200,00. Mercado de R$ 750,00. Energia de R$ 180,00."
}| Campo | Tipo | Descrição |
|---|---|---|
usuario |
String | Identificação do usuário |
dataInicio |
LocalDate | Data inicial do período |
dataFim |
LocalDate | Data final do período |
dadosAnalise |
String | Massa de dados financeiros enviada para análise |
As datas devem utilizar o formato ISO:
yyyy-MM-dd
Status HTTP:
201 Created
Exemplo:
{
"resultadoAnalise": "## 1. Resumo financeiro\n\nA análise financeira foi gerada com base nos dados fornecidos..."
}O agente é instruído a:
- responder sempre em português do Brasil;
- utilizar apenas os dados fornecidos;
- não inventar movimentações, datas, categorias ou valores;
- diferenciar receitas, despesas e contas pendentes;
- identificar informações ausentes ou inconsistentes;
- apresentar valores em reais no formato brasileiro;
- não recomendar produtos financeiros específicos;
- não garantir retornos financeiros;
- apresentar recomendações relacionadas aos dados analisados;
- informar que o relatório possui caráter informativo.
O relatório é organizado nas seguintes seções:
- Resumo financeiro;
- Distribuição das receitas e despesas;
- Fluxo financeiro;
- Contas pendentes;
- Pontos positivos;
- Pontos de atenção;
- Recomendações;
- Plano de melhoria;
- Informações ausentes;
- Conclusão.
O componente de integração aplica algumas medidas para tornar o processamento mais seguro:
- os dados são delimitados pelas marcações
<dados-financeiros>; - instruções presentes dentro dos dados devem ser ignoradas;
- o conteúdo recebido é tratado exclusivamente como informação financeira;
- a resposta não é armazenada pela OpenAI por meio da propriedade
store: false; - entradas vazias são rejeitadas;
- o tamanho máximo da entrada é de
200.000caracteres; - a resposta possui limite máximo de
3.000tokens; - recusas e respostas incompletas são identificadas e tratadas.
Cada relatório gerado cria um documento na coleção:
historico_relatorio
Estrutura armazenada:
{
"_id": "identificador-gerado-pelo-mongodb",
"data_hora": "2026-07-17T12:00:00",
"usuario": "beatriz",
"dados_analise": "Dados financeiros enviados pelo usuário",
"resultado_analise": "Análise financeira gerada pela OpenAI"
}Nesta versão:
- os campos
dataInicioedataFimfazem parte do DTO de entrada, mas ainda não são enviados separadamente para a OpenAI; - o período ainda não é armazenado na entidade de histórico;
- o MailHog está configurado no Docker, mas o envio do relatório por e-mail ainda não foi implementado;
- a configuração do Swagger possui suporte preparado para Bearer Token, mas a autenticação JWT ainda não foi implementada;
- ainda não existe endpoint para consultar o histórico de relatórios;
- ainda não existe tratamento global de exceções.
- Implementar validações com Jakarta Validation;
- Validar se a data inicial é anterior à data final;
- Incluir o período no conteúdo enviado para a OpenAI;
- Armazenar as datas inicial e final no MongoDB;
- Implementar consulta ao histórico de relatórios;
- Implementar envio do relatório por e-mail;
- Utilizar o MailHog nos testes de envio;
- Implementar autenticação e autorização com JWT;
- Criar tratamento global de exceções;
- Adicionar testes unitários e testes de integração;
- Documentar exemplos de erros no Swagger;
- Criar container Docker para a própria API.
Desenvolvido por Beatriz Lima.
GitHub: beatrizlima-tech