# Executar importações cadastradas

Escolha o mapeamento de entrada, confira formatos e identidades, valide o arquivo e retome lotes sem repetir linhas concluídas.

Versão 1.1.0

**Operações → Arquivos** executa arquivos conforme mapeamentos de entrada já cadastrados. O mapeamento relaciona os nomes das colunas do arquivo aos campos do Askora; não é um registro comercial nem uma autorização para importar qualquer tipo de dado.

## Localizar o mapeamento

As abas **Operações**, **Gerenciador**, **Extensões** e **Integrações** separam os destinos. A tabela mostra **Nome**, **Página**, **Tabela de destino** e **Campos mapeados**, com oito registros por página e filtros desses quatro campos. Campos mapeados é a quantidade de correspondências configuradas, não a quantidade de linhas do arquivo.

Ative **Usar Arquivos** em **Integrações → Arquivos → Configurar** para exibir esta página em Operações. Arquivos começa desativado.

Use **Importar** na linha do mapeamento. A ação **Editar** abre sua configuração em **Integrações → Arquivos**. Não há criação, exclusão ou execução em lote de mapeamentos nessa tabela. Só aparecem mapeamentos de entrada de destinos compatíveis e disponíveis; mapeamentos de saída são utilizados na exportação em Integrações → Arquivos. Se a lista estiver vazia, confira a aba, os filtros, o destino e o cadastro do mapeamento.

## Selecionar e validar

1. [Localize o mapeamento](/spm/manual/importacoes-operacionais/#localizar-o-mapeamento) e use **Importar**.
2. Em **1. Confira a importação**, confirme nome, área e tabela. Abra **Campos esperados no arquivo** para ver cada coluna de origem, o campo correspondente e a indicação de obrigatório.
3. Em **2. Envie e configure o arquivo**, use **Selecionar arquivo**. A extensão reconhecida ajusta o formato; confira **Formato do arquivo** e, em CSV, **Separador CSV**.
4. Escolha **Comportamento** e **Quando uma linha falhar**. Confira o **Código do lote** e use **Validar arquivo**.
5. Corrija erros e valide novamente. Com pelo menos uma linha válida e nenhuma com erro, **Importar registros** fica disponível; confirme para gravar.

A conferência valida sem persistir registros de negócio. O resultado mostra quantidades de linhas válidas/com erro e, por linha, Resultado e Detalhe. Alterar arquivo, formato, separador ou configuração antes da execução invalida a conferência anterior. Mesmo escolhendo gravar as demais linhas válidas, a tela exige uma prévia sem erros para liberar a execução; a política de falhas vale para problemas encontrados na gravação.

## Formato do arquivo e campos

| Campo ou formato | Opções e condições |
| --- | --- |
| Formato do arquivo | CSV, Excel (.xlsx) ou JSON; começa em CSV. Não aceita XLS antigo, PDF, imagem ou arquivo compactado como planilha. |
| Separador CSV | Vírgula (padrão), Ponto e vírgula ou Tabulação. Só aparece para CSV e precisa corresponder ao arquivo. |
| CSV | Primeira linha contém os nomes dos campos. Aspas delimitam valores com separadores ou quebras de linha. |
| Excel (.xlsx) | Uma única planilha, com cabeçalhos; fórmulas e células de erro são recusadas, mesmo que mostrem um resultado calculado. Use valores. |
| JSON | Lista de objetos, um objeto por registro; não é um único objeto nem uma lista de valores soltos. |
| Limites | Até 2 MB, de 1 a 100 registros por lote e até 100 colunas na planilha. Divida arquivos maiores em lotes distintos. |

Preserve os nomes esperados pelo mapeamento; os cabeçalhos da planilha não podem estar vazios ou repetidos. As opções e os valores precisam corresponder ao destino ou às conversões configuradas no mapeamento: o sistema não adivinha o significado de uma coluna ou de uma sigla. Campos com os nomes do Askora só passam diretamente quando essa opção está habilitada no mapeamento. Relações, datas, valores obrigatórios e listas continuam sujeitos às validações do cadastro de destino.

## Criar, atualizar e identificar

| Comportamento | Resultado |
| --- | --- |
| Criar novos registros | Padrão. Tenta cadastrar cada linha; não transforma um pedido repetido em atualização. |
| Atualizar existentes | Exige encontrar a identidade já cadastrada. Identidade ausente gera erro em vez de criar outro registro. |
| Criar ou atualizar | Atualiza quando encontra a identidade e cria quando ela não existe, respeitando o contrato do destino. |

Em Vendas, a identidade é o número de **Pedido** (`orderNumber`), inclusive para devoluções e pedidos inativos. Nas demais tabelas, use o código do sistema de origem com seu espaço de nomes (`_external.key` e `_external.namespace`), conforme o mapeamento. Exemplo: código 000123 no sistema ERP deve conservar seus zeros e o mesmo espaço de nomes nas atualizações. O nome da pessoa ou produto não substitui essa identidade.

Não use IDs internos de outra empresa para atualizar registros. O Askora resolve identidade e versão, e cada vínculo precisa ser autorizado para o destino. Um erro de identidade não deve ser contornado com Criar novos registros sem conferir se isso produziria duplicação.

Cada destino mantém suas regras, permissões, limites, aprovações e efeitos no domínio. Importar uma venda não dispensa Pedido, responsável e data válidos nem evita as proteções de fechamento. Métricas e lotes de Pagamentos não são destinos de criação por esse fluxo. A disponibilidade do mapeamento não amplia o acesso aos dados.

## Falhas, código do lote e retomada

**Quando uma linha falhar** começa em **Gravar as demais linhas válidas**. Nessa opção, linhas concluídas permanecem salvas mesmo que outras falhem. **Não gravar nenhuma linha** desfaz o lote da execução quando uma linha falha. A execução revalida os dados e pode encontrar conflito, limite ou mudança de permissões depois da conferência.

Em **Identificação do lote e retomada**, **Código do lote** já vem preenchido e admite até 100 caracteres. Guarde-o com o arquivo. Se houver interrupção, use **Tentar novamente** com o mesmo código, arquivo, ordem das linhas, mapeamento, comportamento e acesso. Linhas já concluídas retornam como **Já processada**, sem nova gravação; mudar o conteúdo/configuração de uma linha já processada com o mesmo código gera conflito. Não altere o mapeamento para tentar retomar aquele lote.

Depois de iniciar a execução, arquivo e opções ficam bloqueados para preservar a retomada. **Baixar resultado** exporta o relatório JSON com o código, destino, quantidades e resultado por linha, inclusive da conferência; o relatório não é uma nova importação nem confirma sucesso integral. Se houve falhas, confira quais linhas já concluíram antes de preparar uma correção.

**Novo lote** limpa arquivo e conferência, gera outro código e mantém o mapeamento escolhido. Use-o para um trabalho diferente ou um arquivo corrigido; em importação parcial, não reenvie inadvertidamente linhas já criadas como novas. Sair antes da execução descarta a conferência; depois de uma tentativa, preserve o código para retomar. A interface impede sair durante a requisição.

## XML fiscal e exportação

XML de nota fiscal deve seguir o fluxo de Documentos, na aba fiscal, para validar emitente, destinatário e valores. Não o envie como uma transferência genérica de Arquivos.

Esta página executa mapeamentos de entrada. Para extrair dados, use **Integrações → Arquivos → Exportar** e seu mapeamento de saída; **Baixar resultado** nesta tela baixa somente o relatório da transferência.

## Disponibilidade

A execução e a configuração dos mapeamentos ficam no web e são exclusivas do **Master**, com validação do destino. Um Administrador não recebe esse acesso apenas por seu perfil administrativo. O aplicativo não oferece tela nativa de Arquivos.