# Nanci > App desktop e CLI para baixar NFS-e do ADN e NF-e e CT-e da SEFAZ com certificado A1 Todas as páginas da documentação em Markdown, na ordem do site. O índice com uma linha por página está em https://nanci.abelhaninja.de/llms.txt. --- # Documentação URL: https://nanci.abelhaninja.de/docs/ O Nanci baixa os documentos fiscais da empresa direto do governo, com o certificado A1: | Documento | Origem | |---|---| | [NFS-e](https://nanci.abelhaninja.de/docs/nfse/) | Ambiente de Dados Nacional (ADN) | | [NF-e](https://nanci.abelhaninja.de/docs/nfe/) | Distribuição DF-e da SEFAZ | | [CT-e](https://nanci.abelhaninja.de/docs/cte/) | Distribuição DF-e da SEFAZ | {{< cards >}} {{< card link="instalacao" title="Instalação e primeiro uso" icon="download" >}} {{< card link="certificados" title="Certificado A1" icon="key" >}} {{< card link="cli" title="Linha de comando" icon="terminal" >}} {{< card link="faq" title="Perguntas frequentes" icon="question-mark-circle" >}} {{< /cards >}} ## Fora do escopo - Emitir notas. - NFC-e, MDF-e, NFCom, NF3e, CF-e SAT e importação de XML avulso. - NF-e e CT-e emitidos pela própria empresa: a SEFAZ não os distribui ao emitente. --- # Instalação e primeiro uso URL: https://nanci.abelhaninja.de/docs/instalacao/ Você precisa de Windows 10 ou 11 e de um certificado e-CNPJ A1 (`.pfx` ou `.p12`). ## Instalar Baixe `nanci-desktop-windows-amd64--installer.exe` da [última versão](https://github.com/vasfvitor/nanci/releases/latest) e execute. Não precisa de administrador. O instalador não tem assinatura de código, então o SmartScreen pode avisar. Para conferir o arquivo, compare o hash com o `nanci-checksums.txt` da mesma versão: ```powershell Get-FileHash .\nanci-desktop-windows-amd64-v0.5.1-installer.exe -Algorithm SHA256 ``` ## Cadastrar a empresa Sem empresa cadastrada, a primeira tela mostra os três passos até as primeiras notas, e o botão **Cadastrar primeira empresa** abre o cadastro. {{< theme-image light="/img/screenshots/boas-vindas-light.png" dark="/img/screenshots/boas-vindas-dark.png" alt="Tela de boas-vindas" >}} Em **Empresas**, clique em **Adicionar** e informe CNPJ, nome e certificado. Preencha também: - **UF**, se for baixar NF-e ou CT-e. - **O que deseja importar no primeiro sync?**: vale só para a NFS-e. NF-e e CT-e trazem o que a SEFAZ ainda tiver, cerca de 3 meses. {{< theme-image light="/img/screenshots/dialogo-adicionar-empresa-light.png" dark="/img/screenshots/dialogo-adicionar-empresa-dark.png" alt="Diálogo de adicionar empresa" >}} ## Sincronizar Escolha a empresa no menu lateral, abra **NFS-e**, **NF-e** ou **CT-e** e clique em **Sincronizar**. A senha do certificado é pedida uma vez e fica guardada no Windows. Na **NFS-e**, o botão **Sincronizar NFS-e** traz a marca **Primeira sincronização** até a empresa sincronizar pela primeira vez. {{< theme-image light="/img/screenshots/primeira-sincronizacao-light.png" alt="Botão de sincronizar com a marca de primeira sincronização" >}} --- # NFS-e URL: https://nanci.abelhaninja.de/docs/nfse/ As NFS-e vêm do ADN Contribuintes, a API nacional da Receita Federal ([manual da API](https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual/manual-contribuintes-apis-adn-sistema-nacional-nfse.pdf)): notas tomadas, prestadas e intermediadas, com cancelamentos e substituições. {{< theme-image light="/img/screenshots/documentos-light.png" dark="/img/screenshots/documentos-dark.png" alt="Página de NFS-e" >}} Exporte a lista filtrada em Excel, CSV, ZIP com os XMLs ou ZIP com os DANFSe. Cada nota também pode ser salva sozinha em XML ou PDF. **Somente não exportados** repete só o que mudou desde a última exportação naquele formato. **Consulta Direta API** busca os eventos de uma nota pela chave de acesso, sem sincronizar. ## Notas que não aparecem A fila do ADN não traz necessariamente todas as notas que a empresa emitiu; depende do município. Veja a [FAQ](https://nanci.abelhaninja.de/docs/faq/#emito-nfs-e-mas-o-nanci-não-baixou-nada). --- # NF-e URL: https://nanci.abelhaninja.de/docs/nfe/ O Nanci baixa as NF-e em que a empresa aparece, pela distribuição DF-e da SEFAZ, e registra a Manifestação do Destinatário. A empresa precisa ter UF cadastrada. {{< theme-image light="/img/screenshots/nfe-light.png" dark="/img/screenshots/nfe-dark.png" alt="Página de NF-e" >}} A SEFAZ guarda as notas por 90 dias e não reenvia o que já saiu da fila. Dentro desse prazo, uma nota que não chegou pode ser buscada pela chave; depois dele, só entra pelo XML (ver [Importar e buscar](#importar-e-buscar)). Como destinatária, a empresa recebe primeiro um **resumo**. O XML completo chega depois da **Ciência da Operação**, da Confirmação ou da Operação não Realizada ([NT 2014.002](https://www.nfe.fazenda.gov.br/portal/exibirArquivo.aspx?conteudo=uWO2d/gTuWg=)). ## Limite de consultas A SEFAZ bloqueia por uma hora quem consulta demais ([NT 2014.002](https://www.nfe.fazenda.gov.br/portal/exibirArquivo.aspx?conteudo=uWO2d/gTuWg=)). O Nanci faz no máximo 20 consultas por hora e, quando a fila está em dia, espera uma hora antes de consultar de novo. Enquanto isso, o botão de sincronizar mostra quando volta a funcionar. Não deixe a empresa mais de 60 dias sem sincronizar. A SEFAZ só gera NSU para quem consultou nesse prazo, e as notas do período parado não chegam mais (regra da NT 2014.002 v1.10, conhecida por relatos de terceiros). Depois de 45 dias sem consulta, a página mostra o aviso **Sem consulta há N dias**; sincronizar reinicia a contagem. ## Manifestação do Destinatário {{< callout type="warning" >}} Uma manifestação enviada não pode ser cancelada. A SEFAZ aceita retificar uma manifestação conclusiva em até 30 dias ([Ajuste SINIEF 07/05](https://www.confaz.fazenda.gov.br/legislacao/ajustes/2005/AJ007_05)), mas o Nanci ainda não faz isso. {{< /callout >}} - **Ciência da Operação**: selecione as notas e clique em **Registrar ciência**. - **Confirmação, Desconhecimento ou Operação não Realizada**: use **Manifestar…** na linha da nota. {{< theme-image light="/img/screenshots/dialogo-ciencia-nfe-light.png" alt="Diálogo de Ciência da Operação" >}} A aba **Pendências** mostra as notas sem manifestação conclusiva e o prazo de cada uma: 90 dias da autorização. Depois disso a operação é considerada confirmada ([Ajuste SINIEF 07/05](https://www.confaz.fazenda.gov.br/legislacao/ajustes/2005/AJ007_05), cláusula 15ª-C). {{< theme-image light="/img/screenshots/nfe-pendencias-light.png" dark="/img/screenshots/nfe-pendencias-dark.png" alt="Aba de pendências de manifestação" >}} ## Importar e buscar **Importar XML** guarda as NF-e que a empresa já tem em arquivo, sem consultar a SEFAZ e sem gastar consultas: as notas que ela mesma emitiu, que a SEFAZ não entrega ao emitente, as de mais de 90 dias e as que o fornecedor mandou por e-mail. Aceita a nota autorizada (com o protocolo), o resumo e os eventos, vários arquivos de uma vez. Um arquivo de outro ambiente, ilegível ou de uma nota em que a empresa não aparece é recusado sem impedir os outros, e o Nanci mostra o motivo de cada um. Na lista, a nota importada leva a marca **Importado**. **Buscar pela chave** pede uma NF-e à SEFAZ pela chave de acesso. Funciona para a destinatária, a transportadora e quem foi autorizado no XML, dentro dos 90 dias; a SEFAZ não entrega ao emitente a própria nota, que só entra pela importação. Cada busca gasta 1 das 20 consultas da hora ([NT 2014.002](https://www.nfe.fazenda.gov.br/portal/exibirArquivo.aspx?conteudo=uWO2d/gTuWg=)). Enquanto a empresa não manifesta a nota, a SEFAZ entrega só o resumo: registre a Ciência da Operação e busque de novo, ou espere a próxima sincronização. ## Exportar **Exportar** gera, da lista filtrada ou da seleção, uma planilha Excel ou CSV, um ZIP com os XMLs e eventos, ou um ZIP com os DANFE em PDF. Cada nota também pode ser salva sozinha em XML ou DANFE. Resumos (notas sem o XML completo) entram na planilha e no ZIP de XML só com **Incluir resumos**, e nunca têm DANFE: o ZIP de DANFE avisa quantos ficaram de fora. **Somente não exportados** repete só o que mudou desde a última exportação naquele formato. --- # CT-e URL: https://nanci.abelhaninja.de/docs/cte/ O Nanci baixa os CT-e (modelos 57, 64 e 67) em que a empresa é parte, com os eventos. Precisa de UF cadastrada, como a [NF-e](https://nanci.abelhaninja.de/docs/nfe/), e tem o mesmo [limite de consultas](https://nanci.abelhaninja.de/docs/nfe/#limite-de-consultas), contado à parte. O aviso **Sem consulta há N dias**, depois de 45 dias sem sincronizar, também vale para o CT-e. {{< theme-image light="/img/screenshots/cte-light.png" dark="/img/screenshots/cte-dark.png" alt="Página de CT-e" >}} A SEFAZ guarda os CT-e por 3 meses ([NT 2015.002](https://www.cte.fazenda.gov.br/portal/exibirArquivo.aspx?conteudo=LLSQYxGtwv0=)). O XML completo chega direto, sem resumo nem manifestação. ## Exportar **Exportar** gera, da lista filtrada ou da seleção, uma planilha Excel ou CSV, um ZIP com os XMLs e eventos, ou um ZIP com os DACTE em PDF. Cada documento também pode ser salvo sozinho em XML ou DACTE. O DACTE existe só para o CT-e modelo 57; CT-e OS, GTV-e e CT-e Simplificado ficam fora do ZIP de DACTE, e a tela diz quantos ficaram de fora. **Somente não exportados** repete só o que mudou desde a última exportação naquele formato. ## Importar XML **Importar XML** guarda os CT-e que a empresa já tem em arquivo, sem consultar a SEFAZ e sem gastar consultas: os que ela mesma emitiu, os de mais de 3 meses e os recebidos por e-mail. Aceita CT-e, CT-e OS, GTV-e e CT-e Simplificado autorizados e os eventos, vários arquivos de uma vez. As recusas são as da [NF-e](https://nanci.abelhaninja.de/docs/nfe/#importar-e-buscar), e o Nanci mostra o motivo de cada arquivo. Na lista, o CT-e importado leva a marca **Importado**. Não há busca pela chave para o CT-e: a distribuição do CT-e só entrega pela fila de NSU. ## Achar o frete de uma NF-e Filtre por **Chave de NF-e transportada** para ver os CT-e que levaram aquela nota. --- # Linha de comando URL: https://nanci.abelhaninja.de/docs/cli/ O `nanci` faz pelo terminal o mesmo que o aplicativo e usa o mesmo banco. O instalador não traz o CLI; compile com [Go](https://go.dev/dl/): ```powershell git clone https://github.com/vasfvitor/nanci cd nanci go build -o nanci.exe ./cmd/nanci ``` As opções de cada comando estão no `--help`, por exemplo `nanci nfe list --help`. ## Primeiros passos ```powershell nanci company add --cnpj 12345678000199 --name "Minha Empresa" --cert C:\certs\empresa.pfx --uf SP nanci pull --cnpj 12345678000199 # NFS-e nanci nfe pull --cnpj 12345678000199 # NF-e nanci cte pull --cnpj 12345678000199 # CT-e nanci export xlsx --cnpj 12345678000199 --competencia 2026-09 --out setembro.xlsx ``` A senha do certificado é pedida no terminal na primeira vez e depois fica guardada no Windows. Em rotinas sem terminal, defina `NANCI_CERT_PASSWORD`. ## Comandos | Comando | O que faz | |---|---| | `init` | Cria ou atualiza o banco e a pasta de dados. | | `company add`, `update`, `list` | Cadastra, altera e lista empresas. | | `company assign-credential --cnpj --credential-id ` | Liga a empresa a um certificado já cadastrado. O ID sai em `credential list`. | | `credential add`, `list`, `update-path` | Cadastra certificados e atualiza o caminho do arquivo. | | `pull`, `status`, `list` | Sincroniza, mostra a situação e lista as NFS-e. | | `export xlsx`, `csv`, `zip`, `xml`, `danfse`, `danfse-zip` | Exporta as NFS-e. Nos formatos em lote, `--chave` (pode repetir) limita às notas informadas. | | `nfe pull`, `status`, `list`, `pendentes` | Sincroniza e lista as NF-e e as manifestações pendentes. | | `nfe ciencia`, `manifestar` | Registra a Manifestação do Destinatário. | | `nfe export zip`, `xml`, `csv`, `xlsx`, `danfe-zip`, `danfe` | Exporta as NF-e em XML, planilha ou DANFE (PDF). O DANFE não sai para resumos. | | `nfe import ...` | Importa arquivos XML de NF-e e de eventos que a empresa já tem, sem consultar a SEFAZ. | | `nfe buscar --chave ` | Busca uma NF-e na SEFAZ pela chave de acesso. | | `cte pull`, `status`, `list` | Sincroniza e lista os CT-e. `cte list --nfe ` acha o frete de uma NF-e. | | `cte export zip`, `xml`, `csv`, `xlsx`, `dacte`, `dacte-zip` | Exporta os CT-e. O DACTE só existe para o CT-e modelo 57. | | `cte import ...` | Importa arquivos XML de CT-e e de eventos que a empresa já tem, sem consultar a SEFAZ. | | `nfe testar-conexao`, `cte testar-conexao` | Testa o certificado sem gastar consultas. | | `nfe reset`, `cte reset` | Apaga as notas da empresa e recomeça a sincronização. | {{< callout type="warning" >}} `nfe ciencia`, `nfe manifestar` e os `reset` só simulam. Para executar, repita com `--confirmar`. Uma manifestação enviada não pode ser cancelada. {{< /callout >}} Cada `nfe buscar` gasta uma das 20 consultas por hora de NF-e da empresa, as mesmas do `nfe pull`. ## Rotina agendada Para o Agendador de Tarefas do Windows: ```powershell $cnpj = "12345678000199" nanci pull --cnpj $cnpj nanci nfe pull --cnpj $cnpj nanci cte pull --cnpj $cnpj nanci export zip --cnpj $cnpj --incremental --out "D:\fiscal\nfse-$(Get-Date -Format yyyyMMdd).zip" ``` Rodar de hora em hora é seguro: se a SEFAZ ainda não permitir nova consulta, o comando avisa e não envia nada. Os logs vão para o terminal; redirecione com `2>> nanci.log` se quiser guardá-los. --- # Certificado A1 URL: https://nanci.abelhaninja.de/docs/certificados/ O Nanci aceita certificado e-CNPJ **A1** (`.pfx` ou `.p12`). A3, em token ou cartão, não funciona. O mesmo certificado serve para NFS-e, NF-e e CT-e, e o da matriz serve para as filiais. O arquivo não é copiado; o Nanci guarda o caminho. Se você mover ou renovar o certificado, atualize o caminho em **Credenciais**. {{< theme-image light="/img/screenshots/credenciais-light.png" dark="/img/screenshots/credenciais-dark.png" alt="Tela de credenciais" >}} ## Senha A senha não vai para o banco do Nanci. Depois do primeiro uso ela fica no Gerenciador de Credenciais do Windows, numa entrada que começa com `nanci_certs`. Para esquecê-la, apague essa entrada. Na linha de comando, a senha também pode vir da variável `NANCI_CERT_PASSWORD`, definida no ambiente ou num arquivo `.env.local` na pasta onde o comando roda, na pasta do executável ou em `%LOCALAPPDATA%\nanci`. Em **Configurações**, **Testar Conexão** confere o certificado e a conexão com o ADN da NFS-e ou, com **CT-e** escolhido, com a SEFAZ do CT-e, sem enviar consulta; a NF-e fica de fora. --- # Privacidade e backup URL: https://nanci.abelhaninja.de/docs/privacidade/ O Nanci não tem servidor nem telemetria. Ele só se comunica com o ADN (`adn.nfse.gov.br`) e com a SEFAZ (`*.nfe.fazenda.gov.br`, `*.cte.fazenda.gov.br`), usando o certificado da empresa; numa empresa em Produção restrita, com os hosts de teste (`adn.producaorestrita.nfse.gov.br`, `hom1.nfe.fazenda.gov.br` e `hom1.cte.fazenda.gov.br`). ## Onde ficam os dados Em `%LOCALAPPDATA%\nanci`. **Configurações → Abrir Pasta de Dados** abre a pasta. | Item | Conteúdo | |---|---| | `nanci-v1.db` | Banco SQLite com empresas, notas e histórico. | | `blobs/` | Os XMLs originais. Não apague: as exportações saem daqui. | | `logs/` | Logs do aplicativo. Guardam o CNPJ das empresas em claro, para diagnóstico local; só o pacote gerado por **Exportar Pacote de Diagnóstico** mascara CNPJ e chaves de acesso. | As senhas ficam no Gerenciador de Credenciais do Windows. O banco e os XMLs não são criptografados; use o BitLocker se o computador for compartilhado. ## Backup Feche o Nanci e copie a pasta inteira. Para restaurar, copie de volta para o mesmo caminho antes de abrir o aplicativo. ## Apagar tudo Desinstalar remove só o programa. Para apagar os dados, apague a pasta e as entradas `nanci_certs` do Gerenciador de Credenciais. --- # Perguntas frequentes URL: https://nanci.abelhaninja.de/docs/faq/ {{< faq "Emito NFS-e, mas o Nanci não baixou nada" >}} A fila do ADN não traz necessariamente as notas que a empresa emitiu; depende do município. Teste com uma nota em que a empresa seja tomadora, ou consulte uma chave conhecida em **Consulta Direta API**. {{< /faq >}} {{< faq "Por que não aparecem as NF-e que a empresa emitiu?" >}} A SEFAZ não distribui ao emitente as notas que ele mesmo emitiu ([NT 2014.002](https://www.nfe.fazenda.gov.br/portal/exibirArquivo.aspx?conteudo=uWO2d/gTuWg=)). O mesmo vale para o CT-e. {{< /faq >}} {{< faq "Por que a NF-e aparece só como resumo?" >}} Falta a [Ciência da Operação](https://nanci.abelhaninja.de/docs/nfe/#manifestação-do-destinatário). Depois dela, o XML completo chega no próximo sync. {{< /faq >}} {{< faq "Consigo baixar notas antigas?" >}} NF-e e CT-e, só dos últimos 3 meses: é o que a SEFAZ guarda ([NT 2014.002](https://www.nfe.fazenda.gov.br/portal/exibirArquivo.aspx?conteudo=uWO2d/gTuWg=), [NT 2015.002](https://www.cte.fazenda.gov.br/portal/exibirArquivo.aspx?conteudo=LLSQYxGtwv0=)). Para NFS-e, escolha o período ao cadastrar a empresa. {{< /faq >}} {{< faq "Por que o botão de sincronizar está desabilitado?" >}} A SEFAZ limita as consultas. Veja [Limite de consultas](https://nanci.abelhaninja.de/docs/nfe/#limite-de-consultas). {{< /faq >}} {{< faq "Produção ou Produção restrita?" >}} Produção é o ambiente real. Produção restrita é o ambiente de testes do governo, sem valor fiscal ([Portal NFS-e](https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/apis-prod-restrita-e-producao)). Para trocar, use **Empresas → Editar**. {{< /faq >}} {{< faq "Funciona com certificado A3, macOS ou Linux?" >}} Não. Só certificado A1, e o aplicativo só existe para Windows. {{< /faq >}} --- # Solução de problemas URL: https://nanci.abelhaninja.de/docs/troubleshooting/ ## Erros comuns | Mensagem | O que fazer | |---|---| | SmartScreen: "O Windows protegeu o computador" | Confira o hash do instalador ([Instalação](https://nanci.abelhaninja.de/docs/instalacao/#instalar)) e clique em **Mais informações → Executar assim mesmo**. | | Senha incorreta ou "MAC verification failed" | Sincronize de novo e digite a senha certa. | | Certificado não encontrado | O arquivo mudou de lugar. Atualize o caminho em **Credenciais**. | | E2220: nenhum documento localizado | Não é erro: não há notas novas na fila do ADN. | | 401 ou 403 | O certificado está vencido ou é de outra empresa. | | "empresa sem UF cadastrada" | Informe a UF em **Empresas → Editar**. | | 593 ou 213 | O CNPJ da empresa não tem a mesma raiz do certificado ([NT 2014.002](https://www.nfe.fazenda.gov.br/portal/exibirArquivo.aspx?conteudo=uWO2d/gTuWg=), [NT 2020.001](https://www.nfe.fazenda.gov.br/portal/exibirArquivo.aspx?conteudo=%2BWTd7iuD21s%3D)). | | 656: consumo indevido | Consultas demais ([NT 2014.002](https://www.nfe.fazenda.gov.br/portal/exibirArquivo.aspx?conteudo=uWO2d/gTuWg=)). Se outro sistema também consulta esse CNPJ na SEFAZ, eles somam. O Nanci espera uma hora. | | 596 | A manifestação passou do prazo de 90 dias ([NT 2020.001](https://www.nfe.fazenda.gov.br/portal/exibirArquivo.aspx?conteudo=%2BWTd7iuD21s%3D)). | ## Enviar logs Em **Configurações**, clique em **Exportar Pacote de Diagnóstico (Logs)**. Os CNPJs saem mascarados. Na linha de comando, rode com `--verbose` e copie a saída. Abra a issue em [github.com/vasfvitor/nanci/issues](https://github.com/vasfvitor/nanci/issues). **Nunca** anexe certificado, senha, XMLs reais ou o banco. Falhas de segurança vão por e-mail, conforme o [SECURITY.md](https://github.com/vasfvitor/nanci/blob/main/SECURITY.md). --- # Desenvolvimento URL: https://nanci.abelhaninja.de/docs/desenvolvimento/ O Nanci é código aberto ([GPL-3.0](https://github.com/vasfvitor/nanci/blob/main/LICENSE)), em Go, com o desktop em [Wails](https://wails.io/) e Vue 3. A documentação para desenvolvedores fica no repositório: - [DEVELOPMENT.md](https://github.com/vasfvitor/nanci/blob/main/docs/DEVELOPMENT.md): ambiente, build e instalador. - [CONTRIBUTING.md](https://github.com/vasfvitor/nanci/blob/main/CONTRIBUTING.md): estrutura, padrões e testes. - [ARCHITECTURE.md](https://github.com/vasfvitor/nanci/blob/main/docs/ARCHITECTURE.md): pacotes e sincronização. - [NFSE_ADN.md](https://github.com/vasfvitor/nanci/blob/main/docs/NFSE_ADN.md), [NFE_SEFAZ.md](https://github.com/vasfvitor/nanci/blob/main/docs/NFE_SEFAZ.md) e [CTE_SEFAZ.md](https://github.com/vasfvitor/nanci/blob/main/docs/CTE_SEFAZ.md): cada integração.