> ## Documentation Index
> Fetch the complete documentation index at: https://docs.validatech.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Validação Automática de NFe

> Automatize a validação de NFe recebidas de fornecedores e parceiros

## Visão Geral

A validação automática de NFe é um processo essencial para empresas que recebem grandes volumes de notas fiscais de fornecedores. Com a ValidaNFe, você pode automatizar completamente este processo, garantindo a autenticidade e integridade das notas recebidas.

<Card title="Benefícios Principais">
  * **Redução de 95% no tempo** de validação manual
  * **Detecção automática** de NFe fraudulentas ou inválidas
  * **Compliance fiscal** garantido
  * **Integração transparente** com sistemas ERP e contábeis
</Card>

## Como Funciona

<Steps>
  <Step title="Recebimento da NFe">
    Sua aplicação recebe NFe de fornecedores via email, upload ou API
  </Step>

  <Step title="Extração da Chave">
    Sistema extrai automaticamente a chave de acesso da NFe
  </Step>

  <Step title="Validação na Receita">
    ValidaNFe consulta status na base oficial da Receita Federal
  </Step>

  <Step title="Análise de Integridade">
    Verificação de dados, impostos e conformidade fiscal
  </Step>

  <Step title="Notificação de Resultado">
    Sistema recebe resultado via webhook ou polling
  </Step>
</Steps>

## Implementação Prática

### 1. Setup do Sistema de Validação

```javascript theme={null}
import { ValidaNFeSDK } from 'validanfe-sdk';

class ValidadorNFe {
  constructor() {
    this.validanfe = new ValidaNFeSDK({
      apiKey: process.env.VALIDANFE_API_KEY
    });
  }

  async validarNFe(chaveNFe, xmlContent) {
    try {
      // Consulta status na Receita Federal
      const statusReceita = await this.validanfe.nfe.consultar({
        chave: chaveNFe,
        tipo: 'completa'
      });

      // Validações adicionais
      const validacoes = await this.executarValidacoes(statusReceita, xmlContent);
      
      return {
        status: 'validada',
        resultado_receita: statusReceita,
        validacoes: validacoes,
        timestamp: new Date().toISOString()
      };
      
    } catch (error) {
      return {
        status: 'erro',
        erro: error.message,
        timestamp: new Date().toISOString()
      };
    }
  }

  async executarValidacoes(nfeData, xmlContent) {
    const validacoes = [];
    
    // Validação 1: Status na Receita
    if (nfeData.status !== 'autorizada') {
      validacoes.push({
        tipo: 'status_receita',
        resultado: 'reprovado',
        mensagem: `NFe não autorizada: ${nfeData.status}`
      });
    }

    // Validação 2: Integridade do XML
    if (!this.validarIntegridadeXML(xmlContent, nfeData)) {
      validacoes.push({
        tipo: 'integridade_xml',
        resultado: 'reprovado',
        mensagem: 'Dados do XML não conferem com a Receita'
      });
    }

    // Validação 3: CNPJ do Emitente
    if (!await this.validarCNPJEmitente(nfeData.emitente.cnpj)) {
      validacoes.push({
        tipo: 'cnpj_emitente',
        resultado: 'reprovado',
        mensagem: 'CNPJ do emitente inválido ou suspeito'
      });
    }

    return validacoes;
  }
}
```

### 2. Processamento em Lote

```javascript theme={null}
class ProcessadorLoteNFe {
  constructor() {
    this.validador = new ValidadorNFe();
    this.filaProcessamento = [];
  }

  async adicionarNFe(nfeData) {
    this.filaProcessamento.push({
      id: nfeData.id,
      chave: nfeData.chave,
      xml: nfeData.xml,
      fornecedor: nfeData.fornecedor,
      adicionado_em: new Date()
    });

    // Processar se fila atingir tamanho limite
    if (this.filaProcessamento.length >= 10) {
      await this.processarLote();
    }
  }

  async processarLote() {
    const lote = this.filaProcessamento.splice(0, 10);
    
    console.log(`Processando lote de ${lote.length} NFe...`);

    // Processar em paralelo para performance
    const promessas = lote.map(async (nfe) => {
      const resultado = await this.validador.validarNFe(nfe.chave, nfe.xml);
      
      return {
        nfe_id: nfe.id,
        chave: nfe.chave,
        fornecedor: nfe.fornecedor,
        resultado: resultado,
        processado_em: new Date()
      };
    });

    const resultados = await Promise.all(promessas);

    // Salvar resultados no banco
    await this.salvarResultados(resultados);
    
    // Notificar equipe sobre reprovações
    await this.notificarReprovacoes(resultados);
  }

  async notificarReprovacoes(resultados) {
    const reprovadas = resultados.filter(r => 
      r.resultado.status === 'erro' || 
      r.resultado.validacoes?.some(v => v.resultado === 'reprovado')
    );

    if (reprovadas.length > 0) {
      await this.enviarAlertaEquipe(reprovadas);
    }
  }
}
```

### 3. Integração com Webhook

```javascript theme={null}
// Endpoint para receber webhooks da ValidaNFe
app.post('/webhook/validanfe', async (req, res) => {
  const { evento, dados } = req.body;

  switch (evento) {
    case 'nfe.consulta.concluida':
      await processarConsultaConcluida(dados);
      break;
      
    case 'nfe.consulta.erro':
      await processarErroConsulta(dados);
      break;
  }

  res.status(200).send('OK');
});

async function processarConsultaConcluida(dados) {
  // Atualizar status no banco
  await database.nfe.update({
    chave: dados.chave_nfe
  }, {
    status_receita: dados.status,
    dados_receita: dados,
    validado_em: new Date()
  });

  // Continuar fluxo de validação
  const nfe = await database.nfe.findOne({ chave: dados.chave_nfe });
  const validacoes = await executarValidacoesAdicionais(nfe);
  
  if (validacoes.aprovado) {
    await aprovarNFe(nfe);
  } else {
    await reprovarNFe(nfe, validacoes.motivos);
  }
}
```

## Casos de Uso Avançados

### Validação por Categorias

<Tabs>
  <Tab title="Materiais de Construção">
    ```javascript theme={null}
    class ValidadorMateriais extends ValidadorNFe {
      async validarEspecifica(nfeData) {
        const validacoes = await super.executarValidacoes(nfeData);
        
        // Validações específicas para materiais
        if (!this.validarNCM(nfeData.produtos)) {
          validacoes.push({
            tipo: 'ncm_materiais',
            resultado: 'reprovado',
            mensagem: 'NCM não compatível com materiais de construção'
          });
        }
        
        if (!this.validarICMS(nfeData.impostos)) {
          validacoes.push({
            tipo: 'icms_materiais',
            resultado: 'reprovado',
            mensagem: 'Alíquota de ICMS incorreta para materiais'
          });
        }
        
        return validacoes;
      }
    }
    ```
  </Tab>

  <Tab title="Serviços">
    ```javascript theme={null}
    class ValidadorServicos extends ValidadorNFe {
      async validarEspecifica(nfeData) {
        const validacoes = await super.executarValidacoes(nfeData);
        
        // Validações específicas para serviços
        if (!this.validarISS(nfeData.impostos)) {
          validacoes.push({
            tipo: 'iss_servicos',
            resultado: 'reprovado',
            mensagem: 'ISS não calculado corretamente'
          });
        }
        
        if (!this.validarMunicipioPrestacao(nfeData)) {
          validacoes.push({
            tipo: 'municipio_prestacao',
            resultado: 'reprovado',
            mensagem: 'Município de prestação incorreto'
          });
        }
        
        return validacoes;
      }
    }
    ```
  </Tab>
</Tabs>

### Dashboard de Monitoramento

```javascript theme={null}
// API para dashboard de validações
app.get('/api/dashboard/validacoes', async (req, res) => {
  const stats = await database.validacoes.aggregate([
    {
      $match: {
        processado_em: {
          $gte: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000) // 30 dias
        }
      }
    },
    {
      $group: {
        _id: '$status',
        count: { $sum: 1 },
        valor_total: { $sum: '$valor_nfe' }
      }
    }
  ]);

  const fornecedoresProblematicos = await database.validacoes.aggregate([
    {
      $match: {
        'resultado.status': 'erro',
        processado_em: {
          $gte: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000) // 7 dias
        }
      }
    },
    {
      $group: {
        _id: '$fornecedor',
        erros: { $sum: 1 }
      }
    },
    { $sort: { erros: -1 } },
    { $limit: 10 }
  ]);

  res.json({
    estatisticas: stats,
    fornecedores_problematicos: fornecedoresProblematicos,
    ultima_atualizacao: new Date()
  });
});
```

## Benefícios Mensuráveis

<CardGroup cols={2}>
  <Card title="Redução de Tempo">
    **95% menos tempo** de validação manual

    * Antes: 5-10 minutos por NFe
    * Depois: 10-30 segundos automatizados
  </Card>

  <Card title="Detecção de Fraudes">
    **99.8% de precisão** na detecção de NFe fraudulentas

    * Validação cruzada com Receita Federal
    * Análise de padrões suspeitos
  </Card>

  <Card title="Compliance Fiscal">
    **100% de conformidade** com regulamentações

    * Validação automática de impostos
    * Verificação de regras tributárias
  </Card>

  <Card title="ROI">
    **Retorno em 3 meses** para empresas com 500+ NFe/mês

    * Redução de custos operacionais
    * Eliminação de multas fiscais
  </Card>
</CardGroup>

## Próximos Passos

<Steps>
  <Step title="Configurar Ambiente">
    Configure sua conta ValidaNFe e obtenha as credenciais da API
  </Step>

  <Step title="Implementar Validador">
    Use nossos exemplos de código para implementar o sistema
  </Step>

  <Step title="Configurar Webhooks">
    Configure notificações automáticas para agilizar o processo
  </Step>

  <Step title="Testar em Homologação">
    Teste com NFe reais em ambiente controlado
  </Step>

  <Step title="Deploy em Produção">
    Coloque o sistema em produção com monitoramento
  </Step>
</Steps>

<Card title="Precisa de Suporte na Implementação?" href="mailto:suporte@validanfe.com">
  Nossa equipe técnica pode ajudar na configuração e otimização do seu sistema de validação
</Card>