Migrações¶

Em uma frase. Importação em massa do acervo de XMLs do NF-e 1.00 para o 2.00: cria a migração, recebe os lotes de XML, processa em segundo plano e mostra progresso, falhas e histórico — sem emitir nada na SEFAZ.

Quem usa: equipe de implantação, suporte, analista fiscal responsável pelo acervo · Frequência: na implantação e em cargas pontuais de acervo · Pré-requisitos: empresas (emitentes e destinatárias do acervo) cadastradas em Dados Mestres ▸ Empresas; permissão de acesso às migrações

Para que serve¶

Quem chega ao NF-e 2.00 traz anos de notas no sistema anterior. Esta tela é o caminho para trazer esse acervo — notas já autorizadas, resumos e eventos — para dentro do app, sem digitar nada e sem passar de novo pela SEFAZ.

O trabalho se organiza em dois níveis:

Migração — uma carga inteira (o acervo, ou um recorte dele, como "2019 — filial São Paulo");
Lote — até 500 XMLs enviados de uma vez dentro de uma migração. Acervos grandes são enviados em vários lotes, todos na mesma migração.

Os lotes podem ser enviados por esta tela ou por um conector, que chama a mesma API a partir do sistema legado. O processamento é o mesmo nos dois casos: cada XML segue o mesmo caminho de um arquivo enviado pela Gestão de Arquivos e vira nota emitida, nota recebida ou evento.

Como chegar¶

No Hub, abra o app NF-e.
Selecione o tile Migrações.

A tela tem três seções — Visão Geral, Histórico e Nova Migração — e mostra só as que o seu perfil permite. Sem nenhuma: «Você não tem permissão para acessar o módulo de Migrações. Fale com o administrador da conta se precisar de acesso.»

Visão Geral¶

Panorama das migrações que ainda estão em andamento. Atualiza sozinha a cada 10 segundos enquanto a aba do navegador está visível; o botão Atualizar força a leitura e o rodapé da barra mostra «Atualizado às HH:MM:SS».

Cards¶

Card	Conteúdo
Ativas · Pausadas · Drenando · Concluídas	Quantidade de migrações da conta em cada situação ("Concluídas" soma concluídas e concluídas com falhas)
Backlog	Documentos ainda não processados, somando as migrações em andamento
Em voo	Documentos em processamento neste momento
Quarentena	Documentos que falharam (inválidos, não reconhecidos, com erro)
Falhas de infra	Documentos que esgotaram as novas tentativas automáticas por falha de infraestrutura

Alertas¶

Antes da tabela, uma faixa por alerta, com o link abrir migração:

Alerta	Quando dispara	Gravidade
Sem progresso	Migração ativa com pendências e sem mudança de situação há mais de 30 min	Crítico
Backlog alto	50.000 documentos ou mais pendentes	Aviso
Itens presos	Documentos em processamento e migração sem mudança de situação há mais de 30 min	Crítico
Quarentena relevante	5% ou mais dos documentos em quarentena	Aviso
Falhas definitivas de infraestrutura	Algum documento esgotou as tentativas	Crítico
Reconciliação divergente	Migração em conferência final, sem pendências, que não fecha	Crítico
Drenagem lenta	Cancelamento em andamento há mais de 60 min	Aviso
Extração incompleta	Lote que não terminou de ser aberto	Aviso

Tabela «Migrações em andamento»¶

Colunas: Status, Total, Processados, Backlog, Em voo, Quarentena, Infra, Criada em e Abrir. Mostra até 50 migrações; acima disso, o título avisa «(lista truncada — veja o Histórico)». Migrações concluídas e canceladas saem daqui e ficam no Histórico.

Histórico¶

Todas as migrações, inclusive as encerradas, com paginação feita no servidor.

Filtro	Valores	Padrão
Status	Criado, Ativo, Pausado, Drenando, Reconciliando, Concluído, Concluído com falhas, Cancelado — vários ao mesmo tempo	Nenhum (todos)
Criada de / Até	Data de criação	Hoje — o Histórico abre mostrando só as migrações criadas hoje

Limpar filtros zera status e datas. Colunas: Status, Descrição, Origem, Lotes, Estimado, Criada em, Atualizada em e Abrir.

Nova Migração¶

1. Identificar a migração¶

Campo	Obrigatório	Formato / domínio	Regra	Registro / campo fiscal
Descrição	não	Texto, até 255 caracteres	Identifica a carga no Histórico. Ex.: «acervo 2019 — filial São Paulo»	—
Total estimado de documentos	não	Número inteiro	«Serve só para acompanhar o progresso — não limita o envio.»	—

Criar migração grava a migração com origem nfe_1_0 e situação Criado, e libera o passo 2: «Migração criada. Agora envie os lotes de XML abaixo.»

2. Enviar lotes de XML¶

Escolha os arquivos em Arquivos XML. A tela confere antes de enviar e avisa:

Limite	Valor	Aviso
Arquivos por lote	500	«O lote tem N arquivos; o limite é 500. Divida em lotes menores.»
Tamanho do lote	64 MB	«O lote tem X MB; o limite é 64.0 MB.»
Tamanho por arquivo	10 MB	«N arquivo(s) acima de 10.0 MB: …»
Extensão	`.xml`	«N arquivo(s) não são .xml e serão recusados.»

Com algum aviso, Enviar lote fica desabilitado. A barra mostra quantidade, tamanho e o identificador do lote (lote-AAAAMMDDHHMMSS-xxxxxx); Limpar seleção esvazia a escolha. Durante o envio aparece a barra «Enviando… N%».

Cada lote aceito entra em Lotes aceitos, com o selo Aceito ou Reenvio (já existia). Aceito significa recebido de forma durável e enfileirado — não que os documentos já foram processados. Acompanhar migração abre o detalhe.

O identificador do lote só muda depois de um envio bem-sucedido. Se o envio falhar, tentar de novo reaproveita o mesmo identificador — e o lote não é duplicado caso a primeira tentativa tenha chegado.

Detalhe da migração¶

Aberto por Abrir (Visão Geral, Histórico), pelo link de um alerta ou por Acompanhar migração. Cabeçalho Migração, com o identificador e o selo da situação; Voltar retorna à seção anterior. Atualiza a cada 10 segundos enquanto a migração está em andamento; encerrada, a barra avisa «migração encerrada (sem atualização automática)».

Ações¶

Botão	Habilitado quando	Efeito
Atualizar	sempre	Relê todas as abas
Pausar	Ativo	Para de gerar trabalho novo; o que já está em processamento termina. Reversível
Retomar	Pausado	Volta a Ativo
Cancelar	Criado, Ativo, Pausado, Drenando ou Reconciliando	Pede confirmação: «Cancelar esta migração?»

A confirmação do cancelamento explica: a migração para de gerar trabalho novo e drena o que já está em processamento; nada do que já foi importado é apagado; a ação não pode ser desfeita — para continuar depois, é preciso criar uma migração nova. Após confirmar: «Cancelamento solicitado. A migração está drenando o que estava em voo.»

Se outra pessoa (ou outra aba) mudou a situação no meio tempo, a ação volta como conflito, com a mensagem do servidor seguida de «O estado da migração foi atualizado na tela.»

Aba «Resumo»¶

Cards Total, Processados, Sucesso, Inválidos, Erro, Desconhecidos, Quarentena, Pendentes e Em voo; barra de progresso com "N% concluído"; e a tabela:

Linha	Conteúdo
Tempo restante estimado	Estimativa, "(estimativa imprecisa)" quando a amostra é fraca, ou «Indisponível — »: ainda sem amostra suficiente, sem vazão mensurável, totais inconsistentes (extração em curso), nada pendente, migração não está processando
Vazão atual / Vazão média	Itens por segundo ou por minuto
Lotes	"N concluídos de M", com lotes em andamento e com extração incompleta
Criada em / Última atualização / Concluída em	Datas da migração

Aba «Quarentena»¶

Os documentos que falharam, com filtros por erro (chips), busca por nome do arquivo ou mensagem de erro (Buscar), e Só reprocessáveis.

Coluna	Conteúdo
Arquivo	Nome do XML
Status	Situação do documento (inválido, erro de processamento, desconhecido)
Erro	XML inválido · Não classificado · Regra de negócio · Falha de infraestrutura · Desconhecido
Detalhe	Resumo da mensagem de erro
Tent.	Tentativas de processamento
Detectado em	Data e hora
Ações	Reprocessar, ou o motivo de não poder

Marque vários e use Reprocessar selecionados (até 500 por vez). O resultado diz «N de M itens reenfileirados.» e agrupa os recusados por motivo.

Aba «Monitoramento»¶

Situação, cards (Total, Processados, Sucesso, Backlog, Em voo, Quarentena, Falhas de infra), os alertas desta migração («Nenhum alerta operacional para esta migração.» quando não há), lotes terminais, lotes com extração incompleta e falhas definitivas de infraestrutura — estas se detalham na Quarentena filtrando por Falha de infraestrutura.

Aba «Documentos»¶

Uma linha por nota da origem — o documento que o conector montou com os XMLs dela. Só aparece para lotes enviados com manifesto (o conector sempre envia; o envio manual pela tela não). Cards no topo: documentos recebidos, quantos a origem declarou ao encerrar o envio, e a contagem por resultado (Migrado, Recusado, Falha técnica, Em processamento).

Filtros: cenário (Autorizada, Inutilizada, Rejeitada), resultado e busca por chave de acesso (44 posições) ou pelo id na origem.
Colunas: id na origem, chave, cenário, resultado (com o motivo da recusa), a nota no 2.00 (link que abre a nota) e quantidade de XMLs.
Expandir a linha mostra cada XML do documento com o papel (NF-e autorizada, Envio, Retorno SEFAZ, Inutilização, Evento), a tentativa e a situação dele.
Carregar mais busca a próxima página; não há atualização automática — use Atualizar.

Aba «Auditoria»¶

Trilha das ações humanas sobre a migração: criação, lote aceito, pausa, retomada, cancelamento, reprocessamento de item e de lote. Colunas Quando, Ação, Quem (identificador do usuário ou da integração), Resultado (Executada / Recusada) e Detalhes, com filtro por ação. «A trilha registra apenas ações humanas. O processamento automático aparece no monitoramento.»

Regras de negócio¶

RN-MIG-001 — Nada é emitido nem transmitido à SEFAZ. Toda nota criada pela migração tem origem Migração e não pode ser emitida nem retransmitida — nem quando está Rejeitada («Nota migrada do NF-e 1.00 é acervo histórico e não pode ser emitida nem retransmitida.»). XML de envio (NFe, enviNFe) só entra como histórico: assinado, vira nota Rejeitada (rejeição do 1.00); sem assinatura, só entra numa nota inutilizada (RN-MIG-013); fora disso é recusado com «Migração aceita apenas documentos já autorizados…».
RN-MIG-002 — O cadastro decide emitida ou recebida. Cada nfeProc é comparado com as empresas da conta: emitente da conta → nota emitida; destinatário da conta → nota recebida; os dois → as duas. Nenhuma das pontas cadastrada → recusa («Nem o emitente … nem o destinatário … correspondem a uma empresa do tenant»). Cadastre as empresas antes de migrar.
RN-MIG-003 — Tipos aceitos. nfeProc e resNFe (notas); NFe/enviNFe (envio, ver RN-MIG-001); retEnviNFe/retConsReciNFe (retorno da SEFAZ de uma tentativa); procInutNFe/retInutNFe (inutilização homologada, cStat 102); procEventoNFe, envEvento, retEvento, evento, retEnvEvento (eventos). Outra raiz XML ou XML malformado vai para a quarentena como XML inválido; o lote só aceita arquivos .xml.
RN-MIG-004 — Reenviar não duplica. O mesmo identificador de lote devolve o lote original («Reenvio (já existia)»). O mesmo documento em lotes diferentes não gera segunda nota: a chave de acesso já registrada é reconhecida.
RN-MIG-005 — Documento migrado não dispara nada. Não notifica webhook, não envia e-mail e não é enviado à Escrituração Fiscal. A carga histórica não se mistura com o movimento do dia.
RN-MIG-006 — Lote só entra em migração Criada ou Ativa. A migração passa de Criado a Ativo no primeiro lote aceito. Pausada, cancelada ou encerrada, recusa lotes novos.
RN-MIG-007 — Pausar não é parar na hora. A pausa impede trabalho novo; documentos já em processamento terminam.
RN-MIG-008 — Cancelar é definitivo e não apaga nada. A migração vai para Drenando e fecha em Cancelado quando não resta documento em processamento. Notas, eventos e XMLs já importados permanecem.
RN-MIG-009 — A migração conclui sozinha. Quando todos os lotes terminam e nada resta em processamento, ela passa por Reconciliando (conferência dos documentos) e fecha em Concluído ou Concluído com falhas. Não há botão de concluir. Migração criada pelo conector com encerramento explícito só conclui depois que ele avisa que terminou de enviar; até lá o Resumo mostra «Aguardando o fim do envio…», mesmo com a fila vazia, e lotes novos continuam aceitos. Depois do aviso, a migração recusa lotes novos.
RN-MIG-010 — Reprocessar só com a migração ativa. Só documentos inválidos ou com erro de processamento, com o conteúdo guardado, podem voltar à fila — e só enquanto a migração está Ativa. Reprocessar reenvia o mesmo XML: não substitui o arquivo.
RN-MIG-011 — Falha de infraestrutura tem novas tentativas automáticas. O documento é reenviado automaticamente até 8 vezes; esgotadas, fica na quarentena como Falha de infraestrutura.
RN-MIG-012 — A estimativa de tempo não inventa número. Sem amostra suficiente, com a migração parada ou com os totais ainda em formação, a tela diz «Indisponível» e o motivo.
RN-MIG-013 — Inutilizada. A faixa inutilizada (procInutNFe) é registrada e marca como Inutilizada a nota da numeração. O XML de envio da nota, mesmo sem assinatura, vira nota Inutilizada se a faixa cobre o número; sem a faixa, é recusado.
RN-MIG-014 — Rejeitada. A nota nasce do envio da última tentativa e fica com o código e o motivo do retorno da última tentativa. A rejeição do lote inteiro (sem a chave da nota, ex. 225) vale para a nota do documento. Cada tentativa aparece no Histórico SEFAZ da nota, com o XML de envio e o de retorno.
RN-MIG-015 — Rejeição antiga não rebaixa nota autorizada. Retorno de rejeição de uma tentativa anterior não muda nota já Autorizada, Cancelada ou Denegada.

As regras RN-MIG-013 e RN-MIG-014 dependem da ordem entre os XMLs de cada nota, que o servidor garante quando processa por documento (lotes com manifesto, com a opção ligada no ambiente).

O que esta tela não faz¶

Não emite, não cancela e não transmite nada à SEFAZ.
Não apaga o que foi importado — nem no cancelamento.
Não envia as notas migradas à Escrituração Fiscal (RN-MIG-005).
Não aceita .zip — os XMLs são enviados soltos, até 500 por lote.
Não permite trocar o XML de um item em quarentena. Para corrigir o conteúdo, envie o XML corrigido num novo lote, com a migração ativa.
Não retoma envio de lotes numa migração antiga pela tela. Os lotes são enviados na seção Nova Migração, na migração recém-criada; cargas contínuas usam o conector.

Erros e mensagens¶

Mensagem	Quando aparece	O que fazer
«Não foi possível criar a migração.»	Falha ao gravar	Tente de novo; persistindo, acione o suporte com a referência exibida
«Não foi possível enviar o lote.»	Falha no envio	Tente de novo: o mesmo identificador de lote é reaproveitado e não duplica
«Job de migração em status Pausado não aceita batches.»	Lote para migração pausada, cancelada ou encerrada	Retome a migração, ou crie uma nova
«Batch com N arquivos excede o limite de 500 XMLs.»	Lote acima do limite	Divida o lote
«Arquivo '…' não é .xml — o batch aceita apenas XMLs.»	Arquivo de outra extensão	Retire o arquivo do lote
«Arquivo '…' está vazio.»	Arquivo sem conteúdo	Retire ou substitua o arquivo
«Migração aceita apenas documentos já autorizados — XML de emissão (enviNFe/NFe) não é processado no fluxo de migração.»	XML de envio sem assinatura fora de uma nota inutilizada	Obtenha o `nfeProc` (XML com protocolo) ou o envio assinado no sistema de origem
«Envio sem assinatura … sem inutilização homologada cobrindo o número…»	Nota inutilizada cuja faixa não chegou (ou chegou depois)	Envie o `procInutNFe` da faixa; com a migração ativa, reprocesse o item
«Manifesto do lote inválido: …»	O agrupamento enviado pelo conector não casa com os arquivos	Corrija o manifesto no conector e reenvie o lote com um identificador novo
«Nota migrada do NF-e 1.00 é acervo histórico e não pode ser emitida nem retransmitida.»	Tentativa de emitir uma nota migrada	Nenhuma: a nota é histórico do 1.00
«Nem o emitente (CNPJ …) nem o destinatário (CNPJ …) correspondem a uma empresa do tenant…»	Nota de empresa não cadastrada	Cadastre a empresa em Dados Mestres e reprocesse com a migração ativa
«Raiz XML não reconhecida: …» / «XML malformado.»	Arquivo que não é NF-e nem evento	Confira o arquivo no acervo de origem
«Status '…' não permite a operação '…'.»	Ação incompatível com a situação atual	A tela já recarregou a situação real; reavalie
«Você não tem permissão para esta ação.»	Perfil sem a permissão da ação	Peça o acesso ao administrador da conta

Relação com a NF-e / SEFAZ / EFD¶

Elemento	Relação
`nfeProc`	NF-e com protocolo de autorização. Vira nota Autorizada (emitida) e/ou Recebida, com o XML original preservado
`resNFe`	Resumo de NF-e de terceiro, sem itens. Vira nota recebida em resumo, completada se o `nfeProc` chegar depois
Eventos (`procEventoNFe` e variantes)	Cancelamento, carta de correção e demais eventos já registrados na SEFAZ; aplicados à nota da mesma chave
SEFAZ	Nenhuma comunicação: nada é autorizado, cancelado ou consultado durante a migração
EFD-ICMS/IPI	As notas migradas não são enviadas à Escrituração Fiscal por este fluxo (RN-MIG-005); portanto não geram, por si, registro C100 na EFD gerada pela plataforma. Competências já entregues pelo sistema anterior continuam válidas como estão

Perguntas frequentes¶

Enviei o lote e ele diz "Aceito", mas as notas não aparecem. Aceito é recebido e enfileirado. Acompanhe no detalhe da migração: as notas aparecem conforme os documentos são processados.

Posso enviar o mesmo lote de novo? Pode. Com o mesmo identificador, a tela mostra «Reenvio (já existia)»; com outro, os documentos já importados são reconhecidos pela chave e não duplicam.

Metade do acervo caiu em quarentena por "Regra de negócio". Quase sempre é empresa não cadastrada (RN-MIG-002) ou XML sem autorização (RN-MIG-001). Leia o Detalhe, cadastre as empresas e use Reprocessar selecionados enquanto a migração está ativa.

A migração concluiu com falhas. Consigo reprocessar a quarentena agora? Não pela mesma migração: reprocessar exige a migração ativa (RN-MIG-010). Crie uma nova migração e envie os XMLs que falharam.

Cancelei por engano. O que já foi importado continua lá. Para o restante, crie uma nova migração e envie os lotes que faltavam — o que já existe não é duplicado.

Onde vejo migrações de semanas atrás? No Histórico, ajustando Criada de: a seção abre só com as de hoje.