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

# Importação (Funcional)

> Gestão de Importação e NF-e

# Gestão de Importação e NF-e (OmniDom)

### 📌 Visão Geral

* **Nome da funcionalidade:** Importação de XML e Planilhas
* **Objetivo principal:** Permitir a importação ágil e a vinculação de produtos e notas fiscais de entrada (XML/XLSX/CSV) diretamente para o estoque, garantindo a rastreabilidade e a alimentação do inventário.
* **Perfil de usuário:** Gerente de Estoque, Analista de Recebimento, Administrador do Sistema.
* **Pré-requisitos de acesso:** Permissões de escrita no módulo de inventário e acesso à tela de Importação.

***

### 🔢 Passo a Passo

**Passo 1: Upload do Arquivo Base**

* O usuário acessa a aba "Via Arquivo" no módulo de Importação (podendo ser para Produtos ou Anúncios).
* O usuário seleciona ou arrasta o arquivo (ex: XML de NF-e).
* Resultado esperado: Início do processamento visual.

**Passo 2: Acompanhamento no Histórico**

* O usuário é levado à listagem de histórico.
* O arquivo aparece com um status (ex: Processando).
* Resultado esperado: O sistema conclui a leitura das tags do XML e habilita a opção de "Revisar" ou "Confirmar".

**Passo 3: Revisão (Modal de Conciliação)**

* O usuário clica para revisar o arquivo recebido.
* O modal principal de conciliação é aberto.
* **Ação obrigatória:** O usuário precisa selecionar o "Depósito" legal/físico de destino para as mercadorias.
* O usuário visualiza cada linha (XML item) e precisa decidir o destino:
  * **Criar Novo:** Gera um novo SKU no banco da OmniDom.
  * **Vincular a SKU Existente:** O usuário clica e busca um produto já existente na base para somar o estoque.
  * **Ignorar:** O item da nota não será importado (ex: uso de insumos internos).

**Passo 4: Ações em Lote e Confirmação**

* O usuário pode selecionar vários itens e aplicar "Criar Tudo" ou "Ignorar Tudo".
* O usuário finaliza clicando em "Confirmar Importação".
* Resultado esperado: O back-end absorve a nota fiscal e atualiza saldos de estoque e custos para os produtos. Um *toast* de sucesso é exibido.

***

### 📋 Regras de Negócio

* **RN01: Obrigatoriedade de Depósito Destino**
  * **Descrição:** Nenhuma mercadoria pode entrar na conta contábil/estoque virtual sem um ponto físico de destino claro.
  * **Condição:** Dentro do modal de conciliação.
  * **Comportamento:** O botão de finalização permanece desabilitado ou acusa erro se o dropdown "Selecionar Depósito" estiver vazio.
* **RN02: Busca Reativa para Vinculação**
  * **Descrição:** Motor de busca ao tentar vincular SKU.
  * **Condição:** O usuário clica em "Vincular" no item importado.
  * **Comportamento:** O motor consulta a base viva de produtos pelo nome ou código de barras e lista para clique direto.
* **RN03: Processamento Assíncrono**
  * **Descrição:** Para não travar a experiência, arquivos grandes geram *jobs* em segundo plano.
  * **Condição:** Logo após o Upload.
  * **Comportamento:** O histórico ganha uma linha pendente e não bloqueia a interface do usuário.

***

### ✅ Critérios de Aceitação

* **CA01: Vinculação de Produto Existente**
  * **Dado que:** o usuário subiu uma NF-e contendo uma escova já vendida pela loja.
  * **Quando:** ele escolhe "Vincular", pesquisa "Escova" e confirma.
  * **Então:** o sistema amarra as entradas deste XML especificamente no ID daquele produto sem duplicar o cadastro principal.
* **CA02: Confirmação e Sucesso**
  * **Dado que:** todos os itens estão resolvidos (Criar, Vincular ou Ignorar) e o Depósito foi escolhido.
  * **Quando:** o usuário confirma o lote.
  * **Então:** a mensagem de alerta verde é lançada confirmando o fim do fluxo e injetando quantidades no estoque correspondente.

***

### ⚠️ Pontos de Atenção

* Ao longo da importação, certificar que a opção "Ignorar" não invalide fechamentos contábeis a depender da integração fiscal ERP, pois a mercadoria fisicamente chegou.

***

### 💡 Dicas para o Usuário

* Para notas fiscais de fabricantes com +100 itens inéditos, utilize o botão "Criar Tudo" na ação em lote após selecionar uma linha de produtos. Isso economiza minutos de cliques.