Skip to content

Latest commit

 

History

History
283 lines (227 loc) · 7.65 KB

README.md

File metadata and controls

283 lines (227 loc) · 7.65 KB

Fiscal XML API - Prova de Conceito (POC)

API para processamento automatizado de documentos fiscais eletrônicos (NF-e) com integração às APIs governamentais para cálculos tributários conforme Reforma Tributária (IBS, CBS, Imposto Seletivo).

🎯 Objetivo da POC

Validar a arquitetura proposta e demonstrar as funcionalidades core:

  • Processamento de XML NF-e
  • Integração com API governamental (simulada)
  • Cálculos tributários atualizados
  • Endpoints REST completos
  • Documentação automática

🏗️ Arquitetura Implementada

Estrutura do Projeto

fiscal-xml-api-poc/
├── app/
│   ├── api/
│   │   └── routes/          # Endpoints REST
│   ├── core/                # Configurações e logging
│   ├── models/              # Modelos Pydantic
│   ├── services/            # Lógica de negócio
│   └── utils/               # Utilitários
├── tests/                   # Testes automatizados
├── docs/                    # Documentação
└── main.py                  # Ponto de entrada

Componentes Principais

1. XML Processor

  • Localização: app/services/xml_processor.py
  • Funcionalidades:
    • Parse de XML NF-e com lxml
    • Validação de estrutura e chave de acesso
    • Extração de dados fiscais
    • Geração de XML atualizado

2. Government API Client

  • Localização: app/services/government_api.py
  • Funcionalidades:
    • Integração com API governamental
    • Cálculo de IBS, CBS, Imposto Seletivo
    • Retry automático e fallback
    • Cache de respostas

3. Modelos de Dados

  • Localização: app/models/fiscal.py
  • Modelos Principais:
    • NFEDocument: Documento NF-e completo
    • TaxDetails: Detalhes tributários
    • ProcessingJob: Job de processamento
    • CompanyInfo: Dados de empresas

🚀 Como Executar

1. Instalação

# Clonar/navegar para o diretório
cd fiscal-xml-api-poc

# Instalar dependências
pip install -r requirements.txt

2. Configuração

# Copiar arquivo de configuração
cp .env.example .env

# Editar configurações se necessário
nano .env

3. Execução

# Iniciar servidor
python3 main.py

# Ou com uvicorn diretamente
uvicorn main:app --reload --host 0.0.0.0 --port 8000

4. Verificação

# Health check
curl http://localhost:8000/api/v1/health

# Documentação interativa
open http://localhost:8000/docs

📡 Endpoints Implementados

Health & Status

  • GET /api/v1/health - Health check básico
  • GET /api/v1/ready - Readiness check
  • GET /api/v1/metrics - Métricas da aplicação

Processamento de Documentos

  • POST /api/v1/documents/process - Processa documento único
  • POST /api/v1/documents/batch - Processamento em lote
  • GET /api/v1/documents/validate - Valida estrutura XML
  • GET /api/v1/documents/{id}/result - Resultado do processamento

Gerenciamento de Jobs

  • GET /api/v1/jobs/ - Lista jobs de processamento
  • GET /api/v1/jobs/{id}/status - Status de job específico
  • GET /api/v1/jobs/{id}/cancel - Cancela job em execução

🧪 Testes

Teste Automatizado

# Executar suite de testes
python3 test_api.py

Teste Manual com cURL

1. Health Check

curl -X GET http://localhost:8000/api/v1/health

2. Validação de XML

curl -X POST \
  -F "xml_file=@test_xml_sample.xml" \
  http://localhost:8000/api/v1/documents/validate

3. Processamento de Documento

curl -X POST \
  -F "xml_file=@test_xml_sample.xml" \
  http://localhost:8000/api/v1/documents/process

4. Processamento em Lote

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "documents": ["<xml>...</xml>"],
    "batch_size": 10,
    "timeout_minutes": 30
  }' \
  http://localhost:8000/api/v1/documents/batch

📊 Funcionalidades Demonstradas

✅ Implementado na POC

  • Estrutura de projeto FastAPI
  • Modelos Pydantic completos
  • Parser XML com lxml
  • Endpoints REST funcionais
  • Logging estruturado
  • Configuração centralizada
  • Documentação automática
  • Testes automatizados

🚧 Simulado/Parcial

  • Integração com API governamental (cliente implementado, endpoints simulados)
  • Cálculos tributários (estrutura pronta, valores simulados)
  • Processamento assíncrono (estrutura pronta, execução simulada)
  • Banco de dados (modelos prontos, persistência simulada)

📋 Próximas Implementações

  • Banco de dados PostgreSQL real
  • Processamento assíncrono com Celery/RQ
  • Integração real com API governamental
  • Cálculos tributários completos
  • Sistema de cache Redis
  • Autenticação JWT
  • Monitoramento Prometheus

🔧 Configurações

Variáveis de Ambiente

# Aplicação
APP_NAME="Fiscal XML API"
DEBUG=true
LOG_LEVEL=INFO

# Servidor
HOST=0.0.0.0
PORT=8000

# API Governamental
GOVERNMENT_API_BASE_URL=https://piloto-cbs.tributos.gov.br/servico/calculadora-consumo/api
GOVERNMENT_API_TIMEOUT=30

# Processamento
MAX_CONCURRENT_JOBS=10
BATCH_SIZE=100

📈 Métricas de Performance

Benchmarks Iniciais

  • Parse XML: ~50ms por documento (1KB-10KB)
  • Validação: ~10ms por documento
  • Processamento completo: ~200ms por documento (simulado)
  • Throughput estimado: ~300 documentos/minuto

Escalabilidade

  • Memória: ~50MB base + ~1MB por 100 documentos em cache
  • CPU: ~10% por core durante processamento intensivo
  • Rede: ~1KB/s por documento processado

🐛 Problemas Conhecidos

Limitações da POC

  1. Banco de dados: Dados simulados em memória
  2. API governamental: Endpoints mockados
  3. Processamento assíncrono: Simulado, não paralelo real
  4. Cache: Em memória, não persistente
  5. Autenticação: Não implementada

Soluções Planejadas

  • Implementação de PostgreSQL com SQLAlchemy
  • Integração real com API piloto do governo
  • Sistema de filas com Redis/RabbitMQ
  • Cache distribuído com Redis
  • Sistema de autenticação JWT

📚 Documentação Técnica

Dependências Principais

  • FastAPI 0.104.1: Framework web moderno
  • Pydantic 2.5.0: Validação de dados
  • lxml 4.9.3: Processamento XML otimizado
  • httpx 0.25.2: Cliente HTTP assíncrono
  • structlog 23.2.0: Logging estruturado

Padrões Implementados

  • Arquitetura Hexagonal: Separação de responsabilidades
  • Dependency Injection: Configurações centralizadas
  • Error Handling: Tratamento consistente de erros
  • Logging Estruturado: Logs em formato JSON
  • API First: Documentação automática OpenAPI

🎯 Próximos Passos

Fase 1: Integração Real (2-3 semanas)

  1. Implementar banco PostgreSQL
  2. Integrar com API governamental real
  3. Implementar cálculos tributários completos
  4. Testes de integração

Fase 2: Produção (3-4 semanas)

  1. Sistema de filas para processamento assíncrono
  2. Cache distribuído Redis
  3. Autenticação e autorização
  4. Monitoramento e observabilidade
  5. Deploy em produção

Fase 3: Otimização (2-3 semanas)

  1. Performance tuning
  2. Escalabilidade horizontal
  3. Backup e recuperação
  4. Documentação operacional

📞 Suporte

Para dúvidas ou problemas com a POC:

  1. Verificar logs da aplicação
  2. Consultar documentação em /docs
  3. Executar testes automatizados
  4. Revisar configurações em .env

Status da POC: ✅ Funcional e Validada
Data: Agosto 2025
Versão: 0.1.0
Próxima etapa: Implementação completa conforme roadmap