projeto-aprovacao-pedidos/COMECE_AQUI.md

🚀 GUIA RÁPIDO - Primeiros Passos

⚡ Início Rápido (5 minutos)

1️⃣ Instalar Dependências

pip install -r requirements.txt

2️⃣ Configurar Token da API

Na raiz do projeto, edite o arquivo .env:

# 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

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

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:

{
  "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!

# 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

# 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

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 - Documentação técnica completa
• 📘 IMPLEMENTACAO_RESUMO.md - O que foi implementado
• 🧪 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:

python test_api_integration.py
python manage.py runserver

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

Boa sorte! 🎉