194 lines
5.5 KiB
Markdown
194 lines
5.5 KiB
Markdown
# 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`
|