Metadata-Version: 2.5
Name: shade-plugins-nfe-distribuicao
Version: 0.1.0
Summary: XML das NF-e de entrada pelo webservice oficial de Distribuição de DF-e da SEFAZ (Ambiente Nacional), com o e-CNPJ de cada cliente.
Author: ShadeOne
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: cryptography>=44
Requires-Dist: lxml>=5
Requires-Dist: nfelib==3.3.0
Requires-Dist: shade-sdk<0.23,>=0.22.20
Description-Content-Type: text/markdown

# shade-plugins-nfe-distribuicao

Plugin do ShadeOne que baixa o XML das NF-e de entrada de cada cliente
pelo webservice oficial `NFeDistribuicaoDFe` do Ambiente Nacional (SEFAZ), com o e-CNPJ do próprio
cliente. Sem tela e sem captcha.

## Uso

No `shade.toml` do robô:

```toml
[hosts]
permitidos = ["www1.nfe.fazenda.gov.br"]

[certificado]
modo = "por_cnpj"
coluna = "cnpj"

[config]
nfe_distribuicao_ambiente = "producao"   # ou "homologacao" (hom1.nfe.fazenda.gov.br)
nfe_distribuicao_uf = "35"               # opcional: código IBGE da UF do autor

[plugins]
nfe-distribuicao = "0.1.0"
```

No robô:

```python
import shade_plugins_nfe_distribuicao as nfe

for nota in nfe.xmls_de_entrada(item["cnpj"]):
    if nota["completo"]:
        print(nota["chave"], nota["arquivo"])  # xmls_de_entrada/<chave>.xml, já anexado ao item
```

## `xmls_de_entrada(cnpj)`

Devolve as NF-e em que o CNPJ é destinatário, a partir do último NSU guardado. Cada item da lista
tem `chave`, `nsu`, `completo`, `xml` (bytes) e `arquivo`.

- **Só lê e anexa.** O plugin não manifesta o destinatário. O serviço entrega o XML completo da nota
  depois que o destinatário manifestou; as demais chegam como resumo (`completo` falso, sem `xml` nem `arquivo`). A Ciência da Operação é decisão de quem
  recebe a nota.
- **O último NSU fica guardado por CNPJ**, em `estado/nfe-distribuicao/` no diretório de trabalho, e
  só avança depois de os arquivos da página estarem no disco e anexados ao item. Uma queda no meio
  repete a página, nunca a perde, e a chamada seguinte baixa só o que é novo.
- **Limite de consumo.** Quem chega ao fim da fila só deve consultar de novo uma hora depois: antes
  disso a chamada devolve lista vazia sem ir à SEFAZ. Se a SEFAZ responder `cStat` 656, o plugin
  levanta `ConsumoIndevido` com `aguardar_ate` e guarda a espera; não repete na hora.
- **No ensaio** a consulta roda, mas nada é gravado nem anexado e o NSU não avança.
- Até 20 páginas (1.000 documentos) por chamada; o resto vem na chamada seguinte. Cada XML anexado
  respeita o teto de 8 MiB por arquivo do run.
- CNPJ de 14 dígitos numéricos; o certificado precisa ter o mesmo CNPJ-base.

## Erros

- `DistribuicaoIndisponivel`: falha técnica (SEFAZ fora do ar, sem resposta, resposta fora da forma).
  O laço do robô repete o item.
- `RecusaDaSefaz` (`ErroDeNegocio`): `motivo` é `certificado_recusado`, `certificado_de_outro_cnpj`,
  `nsu_invalido` ou `entrada_invalida`. Não repete.
- `ConsumoIndevido` (`ErroDeNegocio`): `aguardar_ate` diz quando consultar de novo.

As mensagens trazem o status e o código da SEFAZ, nunca o CNPJ, o certificado nem o corpo.

## Licença

Apache-2.0. O pedido e a resposta usam os bindings do [`nfelib`](https://pypi.org/project/nfelib/)
(MIT), gerados dos XSDs oficiais.
