# 📄 Sistema de Importação XML de Nota Fiscal

## 🎯 Visão Geral

Sistema profissional e reutilizável para importação de arquivos XML de Nota Fiscal (NF-e), com extração automática de dados e preenchimento de formulários.

---

## 📁 Estrutura de Arquivos

### 1. **`/include/xml_parsers/nfe_parser.php`** (Classe Reutilizável)
Classe `NFeLimpaParser` que realiza todo o parse do XML.

**Características:**
- ✅ Suporta múltiplos formatos de XML NF-e
- ✅ Extrai dados de IDE, Emitente, Destinatário, Transporte e Itens
- ✅ Calcula totalizadores (ICMS, IPI, PIS, COFINS)
- ✅ Formata automaticamente CNPJ, CEP e datas
- ✅ Validação de estrutura XML
- ✅ Reutilizável em qualquer rotina

**Métodos Principais:**
```php
$parser = new NFeLimpaParser($xml_string_ou_path);

// Extrair todos os dados
$dados = $parser->extrair_dados();

// Validar XML
$validacao = $parser->validar();
```

**Retorno da extração:**
```php
[
    'ide' => [
        'numero' => '123456',
        'serie' => '1',
        'dhemi' => '01/12/2025',
        'natop' => 'Venda...',
        ...
    ],
    'emit' => [
        'razao_social' => 'Empresa XYZ',
        'cnpj' => '12.345.678/0001-00',
        'endereco' => [ ... ]
    ],
    'dest' => [ ... ],
    'transp' => [ ... ],
    'itens' => [ ... ],
    'total' => [ ... ],
    ...
]
```

---

### 2. **`/tms010_operacao/import_xml.php`** (Endpoint de Upload)

Arquivo que recebe o upload do XML e processa usando a classe `NFeLimpaParser`.

**Request:**
```
POST /tms010_operacao/import_xml.php
Content-Type: multipart/form-data

[arquivo: XML file]
```

**Response (Sucesso):**
```json
{
    "sucesso": true,
    "mensagem": "XML importado com sucesso",
    "dados": {
        "numero_nfe": "123456",
        "serie_nfe": "1",
        "data_emissao": "01/12/2025",
        "remetente_razao_social": "...",
        "cliente_razao_social": "...",
        "valor_total": 1500.50,
        "peso_total": 250.000,
        "quantidade_itens": 5,
        "itens": [...]
    }
}
```

**Response (Erro):**
```json
{
    "sucesso": false,
    "mensagem": "Descrição do erro"
}
```

---

### 3. **`/tms010_operacao/cad.php`** (Modal de Importação)

Adicionado modal com interface drag-and-drop para importação.

**Features:**
- 🎨 Interface bonita com zona de drop
- 📤 Suporte a drag-and-drop de arquivos
- ⚡ Upload assíncrono
- 📊 Exibição dos dados extraídos
- ✅ Preenchimento automático do formulário

---

## 🚀 Como Usar

### Em uma Tela Existente

Se você quer adicionar importação de XML em outra rotina:

```php
<?php
require('../include/xml_parsers/nfe_parser.php');

try {
    $parser = new NFeLimpaParser($_FILES['arquivo']['tmp_name']);
    $validacao = $parser->validar();
    
    if ($validacao['valido']) {
        $dados = $parser->extrair_dados();
        // Usar $dados para preencher sua tela
    }
} catch (Exception $e) {
    echo "Erro: " . $e->getMessage();
}
?>
```

### Exemplo: Integração em Outra Tela

Para reutilizar em outra rotina (ex: fro001_abastecimento):

1. **Copiar o modal** do `cad.php` da TMS010
2. **Ajustar o mapeamento** de campos conforme sua tela
3. **Reutilizar a mesma classe** `NFeLimpaParser`

---

## 🔄 Fluxo de Dados

```
[Upload XML]
     ↓
[import_xml.php]
     ↓
[NFeLimpaParser]
     ↓
[Validação]
     ↓
[Extração de Dados]
     ↓
[Formatação]
     ↓
[Retorno JSON]
     ↓
[JavaScript: Preenche Formulário]
```

---

## 📊 Campos Extraídos

### Identificação
- Número NF
- Série
- Data de Emissão
- Chave de Acesso
- Natureza da Operação

### Remetente (Origem)
- Razão Social
- Nome Fantasia
- CNPJ / IE
- Endereço completo
- CEP, Cidade, UF

### Destinatário (Cliente)
- Razão Social
- CNPJ / CPF / IE
- Endereço completo
- CEP, Cidade, UF

### Transporte
- Modo de Frete
- Transportador (CNPJ, Razão Social)
- Veículo Principal (Placa, UF)
- Reboques (múltiplos)

### Itens
- Código do Produto
- Descrição
- NCM / CFOP
- Quantidade / Unidade
- Valor Unitário / Total
- Peso Líquido / Bruto

### Totalizadores
- Base ICMS
- ICMS / ICMS ST
- IPI / PIS / COFINS
- Frete / Seguro
- Desconto / Outras Despesas
- **Valor Total**

---

## ⚙️ Validações

A classe `NFeLimpaParser` valida automaticamente:

✅ Formato XML válido
✅ Estrutura de NF-e presente
✅ Seção IDE (Identificação)
✅ Seção Emitente
✅ Chave de Acesso

---

## 🎯 Próximos Passos

### Sugestões de Implementação:

1. **Vincular Automático a Clientes/Fornecedores**
   ```php
   // Buscar cliente pelo CNPJ extraído
   SELECT * FROM dim_cliente WHERE cnpj = ?
   ```

2. **Integração com Rastreamento**
   - Extrair dados de transporte
   - Popular veículo e motorista automaticamente

3. **Histórico de Importações**
   - Guardar XMLs importados em tabela
   - Auditoria de preenchimentos automáticos

4. **Validação de Divergências**
   - Alertar se dados divergem de registros existentes

5. **Bulk Import**
   - Permitir importação de múltiplos XMLs

---

## 🐛 Troubleshooting

### "XML inválido ou mal formatado"
- Certifique-se de que o arquivo é um XML genuíno da NF-e
- Verifique se não está compactado (`.zip` ou `.rar`)

### "Chave de acesso não encontrada"
- Alguns XMLs podem ter a chave em locais diferentes
- A classe tenta múltiplas estruturas comuns

### Campos em branco
- Verificar se o XML contém os dados esperados
- Alguns campos são opcionais (nome fantasia, complemento, etc.)

---

## 📝 Exemplo de Uso Completo

```php
<?php
require('../include/xml_parsers/nfe_parser.php');

if ($_FILES['arquivo']['error'] === UPLOAD_ERR_OK) {
    try {
        $parser = new NFeLimpaParser($_FILES['arquivo']['tmp_name']);
        
        // Validar
        $validacao = $parser->validar();
        if (!$validacao['valido']) {
            die('Erro: ' . $validacao['mensagem']);
        }
        
        // Extrair
        $dados = $parser->extrair_dados();
        
        // Usar dados
        $numero_nfe = $dados['numero_nfe'];
        $cliente = $dados['dest']['razao_social'];
        $valor = $dados['total']['valor_total'];
        
        // Gravar no banco
        $query = "INSERT INTO sua_tabela (nfe, cliente, valor) VALUES ('$numero_nfe', '$cliente', $valor)";
        pg_query($bdcon, $query);
        
    } catch (Exception $e) {
        echo "Erro: " . $e->getMessage();
    }
}
?>
```

---

## 📄 Suporte

Para usar em outras telas, copie os mesmos arquivos e faça as adaptações necessárias de mapeamento de campos.

**Arquivos Reutilizáveis:**
- ✅ `nfe_parser.php` (100% reutilizável)
- ✅ `import_xml.php` (adaptável conforme necessário)
- ✅ Modal HTML (adaptável conforme necessário)

---

**Versão:** 1.0
**Data:** Dezembro 2025
**Desenvolvido para:** SAG Frota de Transporte
