Troubleshooting¶
Certificado não carrega¶
Sintoma comum:
NFSeCertificateError: Certificate file not foundNFSeCertificateError: Error loading certificatePrivate key not found in certificate
O que conferir:
caminho do arquivo em
cert_pathsenha do certificado
extensão real do arquivo,
.pfxou.p12se o arquivo tem chave privada embutida
permissões de leitura no ambiente onde a aplicação roda
PDF opcional não funciona¶
Se a geração local do DANFSe falhar, quase sempre falta o extra de PDF.
Instale com:
uv add "pynfse-nacional[pdf]"
O extra traz reportlab e qrcode. Sem ele, a biblioteca continua útil, só
sem a geração local do PDF.
A documentação não compila¶
Se sphinx-build reclamar, rode a partir do ambiente de docs:
uv sync --group docs
uv run sphinx-build -b html -W --keep-going docs site
Erros úteis para caçar:
links quebrados
docstrings com indentação ruim
páginas novas fora do
toctree
A API responde com erro estranho¶
Quando a SEFIN devolve algo diferente do esperado, confira primeiro:
ambiente usado no cliente
número da DPS
validade do certificado
se a nota já foi emitida e a aplicação perdeu a
chave_acesso
Quando o erro vier da própria biblioteca, use o error.code + error.message
para diagnosticar:
error.codeidentifica a categoria do problema de forma estávelerror.messagemensagem em Português do Brasilos códigos e as mensagens estão catalogados em Códigos de erro
Se o problema acontecer só em homologação, vale testar o mesmo fluxo em outro certificado de homologação. Às vezes o arquivo está válido mas o cadastro no ambiente não.