Metadata-Version: 2.4
Name: erpbrasil.edoc
Version: 3.2.0
Summary: Transmissão de documentos fiscais eletrônicos brasileiros (NF-e, NFC-e, CT-e, MDF-e, manifestação do destinatário e NFS-e)
Home-page: https://github.com/erpbrasil/erpbrasil.edoc
Author: Luis Felipe Mileo
Author-email: mileo@kmee.com.br
License: MIT
Project-URL: Documentation, https://github.com/erpbrasil/erpbrasil.edoc#readme
Project-URL: Changelog, https://github.com/erpbrasil/erpbrasil.edoc/blob/master/CHANGELOG.rst
Project-URL: Issue Tracker, https://github.com/erpbrasil/erpbrasil.edoc/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Unix
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Utilities
Requires-Python: >=3.5, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: erpbrasil.base>=2.0.0
Requires-Dist: erpbrasil.assinatura>=1.2.0
Requires-Dist: erpbrasil.transmissao>=1.0.0
Provides-Extra: nfselib-ginfes
Requires-Dist: nfselib.ginfes; extra == "nfselib-ginfes"
Provides-Extra: nfselib-paulistana
Requires-Dist: nfselib.paulistana; extra == "nfselib-paulistana"
Provides-Extra: nfselib-dsf
Requires-Dist: nfselib.dsf; extra == "nfselib-dsf"
Provides-Extra: nfselib-issnet
Requires-Dist: nfselib.issnet; extra == "nfselib-issnet"
Provides-Extra: nfselib-barueri
Requires-Dist: nfselib.barueri; extra == "nfselib-barueri"
Provides-Extra: nfelib
Requires-Dist: nfelib; extra == "nfelib"
Provides-Extra: mdfelib
Requires-Dist: nfelib; extra == "mdfelib"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

==============
erpbrasil.edoc
==============



Biblioteca Python para transmitir documentos fiscais eletrônicos brasileiros aos
webservices das SEFAZ e das prefeituras: monta a mensagem, assina, envia, consulta e
interpreta o retorno de NF-e, NFC-e, CT-e, MDF-e, manifestação do destinatário e NFS-e.

É a camada de transmissão da localização brasileira do Odoo
(`OCA/l10n-brazil <https://github.com/OCA/l10n-brazil>`_), e pode ser usada em qualquer
projeto Python. A assinatura digital vem da
`erpbrasil.assinatura <https://github.com/erpbrasil/erpbrasil.assinatura>`_ e o
transporte SOAP da `erpbrasil.transmissao <https://github.com/erpbrasil/erpbrasil.transmissao>`_.

O que a biblioteca faz
======================

.. list-table::
    :header-rows: 1
    :widths: 22 28 50

    * - Documento
      - Classe
      - Serviços
    * - NF-e (modelo 55)
      - ``erpbrasil.edoc.nfe.NFe``
      - status do serviço, autorização (síncrona e assíncrona) e consulta do recibo,
        consulta por chave, cancelamento, carta de correção, inutilização, consulta de
        cadastro, distribuição de DF-e
    * - NFC-e (modelo 65)
      - ``erpbrasil.edoc.nfce.NFCe``
      - os serviços da NF-e, autorização síncrona e QR Code
    * - Manifestação do destinatário
      - ``erpbrasil.edoc.mde.MDe``
      - ciência, confirmação, desconhecimento e operação não realizada
    * - CT-e
      - ``erpbrasil.edoc.cte.CTe``
      - status do serviço, autorização e consulta do recibo, consulta por chave,
        cancelamento, carta de correção, QR Code
    * - MDF-e
      - ``erpbrasil.edoc.mdfe.MDFe``
      - status do serviço, autorização e consulta do recibo, consulta por chave,
        cancelamento, encerramento, QR Code
    * - NFS-e
      - ``erpbrasil.edoc.provedores.cidades.NFSeFactory``
      - envio do lote de RPS, consulta do lote e da NFS-e, cancelamento (os serviços
        variam por provedor)

O endereço do webservice é escolhido pela UF (ou pela cidade, na NFS-e) e pelo ambiente:
``1`` produção e ``2`` homologação.

Provedores de NFS-e
~~~~~~~~~~~~~~~~~~~

A ``NFSeFactory`` escolhe o provedor pelo código IBGE da cidade do prestador. A tabela
traz as cidades homologadas.

.. list-table::
    :header-rows: 1
    :widths: 18 52 30

    * - Provedor
      - Cidades (código IBGE)
      - Bindings
    * - DSF
      - Belém-PA (1501402), Teresina-PI (2211001), Uberlândia-MG (3170206),
        Nova Iguaçu-RJ (3303500), Campinas-SP (3509502), Campo Grande-MS (5002704)
      - ``erpbrasil.edoc[nfselib.dsf]``
    * - Ginfes
      - Itajubá-MG (3132404), Franca-SP (3516200)
      - ``erpbrasil.edoc[nfselib.ginfes]``
    * - Paulistana
      - São Paulo-SP (3550308)
      - ``erpbrasil.edoc[nfselib.paulistana]``
    * - ISSNet
      - Ribeirão Preto-SP (3543402), Duque de Caxias-RJ (3301702)
      - ``erpbrasil.edoc[nfselib.issnet]``
    * - Barueri
      - Barueri-SP (3505708)
      - ``erpbrasil.edoc[nfselib.barueri]``

Outras cidades atendidas pelos mesmos provedores podem funcionar, mas não foram
homologadas. Para usar uma delas, inclua o código IBGE da cidade no dicionário
``cidades`` de ``erpbrasil.edoc.provedores.cidades`` e homologue o envio, as consultas e
o cancelamento antes de ir para produção; um PR com a cidade nova ajuda quem vier
depois. Também dá para registrar em tempo de execução, sem mudar a biblioteca:

.. code:: python

    from erpbrasil.edoc.provedores.cidades import cidades
    from erpbrasil.edoc.provedores.ginfes import Ginfes

    cidades[codigo_ibge] = Ginfes  # cidade atendida pelo Ginfes, ainda não homologada

Instalação
==========

.. code:: bash

    pip install erpbrasil.edoc

NF-e, NFC-e e manifestação do destinatário já funcionam com a instalação básica: as
bindings que elas usam vêm embutidas no pacote (``erpbrasil.nfelib_legacy``). Os demais
documentos pedem bindings externas, instaladas por extras:

.. code:: bash

    pip install "erpbrasil.edoc[nfelib]"              # CT-e e MDF-e
    pip install "erpbrasil.edoc[nfselib.paulistana]"  # NFS-e de São Paulo

Os extras de NFS-e seguem a tabela de provedores acima.

Como usar
=========

Status do serviço da NF-e em homologação, em São Paulo (código IBGE da UF ``35``):

.. code:: python

    from erpbrasil.assinatura.certificado import Certificado
    from erpbrasil.edoc.nfe import NFe
    from erpbrasil.transmissao import TransmissaoSOAP
    from requests import Session

    certificado = Certificado("certificado-a1.pfx", "senha-do-certificado")
    transmissao = TransmissaoSOAP(certificado, Session())
    nfe = NFe(transmissao, "35", versao="4.00", ambiente="2")

    processo = nfe.status_servico()
    print(processo.resposta.cStat, processo.resposta.xMotivo)

NFS-e pela fábrica de provedores:

.. code:: python

    from erpbrasil.edoc.provedores.cidades import NFSeFactory

    nfse = NFSeFactory(
        transmissao=transmissao,
        ambiente="2",
        cidade_ibge=3550308,
        cnpj_prestador="12345678000195",
        im_prestador="12345678",
    )
    processo = nfse.envia_documento(lote_rps)

``lote_rps`` é o objeto montado com as bindings do provedor (por exemplo,
``nfselib.paulistana``).

Quem monta a NF-e, a NFC-e, o CT-e ou o MDF-e com as bindings da
`nfelib <https://github.com/akretion/nfelib>`_ (xsdata) deve usar os adaptadores de
``nfelib.nfe.ws.edoc_legacy`` (``NFeAdapter``, ``NFCeAdapter``, ``CTeAdapter``,
``MDFeAdapter``, ``MDeAdapter``), que embrulham as classes desta biblioteca. É o caminho
usado pela localização OCA.

Desenvolvimento
===============

.. code:: bash

    pip install tox pre-commit
    pre-commit install
    tox -e py310   # testes (também py38 e py39)
    tox -e check   # metadados do pacote e o RST deste arquivo
    tox -e docs    # documentação, inclusive a verificação de links

Os testes que falam com webservices reproduzem respostas gravadas com o
`vcrpy <https://vcrpy.readthedocs.io/>`_ (``tests/fixtures/vcr_cassettes``). O ``tox``
fixa o ``vcrpy`` e o ``urllib3`` em versões que reproduzem esses cassetes: rodar o
``pytest`` fora do ``tox``, com versões mais novas, faz esses testes falharem com
``Invalid XML content received``.

Para combinar a cobertura de todos os ambientes do ``tox`` no Linux e no macOS:

.. code:: bash

    PYTEST_ADDOPTS=--cov-append tox

No Windows:

.. code:: bat

    set PYTEST_ADDOPTS=--cov-append
    tox

Publicação de uma versão
~~~~~~~~~~~~~~~~~~~~~~~~

1. Atualizar o ``CHANGELOG.rst``.
2. ``bump2version --no-tag patch`` (ou ``minor`` ou ``major``): atualiza a versão
   no ``setup.py``, neste arquivo, em ``docs/conf.py`` e em
   ``src/erpbrasil/edoc/__init__.py``.
3. Abrir o PR com o bump e mesclar com o CI verde.
4. Criar a Release ``vX.Y.Z`` no GitHub sobre o commit mesclado (ela cria a tag).

A Release dispara o workflow ``publish``, que gera o sdist e o wheel, confere se a
versão do pacote é a da tag e publica no PyPI. Não há token no repositório: o PyPI
aceita só este workflow, rodando no ambiente ``pypi`` (Trusted Publishing).

Para testar antes de anunciar, publique um release candidate (``X.Y.Zrc1``, com a
Release marcada como pré-release): o ``pip`` só instala pré-releases quando pedido
com ``--pre`` ou com a versão exata.

Créditos
========

Biblioteca criada pela `Akretion <https://akretion.com/>`_ e pela
`KMEE <https://www.kmee.com.br>`_ e mantida com a comunidade da localização brasileira,
com contribuições da `Engenere <https://github.com/Engenere>`_ e da
`Escodoo <https://www.escodoo.com.br>`_, entre outras empresas e pessoas. Veja a
`lista de contribuidores <https://github.com/erpbrasil/erpbrasil.edoc/graphs/contributors>`_.

Licença
=======

MIT, veja o arquivo ``LICENSE``.


Changelog
=========

0.0.0 (2019-09-23)
~~~~~~~~~~~~~~~~~~

* First release on PyPI.

1.0.0 (2020-11-21)
~~~~~~~~~~~~~~~~~~

* NF-e - Nota fiscal eletrônica;
    * Status Serviço;
    * Emissão;
    * Cancelamento;
    * Carta de correção;
    * Consulta Chave;
    * Consulta Distribuição;
    * Manifestação do Destinatário;
        * Confirmação de Operação;
        * Ciência de Operação;
        * Desconhecimento da operação;
        * Operação não realizada;
* MDF-e - Manifesto Eletrônico de Documentos Fiscais (Transporte):
    * Status Serviço;
    * Consulta Documento;
    * Consulta Não Encerrados;
    * Emissão;
    * Cancelamento;
* NFS-E - Base para o desenvolvimento de provedores:
    * Status Serviço;
    * Consulta Documento;
    * Consulta NFS-e / RPS;
    * Consulta Lote RPS;
    * Emissão;
    * Cancelamento;
    * Suporte ao provedor:
        * GINFES:
* Implementação de testes automatizados;

2.0.0 (2021-04-09)
~~~~~~~~~~~~~~~~~~

* Refatoração do módulo de NF-e

2.1.0 (2021-05-01)
~~~~~~~~~~~~~~~~~~

- Manifestação do Destinatário
- Consulta Cadastro

2.2.0 (2021-05-26)
~~~~~~~~~~~~~~~~~~

- Nota Paulistana

2.9.0 (2024-05-15)
~~~~~~~~~~~~~~~~~~

- Suporte para emissão de NF-e utilizando as Sefaz autorizadoras de contingência.

2.10.0 (2024-07-25)
~~~~~~~~~~~~~~~~~~~

- Ceará passa a usar o webservice da SVRS.
- URLs e expressão regular do Ginfes corrigidas.
- Leitura do retorno SOAP com um padrão combinado de prefixos.
- Versão da nfelib travada e erpbrasil.transmissao no requirements.

2.10.1 (2024-10-10)
~~~~~~~~~~~~~~~~~~~

- URL da SEFAZ MG corrigida.

3.0.0 (2024-12-06)
~~~~~~~~~~~~~~~~~~

- CT-e: status do serviço, envio, cancelamento, carta de correção e cteProc.
- MDF-e refatorado.
- NF-e e NFC-e: ``monta_qrcode``.
- Busca das URLs dos webservices refatorada.

3.1.0 (2025-11-08)
~~~~~~~~~~~~~~~~~~

- Bindings generateDS legados de NF-e, NFC-e e eventos embutidos em
  ``erpbrasil.nfelib_legacy``.
- MDF-e: RS na SVRS e ``get_service_url`` levanta erro para UF sem configuração.
- Manifestação do destinatário: endpoint de homologação corrigido.

3.1.1 (2026-01-08)
~~~~~~~~~~~~~~~~~~

- digVal: ``gds_format_base64`` converte bytes para texto.

3.2.0 (2026-10-05)
~~~~~~~~~~~~~~~~~~

Novidades:

- NFS-e Paulistana: schema v03 (Reforma Tributária) opcional, com
  ``versao_schema="v03"``; o v02 continua padrão e gera o mesmo XML (#101).
- NFS-e Barueri: consulta pelo protocolo, download do arquivo do lote e retorno
  da consulta com a situação e a mensagem (#93).
- Novo extra ``nfselib.barueri``.

Correções:

- ``assina_raiz`` não altera mais o XML depois de assinado, o que evitava a
  rejeição 297 com texto que tem quebra de linha (#97). No Ginfes o XML assinado
  continua sem quebras de linha, como até a 3.1.1.
- Reassinatura descarta a Signature anterior e declara ``xmlns:ds`` na
  exportação dos bindings legados (#99).
- CT-e e MDF-e: ``get_service_url`` aceita o ambiente como texto (#109). Quem
  passa ``"1"`` em texto, como a localização OCA na 14.0, transmitia o MDF-e
  para a homologação e passa a transmitir para a produção.
- CT-e: PR, MT, MS e MG usam a autorizadora própria e RS a SVRS (#110).
- MDF-e: todas as UFs autorizam na SVRS; MG, MS, MT e PR levantavam ValueError
  (#100).
- NF-e: caminhos da contingência SVC-RS em produção, que estavam trocados entre
  os serviços (AM, BA, GO, MA, MS, MT, PE, PI e PR).
- NF-e: o lote que volta já processado a um envio assíncrono (cStat 104, sem
  infRec), comum na contingência, não quebra mais o ``processar_documento`` com
  AttributeError depois da autorização; o processo é montado como no envio
  síncrono (#102).
- NF-e: consulta de cadastro do AM e do PE pelo CadConsultaCadastro4, como
  publica o Portal NF-e; a versão 2 dava 404 (#87).
- Barueri: ``analisa_retorno_consulta`` não levanta mais UnboundLocalError em
  retorno com erro.
- Os extras ``nfelib`` e ``mdfelib`` instalam a nfelib (apontavam para pacotes
  inexistentes); sai o extra ``nfselib.betha``.

Outros:

- README reescrito; descrição e links do pacote no PyPI.
- A Release do GitHub publica no PyPI (workflow ``publish``, Trusted Publishing).
- CI: py37 removido; zeep e requests por versão do Python (alertas de
  segurança); testes de Paulistana, ISSNet, chave, CT-e, MDF-e, contingência
  SVC-RS, Barueri e reassinatura.
