bot-report-api

API REST para gerenciamento de relatórios de execução de bots — construída com FastAPI, Pydantic v2 e princípios de clean architecture.

---

O problema

Times de automação RPA precisam de visibilidade sobre o desempenho dos seus bots: quais falharam, quantas execuções ocorreram hoje, qual a taxa de sucesso. Sem um sistema central, essas informações ficam espalhadas em logs e planilhas.

bot-report-api centraliza o registro e a consulta dessas métricas com uma API REST moderna e documentada.

---

Instalação e execução

git clone https://github.com/EricJoness/bot-report-api.git
cd bot-report-api
pip install -e ".[dev]"

# Subir o servidor
uvicorn bot_report_api.main:app --reload

Acesse a documentação interativa em: http://localhost:8000/docs

---

Endpoints

🤖 Bots

Método	Rota	Descrição
GET	/bots/	Lista todos os bots (filtro: ?ativo=true)
POST	/bots/	Cadastra novo bot
GET	/bots/{id}	Busca bot por ID
DELETE	/bots/{id}	Remove bot

▶️ Execuções

Método	Rota	Descrição
GET	/execucoes/	Lista execuções (filtros: bot_id, status)
POST	/execucoes/	Registra início de execução
GET	/execucoes/{id}	Busca execução por ID
PATCH	/execucoes/{id}	Atualiza status (sucesso/falha/cancelado)

📊 Relatórios

Método	Rota	Descrição
GET	/relatorios/	Relatório geral com métricas de todos os bots

---

Exemplos de uso

Cadastrar um bot

curl -X POST http://localhost:8000/bots/ \
  -H "Content-Type: application/json" \
  -d '{"nome": "Bot NF-e", "tipo": "api", "descricao": "Emite notas fiscais"}'

Registrar uma execução

curl -X POST http://localhost:8000/execucoes/ \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 1, "status": "em_andamento"}'

Finalizar com sucesso

curl -X PATCH http://localhost:8000/execucoes/1 \
  -H "Content-Type: application/json" \
  -d '{"status": "sucesso", "duracao_segundos": 12.5, "mensagem": "Nota emitida com sucesso."}'

Consultar relatório geral

curl http://localhost:8000/relatorios/

Resposta:

{
  "total_bots": 3,
  "total_execucoes": 10,
  "execucoes_hoje": 4,
  "taxa_sucesso_geral_pct": 80.0,
  "bots": [
    {
      "bot_id": 1,
      "nome_bot": "Bot NF-e",
      "total_execucoes": 5,
      "sucesso": 4,
      "falhas": 1,
      "taxa_sucesso_pct": 80.0,
      "duracao_media_segundos": 11.2
    }
  ]
}

---

Executar os testes

pytest tests/ -v --cov=bot_report_api

Os testes usam TestClient do FastAPI — nenhum servidor real precisa estar rodando.

---

Estrutura do projeto

bot-report-api/
├── bot_report_api/
│   ├── main.py          # App FastAPI + routers + lifespan
│   ├── schemas.py       # Modelos Pydantic v2
│   ├── database.py      # Camada de dados (in-memory)
│   └── routers/
│       ├── bots.py      # CRUD de bots
│       ├── execucoes.py # Registro de execuções
│       └── relatorios.py# Métricas agregadas
└── tests/
    └── test_api.py      # 18 testes de integração

---

Roadmap

• Persistência com SQLAlchemy + PostgreSQL
• Autenticação JWT
• Paginação nos endpoints de listagem
• Webhook para notificar falhas em tempo real
• Dashboard com métricas históricas

---

Licença

MIT © Eric Jones Silva