Sincronização SEFAZ DF01¶
Painel que controla o download dos documentos fiscais que a SEFAZ tem para sua empresa. Cada linha é um job de sincronização — uma combinação de empresa + tipo de documento (NF-e ou CT-e).
Pré-requisitos¶
- Estar logado como Master (nível 0) — execução manual de sync exige esse nível
- Empresa com sincronização ativa e certificado A1 válido
- DFE Service online (status no topo direito da tela)
Como a sincronização funciona
A sincronização roda automaticamente em background a cada poucos minutos. Esta tela serve para acompanhar o progresso e forçar uma execução manual quando necessário (ex.: você precisa baixar uma NF que acabou de chegar).
Passo a passo¶
1. Acessar a tela¶
No menu lateral, clique em DFe → Sincronização.
2. Verificar o status do serviço¶
No canto superior direito:
| Indicador | Significado |
|---|---|
| DFE Service Online (verde) | Serviço rodando — pode executar sync manual |
| DFE Service Offline (vermelho) | Serviço parado — botões ficam desabilitados |
Se estiver offline, vá em Configurações → Serviços e inicie o dfe-service.
3. Entender as colunas da tabela¶
| Coluna | Descrição |
|---|---|
| Empresa | CNPJ destinatário sincronizado |
| Tipo | NFE ou CTE |
| Status | Estado atual do job (veja abaixo) |
| Progresso | Barra com NSU atual / NSU máximo (último número de sequência conhecido) |
| Última Sync | Quando rodou pela última vez |
| Erro | Mensagem da SEFAZ se a última execução falhou |
4. Estados do job¶
| Status | Significado |
|---|---|
| Em dia (verde) | NSU atual = NSU máximo — tudo baixado |
| Percorrendo (azul) | Última execução concluída mas ainda há documentos a baixar |
| Executando (amarelo, pulsando) | Job rodando agora — não execute de novo |
| Erro (vermelho) | Última execução falhou (passe o mouse no erro) |
| Pendente (cinza) | Nunca rodou ou aguardando primeira execução |
5. Executar sincronização¶
| Botão | Quando usar |
|---|---|
| Executar (na linha) | Roda apenas o job daquela empresa+tipo |
| Sincronizar Todos (topo) | Roda todos os jobs ativos em paralelo |
A página atualiza sozinha a cada 5 segundos enquanto algum job está executando.
6. Editar NSU¶
O NSU (Número Sequencial Único) é o "marcador" da SEFAZ — diz até onde sua empresa já consultou. Clique em Editar NSU na linha para alterar:
- Coloque
0se quiser baixar tudo desde o início (cuidado: pode demorar e ser bloqueado por rate limit) - Edite manualmente se a SEFAZ retornou um NSU inválido e travou o job
- Requer senha do Master para confirmar
Edite NSU com cuidado
Reduzir o NSU força re-download de documentos já baixados (eles serão deduplicados pela chave, mas consomem cota da SEFAZ). Aumentar o NSU pode pular documentos que você ainda não tem.
Filtros e mensagens¶
Filtro de data mínima¶
Se a configuração SYNC_DATA_MINIMA está ativa, um banner amarelo no topo informa: "Salvando apenas documentos a partir de DD/MM/AAAA". Documentos anteriores são baixados mas descartados.
Cooldown / Rate Limit¶
A SEFAZ aplica rate limit por CNPJ (geralmente 1 consulta por hora). Quando isso acontece:
- O job recebe o erro
Rate limited - Na coluna Erro, aparece "Cooldown até HH:MM"
- O botão Executar fica como Aguarde até o cooldown vencer
- A sincronização automática retoma sozinha após o cooldown
Erros comuns¶
DFE Service offline
O serviço Python dfe-service não está rodando no Windows. Vá em Configurações → Serviços e clique em Iniciar.
Certificado vencido
A SEFAZ rejeita conexões com certificado expirado. Vá em Certificados A1 (DF02) e faça novo upload.
Rate limit constante
Se uma empresa vive em cooldown, é porque a sincronização automática está disparando além do permitido. Verifique se há mais de uma instância do dfe-service rodando.
NSU travado em valor antigo
A SEFAZ às vezes retorna o mesmo NSU várias vezes. Edite manualmente para forçar o avanço — somente em último caso.