projeto-aprovacao-pedidos/COMECE_AQUI.md

# 🚀 GUIA RÁPIDO - Primeiros Passos

## ⚡ Início Rápido (5 minutos)

### 1️⃣ Instalar Dependências
```bash
pip install -r requirements.txt
```

### 2️⃣ Configurar Token da API
Na raiz do projeto, edite o arquivo `.env`:

```bash
# Abrir ou criar .env na raiz
# Linux/Mac:
nano .env

# Windows:
notepad .env
```

Conteúdo do arquivo:
```
API_SUPRIMENTOS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE4MDk1Mzg4NzcsInVzZXJuYW1lIjoic3VwcmltZW50b3MuZ2luc2VuZyJ9.VyQOfFKOf56_GqmECfuQ29Y5sEGtOopVS4XC-cA54DU
API_SUPRIMENTOS_DETALHE_URL=https://api.grupoginseng.com.br/api/suprimentos_detalhepedido?limit=50000&status=pendente
API_SUPRIMENTOS_IMPLANTACAO_URL=https://api.grupoginseng.com.br/api/vw_suprimentos_implantacaopedido?limit=50000
```

### 3️⃣ Testar a Integração
```bash
python test_api_integration.py
```

Você deve ver:
```
🧪 TESTES DE INTEGRAÇÃO COM API DE SUPRIMENTOS

✓ PASSOU: Conexão com API
✓ PASSOU: Merge de dados
✓ PASSOU: Integração completa

🎉 Todos os testes passaram! Integração pronta para usar.
```

### 4️⃣ Rodar o Servidor
```bash
python manage.py runserver
```

Acesse: `http://localhost:8000/home/`

## 📊 O que mudou?

### Tabela agora mostra:
- **PDV** (de ambas fontes)
- **SKU** (de ambas fontes)
- **Estoque** (do SQL)
- **Trânsito** (do SQL)
- **Pendente** (do SQL)
- **sugestao_analista** ← **NOVO! (da API)**

### Novos Campos no JSON:
```json
{
  "PDV": "2001",
  "SKU": "ABC123",
  "sugestao_analista": 45,           // ← DA API
  "dados_api_presentes": true,        // ← FLAG
  "Estoque_Total": 150,              // Do SQL
  ...
}
```

## 🔐 Proteção do Token

✅ **Arquivo `.env` não é versionado**  
✅ **Arquivo `.env.example` documenta os campos**  
✅ **Token nunca aparece no código**  

**IMPORTANTE:** Nunca faça commit do arquivo `.env`!

```bash
# Verificar se está protegido:
cat .gitignore | grep .env
# Deve mostrar: .env
```

## ❌ Resolução de Problemas

### Erro: "Token não configurado"
```
❌ ERRO: Token não configurado no .env
```
**Solução:** Crie/edite o arquivo `.env` na raiz do projeto

### Erro: "Falha ao conectar com a API"
```
❌ Falha ao conectar com a API (verifique token e conexão de rede)
```
**Solução:** 
- Verifique se o token é válido
- Teste a conexão: `ping api.grupoginseng.com.br`
- Verifique firewall/VPN

### Dados não aparecem
```
⚠️ API retornou lista vazia
```
**Solução:**
- Verifique se há dados pendentes na API
- Confirme PDV e SKU estão corretos

## 📱 Monitorando a Integração

### Ver logs no terminal
```bash
# Quando você roda: python manage.py runserver

[2024-XX-XX XX:XX:XX] Dados da API integrados: 250 registros
[2024-XX-XX XX:XX:XX] GET /home/api/pivot-data/ 200 OK
```

### Debug no Python
```bash
python manage.py shell

# Dentro do shell:
>>> from home.views import get_api_suprimentos_data
>>> dados = get_api_suprimentos_data()
>>> print(f"Total: {len(dados) if dados else 'None'} registros")
>>> print(dados[0] if dados else "Sem dados")
```

## 📦 Arquitetura da Solução

```
┌─────────────────────────────────────────┐
│           Página Web                     │
│     /home/api/pivot-data/               │
└────────────────┬────────────────────────┘
                 │
         ┌───────▼────────┐
         │  get_pivot_data │
         └───────┬────────┘
                 │
         ┌───────┴────────────────┐
         │                        │
    ┌────▼──────┐        ┌────────▼─────┐
    │ SQL Server │        │ API Suprimentos│
    │(dados base)│        │(quantidade)    │
    └────┬──────┘        └────────┬─────┘
         │                        │
         └───────────┬────────────┘
                     │
        ┌────────────▼──────────────┐
        │ merge_api_with_sql_data() │
        │ (JOIN por PDV + SKU)      │
        └────────────┬──────────────┘
                     │
        ┌────────────▼──────────────┐
        │  Dados Combinados         │
        │  sugestao_analista = qty  │
        └───────────────────────────┘
```

## 📋 Checklist

- [ ] `.env` criado na raiz
- [ ] Token adicionado ao `.env`
- [ ] Dependências instaladas: `pip install -r requirements.txt`
- [ ] Teste passou: `python test_api_integration.py`
- [ ] Servidor rodando: `python manage.py runserver`
- [ ] Página abre: `http://localhost:8000/home/`
- [ ] Dados aparecem com "sugestao_analista"
- [ ] `.env` está no `.gitignore`

## 🎓 Referências

- 📘 [INTEGRACAO_API.md](INTEGRACAO_API.md) - Documentação técnica completa
- 📘 [IMPLEMENTACAO_RESUMO.md](IMPLEMENTACAO_RESUMO.md) - O que foi implementado
- 🧪 [test_api_integration.py](test_api_integration.py) - Script de teste

## 💬 Dúvidas Frequentes

**P: Preciso reiniciar o servidor a cada mudança do `.env`?**  
R: Sim, o Django lê as variáveis ao iniciar. Reinicie com: `Ctrl+C` e `python manage.py runserver`

**P: E se a API cair?**  
R: Site continua funcionando normalmente com dados do SQL Server.

**P: Como adicionar novo token?**  
R: Edite `.env`, reinicie servidor.

**P: Posso compartilhar o `.env` com a equipe?**  
R: Não! Use variáveis de ambiente por servidor. Cada dev tem seu `.env` local.

## 🚀 Próximo Passo

Você está pronto! Execute:

```bash
python test_api_integration.py
python manage.py runserver
```

E acesse: **http://localhost:8000/home/**

Boa sorte! 🎉