Metadata-Version: 2.5
Name: shade-plugins-documentos-fiscais
Version: 0.1.0
Summary: Ler NF-e (XML e DANFE em PDF), conferir chave de acesso e decompor a linha digitável do boleto, offline.
Author: ShadeOne
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: pdfplumber<0.12,>=0.11
Requires-Dist: shade-sdk<0.23,>=0.12.0
Description-Content-Type: text/markdown

# shade-plugins-documentos-fiscais

Lê a NF-e (XML e DANFE em PDF), confere a chave de acesso e decompõe a linha digitável do boleto.
É um plugin do [`shade-sdk`](https://pypi.org/project/shade-sdk/); roda offline, sem credencial,
sem nenhuma operação com efeito e sem modelo de IA: só leitura e conta.

No `shade.toml` do robô:

```toml
[plugins]
documentos-fiscais = "0.1.0"
```

```python
import shade_plugins_documentos_fiscais as fiscais

nota = fiscais.nfe_xml("nota.xml")
nota["emitente"]["nome"], nota["totais"]["nota"], nota["chave"]

danfe = fiscais.nfe_danfe("danfe.pdf")          # os mesmos campos, do PDF
chave = fiscais.chave_de_acesso("3526 1011 2223 3300 0181 5500 1000 0001 2311 2345 6783")
boleto = fiscais.boleto("23793.45677 89012.345677 89012.345677 5 16360000123456")
boleto["banco"], boleto["valor"], boleto["vencimento"]
```

| Operação | O que faz |
| --- | --- |
| `chave_de_acesso(chave)` | Confere os 44 caracteres pelo dígito verificador (módulo 11; aceita o CNPJ alfanumérico) e devolve UF, mês da emissão, emitente (CNPJ ou CPF), modelo, série, número, tipo de emissão e código numérico. |
| `nfe_xml(caminho)` | Lê o `nfeProc`/`NFe` (layout 4.00): emitente, destinatário, itens, totais, protocolo. A chave do `Id` é conferida e tem de bater com a UF, o mês, o emitente, o modelo, a série e o número da própria nota. |
| `nfe_danfe(caminho)` | Os campos impressos no DANFE (texto, sem OCR), lidos pelo mesmo `pdfplumber` do plugin `pdf`. Não precisa declarar o `pdf` no `shade.toml`. |
| `boleto(codigo, referencia=None)` | Linha digitável de 47 dígitos ou código de barras de 44: banco, moeda, valor, vencimento, campo livre, e as duas formas do código. Confere os módulos 10 (três campos) e 11 (geral). |

- **Recusa com motivo:** o que não confere levanta `DocumentoInvalido` (um `ErroDeNegocio`: o item
  termina com falha, sem repetir) com `motivo`: `digito_verificador`, `tamanho`, `formato`, `uf`,
  `emissao`, `modelo`, `emitente`, `chave_diverge`, `protocolo_diverge`, `doctype`,
  `xml_malformado`, `nao_e_nfe`, `estrutura`, `chave_nao_encontrada`, `pdf_ilegivel`, `arrecadacao`.
- **XML seguro:** a NF-e não tem DOCTYPE. O arquivo que traz um é recusado (`doctype`) antes de
  qualquer entidade ser expandida: nenhuma entidade externa lê arquivo do disco, e a cascata de
  entidades não estoura a memória. O arquivo passa de 10 MB → recusado.
- **Valores:** dinheiro e quantidade saem em texto decimal (`"215.00"`), sem arredondar; o campo
  ausente é `None`.
- **Vencimento do boleto:** o fator volta ao 1000 a cada 9.000 dias (o 1000 é 22/02/2025). O
  vencimento é o do ciclo mais próximo da `referencia` (a data de hoje, se omitida); fator 0000 e
  valor zero saem `None` (sem vencimento, valor livre).
- **Limites:** boleto de arrecadação (48 dígitos: consumo e tributo) é recusado (`arrecadacao`).
  O DANFE só entrega, sempre, a chave e o que ela carrega; destinatário, totais e itens saem dos
  rótulos oficiais com o valor na linha de baixo e da tabela `DADOS DOS PRODUTOS / SERVIÇOS`, e o
  campo que o desenho do PDF não entrega sai `None` (o XML é a fonte completa). PDF só imagem
  (escaneado) não é lido.
