# Guia de Integração com Sistemas Existentes

## 1. Visão Geral

Este guia descreve como integrar o Portal de Transparência com os sistemas de gestão pública existentes (orçamento, financeiro, RH, licitações, contratos, etc.) para garantir a atualização automática dos dados.

---

## 2. Arquitetura de Integração

```
┌─────────────────────────────────────────────────────────────────┐
│                    PORTAL DE TRANSPARÊNCIA                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   Frontend  │  │   Backend   │  │   API REST  │              │
│  │   (HTML/JS) │  │   (Node.js) │  │   (JSON)    │              │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
│         │                │                │                      │
│         └────────────────┴────────────────┘                      │
│                          │                                       │
│                    ┌─────┴─────┐                                 │
│                    │  ETL/ETL  │                                 │
│                    │ (Pipeline)│                                 │
│                    └─────┬─────┘                                 │
└──────────────────────────┼───────────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│  SIAFI/SIAFIC │  │  SIGPLAN/     │  │  Sistema de   │
│  (Orçamento)   │  │  SIGTO        │  │  RH           │
└───────────────┘  └───────────────┘  └───────────────┘
        │                  │                  │
        ▼                  ▼                  ▼
┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│  Sistema de   │  │  Sistema de   │  │  Sistema de   │
│  Licitações   │  │  Contratos    │  │  Obras        │
└───────────────┘  └───────────────┘  └───────────────┘
```

---

## 3. Integrações por Dimensão

### 3.1 Receita (SIAFI/SIAFIC)

**Fonte de dados:** SIAFI (Sistema Integrado de Administração Financeira)

**Integração:**
```python
# Exemplo de script ETL para receita
import requests
from datetime import datetime

def extrair_receita_siafi(ano, mes):
    """Extrai dados de receita do SIAFI"""
    url = f"https://siafi.gov.br/api/receita?ano={ano}&mes={mes}"
    response = requests.get(url, headers={"Authorization": f"Bearer {TOKEN}"})
    return response.json()

def transformar_receita(dados):
    """Transforma dados para o formato do portal"""
    return {
        "ano": dados["ano"],
        "mes": dados["mes"],
        "previsao": dados["valor_previsto"],
        "realizada": dados["valor_realizado"],
        "classificacao": {
            "categoria_economica": dados["categoria"],
            "origem": dados["origem"],
            "especie": dados["especie"],
            "desdobramento": dados["desdobramento"]
        }
    }

def carregar_receita(dados_transformados):
    """Carrega dados no banco do portal"""
    # Inserir/atualizar no banco de dados
    pass

# Executar ETL
for ano in [2023, 2024, 2025]:
    for mes in range(1, 13):
        dados = extrair_receita_siafi(ano, mes)
        dados_transformados = transformar_receita(dados)
        carregar_receita(dados_transformados)
```

**Frequência de atualização:** Diária (após fechamento do dia)

---

### 3.2 Despesa (SIAFI/SIAFIC)

**Fonte de dados:** SIAFI

**Integração:**
```python
def extrair_despesa_siafi(ano, mes):
    """Extrai dados de despesa do SIAFI"""
    url = f"https://siafi.gov.br/api/despesa?ano={ano}&mes={mes}"
    response = requests.get(url, headers={"Authorization": f"Bearer {TOKEN}"})
    return response.json()

def extrair_empenhos(ano, mes):
    """Extrai empenhos detalhados"""
    url = f"https://siafi.gov.br/api/empenhos?ano={ano}&mes={mes}"
    response = requests.get(url, headers={"Authorization": f"Bearer {TOKEN}"})
    return response.json()
```

**Campos obrigatórios para empenhos:**
- Número do empenho
- Beneficiário (nome/CPF/CNPJ)
- Valor
- Objeto (bem/serviço)
- Modalidade e número do procedimento licitatório

---

### 3.3 Recursos Humanos (Sistema de RH)

**Fonte de dados:** Sistema de RH (SIAPE, SIGPE, etc.)

**Integração:**
```python
def extrair_servidores():
    """Extrai relação de servidores"""
    url = "https://rh.gov.br/api/servidores"
    response = requests.get(url, headers={"Authorization": f"Bearer {TOKEN}"})
    return response.json()

def extrair_remuneracao():
    """Extrai remuneração nominal"""
    url = "https://rh.gov.br/api/remuneracao"
    response = requests.get(url, headers={"Authorization": f"Bearer {TOKEN}"})
    return response.json()
```

**Campos obrigatórios:**
- Nome completo
- Cargo/função
- Lotação
- Data de admissão
- Data de exoneração/inativação (quando aplicável)
- Carga horária
- Remuneração nominal

---

### 3.4 Licitações (Sistema de Licitações)

**Fonte de dados:** Sistema de licitações (LicitaNet, ComprasNet, etc.)

**Integração:**
```python
def extrair_licitacoes(ano):
    """Extrai relação de licitações"""
    url = f"https://licitacoes.gov.br/api/licitacoes?ano={ano}"
    response = requests.get(url, headers={"Authorization": f"Bearer {TOKEN}"})
    return response.json()

def extrair_documentos_licitacao(numero):
    """Extrai documentos de uma licitação"""
    url = f"https://licitacoes.gov.br/api/licitacoes/{numero}/documentos"
    response = requests.get(url, headers={"Authorization": f"Bearer {TOKEN}"})
    return response.json()
```

**Documentos obrigatórios:**
- Termo de referência/projeto básico
- Justificativa
- Pareceres técnicos/jurídicos
- Orçamento/formação de preço
- Edital e anexos
- Atas de sessões
- Impugnações/recursos
- Termos de adjudicação e homologação

---

### 3.5 Contratos (Sistema de Contratos)

**Fonte de dados:** Sistema de contratos

**Integração:**
```python
def extrair_contratos(ano):
    """Extrai relação de contratos"""
    url = f"https://contratos.gov.br/api/contratos?ano={ano}"
    response = requests.get(url, headers={"Authorization": f"Bearer {TOKEN}"})
    return response.json()

def extrair_fiscais_contrato(numero):
    """Extrais fiscais de contrato"""
    url = f"https://contratos.gov.br/api/contratos/{numero}/fiscals"
    response = requests.get(url, headers={"Authorization": f"Bearer {TOKEN}"})
    return response.json()
```

---

### 3.6 Obras (Sistema de Obras)

**Fonte de dados:** Sistema de obras

**Integração:**
```python
def extrair_obras():
    """Extrai informações sobre obras"""
    url = "https://obras.gov.br/api/obras"
    response = requests.get(url, headers={"Authorization": f"Bearer {TOKEN}"})
    return response.json()

def extrair_quantitativos_obra(id_obra):
    """Extrai quantitativos de uma obra"""
    url = f"https://obras.gov.br/api/obras/{id_obra}/quantitativos"
    response = requests.get(url, headers={"Authorization": f"Bearer {TOKEN}"})
    return response.json()
```

---

### 3.7 SIC (Sistema de Ouvidoria/Acesso à Informação)

**Fonte de dados:** Fala.BR ou sistema próprio

**Integração:**
```python
def extrair_relatorio_estatistico(ano):
    """Extrai relatório estatístico do SIC"""
    url = f"https://falabr.gov.br/api/relatorio?ano={ano}"
    response = requests.get(url, headers={"Authorization": f"Bearer {TOKEN}"})
    return response.json()
```

---

## 4. Tecnologias Recomendadas

### 4.1 Pipeline ETL

| Tecnologia | Uso |
|---|---|
| **Apache Airflow** | Orquestração de pipelines |
| **Python + Pandas** | Transformação de dados |
| **Apache Kafka** | Streaming de dados (tempo real) |
| **dbt (data build tool)** | Transformação de dados analytics |
| **Cron jobs** | Agendamento simples |

### 4.2 Banco de Dados

| Tipo | Tecnologia | Uso |
|---|---|---|
| Relacional | PostgreSQL | Dados estruturados |
| Documentos | MongoDB | Documentos não estruturados |
| Cache | Redis | Cache de consultas frequentes |
| Full-text | Elasticsearch | Pesquisa full-text |
| Data Warehouse | BigQuery/Redshift | Analytics |

### 4.3 Backend

| Tecnologia | Uso |
|---|---|
| Node.js/Express | API REST |
| Python/FastAPI | API REST + ETL |
| Java/Spring Boot | Enterprise |

### 4.4 Frontend

| Tecnologia | Uso |
|---|---|
| React/Vue.js | SPA |
| Next.js/Nuxt.js | SSR + SEO |
| Tailwind CSS | Styling |

---

## 5. Fluxo de Dados

### 5.1 Dados em Tempo Real

```
Sistema de origem → Kafka → Stream processing → Banco de dados → Portal
```

**Exemplos:** Receita, despesa (atualização diária)

### 5.2 Dados em Lote

```
Sistema de origem → ETL agendado → Transformação → Banco de dados → Portal
```

**Exemplos:** Servidores, contratos, licitações (atualização diária/semanal)

### 5.3 Dados Estáticos

```
Documento → Upload manual → Validação → Banco de documentos → Portal
```

**Exemplos:** PPA, LDO, LOA, relatórios

---

## 6. Monitoramento

### 6.1 Logs

```json
{
  "timestamp": "2026-01-15T10:30:00Z",
  "pipeline": "receita_etl",
  "status": "success",
  "registros_processados": 1500,
  "tempo_execucao": "2.5s",
  "erros": 0
}
```

### 6.2 Alertas

| Condição | Ação |
|---|---|
| Pipeline falhou | Enviar e-mail/SMS |
| Dados não atualizados em > 24h | Enviar alerta |
| Erro de validação | Registrar log + alertar |
| Performance degradada | Escalar recursos |

### 6.3 Dashboard

- Status dos pipelines
- Última atualização de cada dimensão
- Volume de dados processados
- Erros e alertas

---

## 7. Segurança

### 7.1 Autenticação

```python
# Usar OAuth2 ou API keys
headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "X-API-Key": API_KEY
}
```

### 7.2 Criptografia

- Dados em trânsito: TLS 1.3
- Dados em repouso: AES-256
- Senhas: bcrypt/Argon2

### 7.3 Auditoria

- Log de todas as operações de ETL
- Log de acessos à API
- Log de alterações em dados sensíveis

---

## 8. Checklist de Integração

- [ ] Mapear todas as fontes de dados
- [ ] Definir frequência de atualização por dimensão
- [ ] Implementar pipelines ETL
- [ ] Configurar banco de dados
- [ ] Implementar API REST
- [ ] Implementar cache
- [ ] Configurar monitoramento
- [ ] Testar fluxos completos
- [ ] Documentar integrações
- [ ] Treinar equipe de manutenção