projeto-aprovacao-pedidos/INTEGRACAO_API.md

Guia de Integração da API de Suprimentos

📋 Visão Geral

Este projeto integra dados da API de Suprimentos com os dados do SQL Server. A integração faz um join automático por PDV e SKU, mapeando a quantidade da API para o campo "sugestão Analista".

🔐 Configuração Segura do Token

1. Arquivo .env (NUNCA commit ao Git!)

O token da API é armazenado de forma segura em um arquivo .env na raiz do projeto:

API_SUPRIMENTOS_TOKEN=seu_token_jwt_aqui
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

2. Protegendo o Token

IMPORTANTE: Adicione o arquivo .env ao .gitignore para nunca expor o token:

# .gitignore
.env
*.pyc
__pycache__/
db.sqlite3

3. Usando o Token em Produção

Para produção, configure as variáveis de ambiente no servidor/container:

# Docker Compose
environment:
  API_SUPRIMENTOS_TOKEN: ${API_SUPRIMENTOS_TOKEN}

# Servidor Linux
export API_SUPRIMENTOS_TOKEN="seu_token_aqui"

🔄 Como Funciona a Integração

Fluxo de Dados

┌─────────────────────────────────────────────────────┐
│  SQL Server                                         │
│  (estoque_mar_historico + draft_historico)         │
│  - PDV, SKU, Estoque, Trânsito, etc.               │
└────────────────────┬────────────────────────────────┘
                     │
                     ▼
        ┌────────────────────────┐
        │ views.get_pivot_data() │
        │ - Busca dados SQL      │
        │ - Busca dados API      │
        │ - Faz JOIN             │
        └────────────────┬───────┘
                         │
        ┌────────────────────────┐
        │ API de Suprimentos     │
        │ (com autenticação JWT) │
        │ - PDV, SKU, quantidade │
        └────────────┬───────────┘
                     │
                     ▼
        ┌────────────────────────┐
        │ Dados Mesclados        │
        │ sugestao_analista =    │
        │ quantidade (da API)    │
        └────────────────────────┘

Funções Principais

1. get_api_suprimentos_data()

• Busca dados da API com token JWT
• Retorna None se falhar (não quebra a página)
• Timeout de 30 segundos

2. merge_api_with_sql_data()

• Faz JOIN por (PDV, SKU)
• Mapeia quantidade → sugestao_analista
• Adiciona campo dados_api_presentes (true/false)

3. get_pivot_data()

• Combinação de dados SQL + API
• Retorna api_integrated: true se dados foram mesclados

📊 Campos Mapeados

Tabela SQL	Campo da API	Campo Resultante
PDV	PDV	PDV (chave join)
SKU	SKU	SKU (chave join)
-	quantidade	sugestao_analista

🚀 Como Usar

Setup Inicial

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

# 2. Criar arquivo .env
cp .env.example .env
# Editar .env e adicionar seu token JWT

# 3. Executar o servidor
python manage.py runserver

Na Página

Os dados serão automaticamente mesclados ao carregar a tabela. Você verá:

• Quando API está disponível:

  • Coluna sugestao_analista preenchida com dados da API
  • Log no console: "Dados da API integrados: X registros"

• Quando API falha ou token inválido:

  • Dados do SQL Server continuam aparecendo
  • Log de erro aparece no terminal
  • Página não quebra

⚠️ Tratamento de Erros

A integração é resiliente:

✅ Se a API cair → página continua funcionando com dados do SQL
✅ Se o token expirar → backend usa dados do SQL
✅ Se PDV/SKU não matcham → campo fica null

🔍 Debug

Ver logs da integração

# No terminal do servidor
[2024-XX-XX XX:XX:XX] Dados da API integrados: 250 registros
[2024-XX-XX XX:XX:XX] Erro ao chamar API: Connection timeout

Testar a integração manualmente

# manage.py shell
from home.views import get_api_suprimentos_data
dados = get_api_suprimentos_data()
print(f"Registros obtidos: {len(dados) if dados else 'None'}")

📝 Exemplo de Resposta

{
  "status": "success",
  "data": [
    {
      "PDV": "2001",
      "Descricao_PDV": "Loja Centro",
      "SKU": "ABC123",
      "Estoque_Total": 150,
      "sugestao_analista": 45,
      "dados_api_presentes": true,
      ...
    }
  ],
  "api_integrated": true
}

🛡️ Segurança

• ✅ Token armazenado em .env (não no código)
• ✅ Arquivo .env no .gitignore
• ✅ Timeout de conexão (30s)
• ✅ Tratamento de erros silencioso
• ✅ Logs detalhados para debug
• ✅ Sem exposição de senhas no código

📞 Suporte

Se encontrar problemas:

1. Verifique se o .env existe na raiz do projeto
2. Confirme que o token JWT é válido
3. Verifique os logs no terminal do servidor
4. Teste manualmente com: python manage.py shell