# 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:

```bash
# .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:

```bash
# 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

```bash
# 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

```python
# 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

```python
# 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

```json
{
  "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`