# Módulo de Entrada de Notas Fiscais - Documentação

## Visão Geral

O módulo de Entrada de Notas Fiscais permite cadastrar e processar notas fiscais de entrada (compras) de 4 formas diferentes, com integração completa com os módulos de Compras, Estoque e Financeiro.

## Funcionalidades

### 1. Entrada Manual
- Digitação completa de todos os dados da nota fiscal
- Campos obrigatórios: chave de acesso, número, série, emitente, destinatário, valores
- Validação de chave de acesso (44 dígitos)
- Criação automática de fornecedor se não existir

### 2. Consulta por Chave de Acesso
- Consulta na SEFAZ usando a chave de acesso (44 dígitos)
- Extração automática de dados da nota
- Suporte a produção e homologação
- Validação de status da nota (autorizada, cancelada, denegada)

### 3. Importação de XML
- Upload de arquivo XML da nota fiscal
- Processamento automático do XML
- Extração de todos os dados: emitente, destinatário, itens, impostos
- Validação de estrutura XML

### 4. Detecção Automática
- Configuração para detectar notas emitidas contra a empresa
- Execução periódica via cron job
- Processamento automático opcional
- Criação automática de fornecedores e produtos

## Integrações

### Compras
- Criação automática de `purchase_invoices`
- Criação de `purchase_invoice_items`
- Vinculação com fornecedores

### Estoque
- Atualização automática de `products.estoque`
- Registro em `inventory_movements`
- Tipo de movimentação: `entrada_compra`

### Financeiro
- Criação automática de `contas_pagar`
- Vinculação com invoice de compra
- Data de vencimento configurável (padrão: 30 dias)

### Fornecedores
- Criação automática de fornecedor se não existir
- Busca por CNPJ
- Atualização de dados do fornecedor

### Produtos
- Mapeamento automático por código/EAN
- Mapeamento por NCM + descrição (fuzzy match)
- Mapeamento por descrição (fuzzy match)
- Criação automática de produtos (opcional)
- Atualização de preço de custo, NCM, EAN

## Instalação

### 1. Executar Migrations

As migrations são executadas automaticamente quando o módulo é ativado:

```sql
-- Tabelas criadas:
- nfe_entrada
- nfe_entrada_itens
- nfe_entrada_deteccao
```

### 2. Configurar Cron Job (Opcional)

Para detecção automática, adicione ao crontab:

```bash
# Executar a cada 15 minutos
*/15 * * * * /usr/bin/php /caminho/para/scripts/nfe-deteccao-cron.php >> /var/log/nfe-deteccao.log 2>&1
```

### 3. Configurar Webhook (Opcional)

Configure o webhook para receber notificações automáticas:

1. Acesse `/fiscal/entrada-notas`
2. Vá para a aba "Detecção Automática"
3. Configure:
   - CNPJ da empresa
   - Token do webhook (opcional, mas recomendado)
   - URL do webhook (opcional)
   - Auto-processar
   - Auto-criar fornecedor/produto

## Uso

### Entrada Manual

1. Acesse `/fiscal/entrada-notas`
2. Clique em "Manual"
3. Preencha todos os campos obrigatórios
4. Clique em "Salvar Nota"

### Consulta por Chave

1. Acesse `/fiscal/entrada-notas`
2. Clique em "Chave de Acesso"
3. Digite a chave de acesso (44 dígitos)
4. Clique em "Consultar"
5. Se encontrada, a nota será exibida e poderá ser salva

### Importação de XML

1. Acesse `/fiscal/entrada-notas`
2. Clique em "Importar XML"
3. Selecione o arquivo XML da nota fiscal
4. Clique em "Importar XML"
5. A nota será processada e salva automaticamente

### Detecção Automática

1. Acesse `/fiscal/entrada-notas`
2. Clique em "Detecção Automática"
3. Configure o CNPJ da empresa
4. Configure as opções desejadas
5. Clique em "Salvar Configuração"
6. Execute manualmente ou aguarde o cron job

## Webhook

### Endpoint

```
POST /api/fiscal/nfe-entrada/webhook
```

### Headers

```
X-Tenant-Id: <tenant_id>
X-Webhook-Token: <token> (opcional, mas recomendado)
Content-Type: application/json
```

### Payload

```json
{
  "tipo": "nfe_recebida",
  "chave_acesso": "12345678901234567890123456789012345678901234",
  "xml": "<xml_da_nota>",
  "auto_processar": true
}
```

### Tipos de Notificação

- `nfe_recebida`: Nota fiscal recebida
- `nfe_autorizada`: Nota fiscal autorizada
- `nfe_cancelada`: Nota fiscal cancelada

## Integração com SEFAZ

### Consulta por Chave

O sistema consulta a SEFAZ usando SOAP para obter o status e dados da nota fiscal.

### Endpoints por UF

O sistema suporta todos os estados brasileiros com endpoints específicos para cada SEFAZ.

### Autenticação

Em produção, é necessário certificado digital A1 ou A3 para consultas na SEFAZ.

## Mapeamento de Produtos

### Ordem de Busca

1. **Código do Produto**: Busca exata por código
2. **Código de Barras (EAN)**: Busca exata por EAN
3. **NCM + Descrição**: Fuzzy match (70% de similaridade)
4. **Descrição**: Fuzzy match (60% de similaridade)

### Criação Automática

Se `auto_criar_produto` estiver ativo, produtos não encontrados serão criados automaticamente com:
- Código gerado automaticamente
- Descrição da nota
- NCM (se disponível)
- EAN (se disponível)
- Preço de custo da nota
- Unidade de medida

## Processamento

### Fluxo de Processamento

1. **Salvar Nota**: Nota é salva com status `pendente`
2. **Processar Nota**: 
   - Cria invoice de compra
   - Atualiza estoque
   - Cria conta a pagar (opcional)
   - Atualiza status para `processada`

### Processamento Automático

Se `auto_processar` estiver ativo, notas recebidas via webhook serão processadas automaticamente.

## Segurança

### Webhook

- Validação de token (se configurado)
- Validação de tenant ID
- Logs de auditoria
- Idempotência (evita processamento duplicado)

### SEFAZ

- Certificado digital (produção)
- Validação de chave de acesso
- Tratamento de erros

## Troubleshooting

### Erro: "Chave de acesso inválida"
- Verifique se a chave tem 44 dígitos
- Remova espaços e caracteres especiais

### Erro: "XML inválido"
- Verifique se o arquivo XML está completo
- Verifique se é um XML de NFe válido

### Erro: "Erro ao consultar SEFAZ"
- Verifique conexão com internet
- Verifique se o certificado digital está configurado (produção)
- Verifique se a UF está correta

### Nota não processa automaticamente
- Verifique se `auto_processar` está ativo
- Verifique se o cron job está configurado
- Verifique os logs em `/var/log/nfe-deteccao.log`

## API Endpoints

### Listagem
- `GET /api/fiscal/nfe-entrada` - Lista notas
- `GET /api/fiscal/nfe-entrada/{id}` - Detalhes de uma nota

### Criação
- `POST /api/fiscal/nfe-entrada/manual` - Cria nota manual
- `POST /api/fiscal/nfe-entrada/importar-xml` - Importa XML
- `POST /api/fiscal/nfe-entrada/consultar-chave` - Consulta por chave

### Processamento
- `POST /api/fiscal/nfe-entrada/{id}/processar` - Processa nota

### Detecção Automática
- `GET /api/fiscal/nfe-entrada/deteccao/config` - Obtém configuração
- `POST /api/fiscal/nfe-entrada/deteccao/config` - Configura detecção
- `POST /api/fiscal/nfe-entrada/deteccao/executar` - Executa detecção

### Webhook
- `POST /api/fiscal/nfe-entrada/webhook` - Recebe webhook

## Estrutura de Dados

### nfe_entrada
- Dados básicos da nota (chave, número, série, modelo)
- Emitente e destinatário
- Valores totais e impostos
- Status e forma de entrada
- XML original

### nfe_entrada_itens
- Itens da nota fiscal
- Dados de impostos (ICMS, IPI, PIS, COFINS)
- Vinculação com produtos

### nfe_entrada_deteccao
- Configuração de detecção automática
- Estatísticas de detecção
- Configurações de webhook

## Logs e Auditoria

Todas as operações são registradas em:
- `AuditLogger`: Operações de criação, atualização, processamento
- `error_log`: Erros e exceções
- Logs de detecção automática

## Próximos Passos

1. **Integração Real com SEFAZ**: Implementar consulta real usando certificado digital
2. **Download de XML**: Implementar download automático de XML da SEFAZ
3. **Notificações por Email**: Enviar notificações por email quando notas forem detectadas
4. **Dashboard**: Criar dashboard com estatísticas de notas fiscais
5. **Relatórios**: Gerar relatórios de notas fiscais por período, fornecedor, etc.

