%global _empty_manifest_terminate_build 0
Name: python-bradocs4py
Version: 1.3.1.0
Release: 1
Summary: Implementa a funcionalidade validar_inscao_estadual.
License: MIT
URL: https://github.com/namio/BRADocs4Py.git
Source0: https://mirrors.aliyun.com/pypi/web/packages/55/d0/b448136daeec51703d557700540749d1ec7a4d734997b040c1d233e27ae1/bradocs4py-1.3.1.0.tar.gz
BuildArch: noarch
%description
[](https://pypi.org/project/bradocs4py/)
[](https://github.com/namio/BRADocs4Py.git)
[](https://pypi.org/project/bradocs4py/)
[](https://pypi.org/project/bradocs4py/)
[](https://pypi.org/project/bradocs4py/)
[](https://github.com/namio/BRADocs4Py/blob/master/LICENSE)
[](https://github.com/namio/BRADocs4Py.git)
[](https://saythanks.io/to/namio)
# BRADocs4Py
BRADocs4Py é uma biblioteca que visa fornecer componentes para trabalhar com tipos de dados específicos da realidade brasileira.
Esta biblioteca surgiu mediante a necessidade de se ter tipos específicos que possibilitem lidar com documentos de identificação próprios do Brasil, como é o caso do Cadastro de Pessoa Física (CPF) e do Cadastro Nacional de Pessoa Jurídica (CNPJ).
Além de conter classes que representam o modelo computacional dos principais documentos brasileiros, esta biblioteca também disponibiliza classes que permitem a validação e a geração de números válidos para estes documentos; sendo estas últimas disponibilizadas exclusivamente para fins de testes computacionais.
> This software is coded and documented in portuguese only as it is intended to be used to generate the necessary files for the brazilian government regarding to digital bookkeeping.
## Requisitos
* python
## Como instalar
$ pip install bradocs4py
## Objetivos do Projeto
A ideia inicial do projeto e unificar em uma única biblioteca módulos que permitam representar computacionalmente e validar documentos brasileiros - inicialmente CPF e CNPJ, além de permitir a geração de números válidos para estes documentos.
## Compatibilidade do Projeto
O projeto inicialmente suportará apenas Python 3.6.5+.
Outras linguagens de programação poderão ter versões especificas conforme minha disponibilidade de tempo.
## Status do Projeto
O projeto está em fase inicial de desenvolvimento.
| Módulo | Situação |
|:------------------------------------|:---------------:|
| [DocumentoIdentificacao](#di) |Funcional |
| [CPF](#cpf) |Funcional |
| [ValidadorCpf](#vcpf) |Funcional |
| [GeradorCpf](#gcpf) |Funcional |
| [Cnpj](#cnpj) |Funcional |
| [ValidadorCnpj](#vcnpj) |Funcional |
| [GeradorCnpj](#gcnpj) |Funcional |
| [InscricaoEstadual](#ie) |Funcional |
| [ValidadorInscricaoEstadual](#vie) |Funcional |
| [GeradorInscricaoEstadual](#gie) |Não implementado |
| [InscricaoSuframa](#is) |Funcional |
| [ValidadorSuframa](#vs) |Funcional |
| [GeradorSuframa](#gs) |Funcional |
| [ChaveAcessoNFe](#chave) |Funcional |
| [ValidadorChaveAcessoNFe](#vchave) |Funcional |
| [GeradorChaveAcessoNFe](#gchave) |Funcional |
| [GTIN](#gtin) |Funcional |
| [ValidadorGTIN](#vgtin) |Funcional |
| [GeradorGTIN](#ggtin) |Funcional |
### <a name="di"></a> DocumentoIdentificacao
Classe abstrata, não podendo ser instanciada diretamente, serve como base para todas as classes que representam um documento de identificação ou qualquer outro documento brasileiro que necessite de validação.
### <a name="cpf"></a> CPF
Classe usada para representar em código Pyhton um _Cadastro de Pessoa Física_ (CPF); permitindo representá-lo textualmente, com a devida formatação e identificar a sua validade.
#### Utilização
>>> cpf = CPF('52513127765')
>>> cpf
'525.131.277-65'
>>> cpf.isValid
True
>>> cpf.rawValue
52513127765
>>> cpf = CPF('abcdefghijk')
>>> cpf.isValid
False
>>> print(cpf)
abcdefghijk
>>> print(cpf.rawValue)
abcdefghijk
> Independente do conteúdo passado ao se criar uma instância de CPF, **sempre** obter-se-á uma instância deste. Caberá consultar a propriedade __isValid__ de uma instância de CPF para verificar se esta é válida ou não.
> A representação textual de uma instância de CPF só será exibida caso esta instância contenha um número válido de CPF; ao contrário será exibida a _string_ utilizada para criá-la.
> Para obter a _string_ utilizada ao instanciar um CPF, basta acessar a propriedade **rawValue** da instância criada.
### <a name="vcpf"></a> ValidadorCpf
Classe responsável por validar uma instância de CPF ou uma _string_ contendo a representação numérica de um CPF.
#### Utilização
>>> cpf = CPF('abcdefghijk')
>>> ValidadorCpf.validar(cpf)
False
>>> ValidadorCpf.validar('123.456.789-00')
False
Foi criado um CPF válido, porém foi digitado um caractere de separação diferente dos caracteres esperados (.-/ ). Mesmo assim, o validador informa tratar-se de um CPF correto
>>> cpf = CPF('508,697,212-40')
>>> ValidadorCpf.validar(cpf)
True
### <a name="gcpf"></a> GeradorCpf
Classe responsável por gerar aleatoriamente um CPF válido.
#### Utilização
>>> cpf = GeradorCpf.gerar()
>>> cpf.isValid
True
### <a name="cnpj"></a> Cnpj
Classe usada para representar em código Pyhton um _Cadastro Nacional de Pessoa Jurídica_ (CNPJ); permitindo representá-lo textualmente, com a devida formatação e identificar a sua validade.
#### Utilização
>>> cnpj = Cnpj('abcdefghijklmn')
>>> cnpj.isValid
False
>>> cnpj = Cnpj('12345678901234')
>>> cnpj.isValid
False
>>> cnpj = Cnpj('19.658.147/0001-0O')
>>> cnpj.isValid
False
>>> cnpj = Cnpj('19.658.147/0001-00')
>>> cnpj.isValid
True
> Independente do conteúdo passado ao se criar uma instância de CNPJ, **sempre** obter-se-á uma instância deste. Caberá consultar a propriedade __isValid__ de uma instância de CNPJ para verificar se esta é válida ou não.
> A representação textual de uma instância de CNPJ só será exibida caso esta instância contenha um número válido de CNPJ; ao contrário será exibida a _string_ utilizada para criá-la.
> Para obter a _string_ utilizada ao instanciar um CNPJ, basta acessar a propriedade **rawValue** da instância criada.
### <a name="vcnpj"></a> ValidadorCnpj
Classe responsável por validar uma instância de CNPJ ou uma _string_ contendo a representação numérica de um CNPJ.
#### Utilização
>>> cnpj = Cnpj('abcdefghijklmn')
>>> ValidadorCnpj.validar(cnpj)
False
>>> cnpj = Cnpj('19.658.147/0001-0O')
>>>ValidadorCnpj.validar(cnpj)
False
>>> ValidadorCnpj.validar('12345678901234')
False
>>> cnpj = Cnpj('34 633 423,0001/60')
>>> ValidadorCnpj.validar(cnpj)
True
>>> ValidadorCnpj.validar('05.692.744/0001-38')
True
### <a name="gcnpj"></a> GeradorCnpj
Classe responsável por gerar aleatoriamente um CNPJ válido.
#### Utilização
>>> cnpj = GeradorCnpj.gerar()
>>> cnpj.isValid
True
### <a name="is"></a> InscricaoSuframa
Representa o número de inscrição na Superintendência da Zona Franca de Manaus (SUFRAMA)
> A SUFRAMA mantém controle sobre as empresas com insentivo fiscal, identificando-as através do número de _Inscrição SUFRAMA_.
A composição deste indicador é: _SS.NNNN.LLD_, onde:
**SS** representa o __código do setor de atividade__ da empresa, conforme exemplo abaixo:
| Código | Descrição |
| :----: | :---------------------------|
| 01 e 02 | Cooperativa |
| 10 e 11 | Comércio |
| 20 | Indústria com projeto pleno |
| 60 | Serviços |
**NNNN** número sequencial
**LL** representa o código da licalidade da Unidade Administrativa da Suframa que habilitou a empresa, conforme exemplo abaixo:
| Código | Descrição |
| :----: | :-----------|
| 01 | Manaus |
| 10 | Boa Vista |
| 30 | Porto Velho |
**D** dígito verificador
#### Validação
* Campo numérico com 9 posições (incluindo o dígito verificador).
* Pode iniciar por 0 (zero), mas não pode iniciar por 00.
* Dígito verificador calculado por [__módulo 11__](https://pt.wikipedia.org/wiki/D%C3%ADgito_verificador#Módulo_11 "Método de cálculo do dígito verificador usando Módulo 11"), pesos 2 a 9.
#### Utilização
>>> x = InscricaoSuframa('01.1234.129')
>>> x.rawValue
'011234129'
>>> print(x)
01.1234.129
>>> x.isValid
False
>>> x = InscricaoSuframa('101580100')
>>> x.rawValue
'101580100'
>>> print(x)
10.1580.100
>>> x.isValid
True
>>> x = InscricaoSuframa('1015801OO')
>>> x.rawValue
'1015801OO'
>>> print(x)
1015801OO
>>> x.isValid
False
### <a name="vs"></a> ValidadorSuframa
Valida uma instância de InscricaoSuframa ou uma _string_ contendo a representação numérica de uma Inscrição Suframa.
#### Utilização
# Validação de uma _string_ representando uma Inscrição Suframa:
>>> ValidadorSuframa.validar('101580100')
True
# Validação de uma _string_ representando uma Inscrição Suframa inválida (contendo caracteres não numéricos):
>>> ValidadorSuframa.validar('1015801OO')
False
# Validação de uma instância de InscriçãoSuframa:
>>> x = InscricaoSuframa('01.1234.129')
>>> ValidadorSuframa.validar(x)
False
### <a name="gs"></a> GeradorSuframa
Gera aleatoriamente uma Inscrição Suframa válida
>>> x = GeradorSuframa.gerar()
>>> x.isValid
True
> **IMPORTANTE**: O __GeradorSuframa__ tem por objetivo ajudar estudantes, programadores, analistas de sistemas e testadores de código a gerar Inscrições Suframa válidas visando auxiliar as rotinas de testes de softwares em desenvolvimento.
> A má utilização dos dados gerados pelo __GeradorSuframa__ é de **total responsabilidade do usuário** desta biblioteca.
> As inscrições são geradas de forma aleatória, respeitando as leis de formação estabelecidas pela SUFRAMA.
### <a name="ie"></a> InscricaoEstadual
Representa, em código Pyhton, uma _Inscrição Estadual_ (IE), ou o registro do contribuinte no cadastro do ICMS mantido pela Receita Estadual; permitindo representá-lo textualmente, com a devida formatação e identificar a sua validade.
#### Utilização
>>> ie = InscricaoEstadual('613.855.219.926', 'SP')
>>> ie.isValid
True
>>> ie.rawValue
'613855219926'
>>> ie.UF
'SP'
>>> print(ie)
613.855.219.926
### <a name="vie"></a> ValidadorInscricaoEstadual
Valida a consistência de uma instância de InscricaoEstadual ou uma _string_ contendo a representação numérica de uma Inscrição Estadual para uma determinada Unidade da Federação, informada juntamente com a representação numérica da IE a qual se deseja validar.
> A validação da Inscrição Estadual para cada Unidade da Federação brasileira, leva em consideração o disposto no [__Convênio 57/59__](http://www.sintegra.gov.br/conv_5795.html "ConvênioICMS 57/59"), como também as orientações e especificidades contidas na página [Conferências de Inscrições Estaduais](http://www.sintegra.gov.br/insc_est.html "Conferência de Inscrições Estaduais") do SINTEGRA.
#### Utilização
>>> ie = InscricaoEstadual('613.855.219.926', 'SP')
>>> ValidadorInscricaoEstadual.validar(ie)
True
>>> ValidadorInscricaoEstadual.validarStr('207653461', 'RN')
True
>>> ValidadorInscricaoEstadual.validarStr('209564598', 'TO')
False
> **NOTA**: Caso não se deseje utilizar o __ValidadorInscricaoEstadual__, pode-se utilizar o validador específico para uma determinada Unidade da Federação.
<p>Cada Unidade da Federação brasileira possui o seu próprio validador, definido por: **Validador**XX, onde _XX_ deve ser substituído pela sigla da Unidade da Federação desejada.</p>
<p>O Exemplo a seguir mostra como utilizar somente o validador específico para o Ceará, visando validar uma Inscrição Estadual deste Estado:</p>
>>> from bradocs4py.validadoresie import ValidadorCE
>>> ValidadorCE.validar('1234567')
False
>>> ValidadorCE.validar('50374156-6')
True
> **IMPORTANTE**: Ao contrário de ValidadorInscricaoEstadual, os validadores específicos de cada UF validam somente uma cadeia de caracteres (_string_) contendo o número representativo da Inscrição Estadual a ser validada.
### <a name="chave"></a> ChaveAcessoNFe
Representa a **Chave de Acesso** de uma Nota Fiscal Eletrônica.
#### <a name="lfchave"></a> Lei de formação de uma Chave de Acesso de NF-e
A Chave de Acesso da Nota Fiscal Eletrônica é representada por uma sequência de 44 caracteres numéricos, devendo ser composta pelos seguintes campos que se encontram dispersos no Layout da NF-e:
* UF - Código da UF do emitente do Documento Fiscal
* AAMM - Ano e mês da emissão da NF-e
* CNPJ - CNPJ do emitente do Documento Fiscal
* Modelo - Modelo do Documento Fiscal
* Série - Série do Documento Fiscal
* Número - Número do Documento Fiscal
* Forma Emissão - Forma de emissão do Documento Fiscal
* Código Numérico - Código numérico que compõe a Chave de Acesso
* DV - Dígito verificados
| Código | UF | AAMM | CNPJ | Modelo | Série | Número | Forma Emissão | Código Numérico | DV |
| :--------:|:----:|:----:|:----:|:------:|:-----:|:------:|:-------------:|:---------------:|:----:|
|Quantidade de caracteres |02 |04 |14 |02 |03 |09 |01 |08 |01 |
#### Utilização
>>> ca = ChaveAcessoNFe('23 1811 06850713000120 55 001 001766829 1 11103011 2')
>>> ca
<BRADocs4Py.bradocs4py.chaveacessonfe.ChaveAcessoNFe('23181106850713000120550010017668291111030112')>
>>> print(ca)
2318 1106 8507 1300 0120 5500 1001 7668 2911 1103 0112
>>> ca.rawValue
'23181106850713000120550010017668291111030112'
>>> ca.isValid
True
### <a name="vchave"></a> ValidadorChaveAcessoNFe
Valida a consistência e a integridade de uma instância de [ChaveAcessoNFe](#chave) ou uma _string_ contendo a representação numérica de uma Chave de Acesso, através do cálculo de seu _dígito verificador_.
> O **Dígito Verificador** (DV) visa garantir a integridade da Chave de Acesso, protegendo-a principalmente contra digitações erradas.
#### Utilização
>>> chave = ChaveAcessoNFe(35181298957205000164667451830925015791400679)
>>> validarChaveAcessoNFe(chave)
True
>>> ValidadorChaveAcessoNFe.validar(52060433009911002506550120000007800267301615)
True
>>> ValidadorChaveAcessoNFe.validar('52060433009911002506550120000007800267301615')
True
>>> ValidadorChaveAcessoNFe.validar('52060433009911002506550120000007800267301625')
False
ou
>>> validarChaveAcessoNFe(52060433009911002506550120000007800267301615)
True
>>> validarChaveAcessoNFe('52060433009911002506550120000007800267301615')
True
>>> validarChaveAcessoNFe('52060433009911002506550120000007800267301625')
False
>>> validarChaveAcessoNFe(chave)
True
#### <a name="dvchave"></a> Cálculo do dígito verificador
O dígito verificador da chave de acesso da NF-e é baseado em um cálculo do módulo 11. O módulo 11 de um número é calculado multiplicando-se cada algarismo pela sequência de multiplicadores 2,3,4,5,6,7,8,9,2,3, ..., posicionados da direita para a esquerda.
A somatória dos resultados das ponderações dos algarismos é dividida por 11 e o DV (dígito verificador) será a diferença entre o divisor (11) e o resto da divisão:
DV = 11 - (resto da divisão)
> Quando o resto da divisão for 0 (zero) ou 1 (um), o DV deverá ser igual a 0 (zero).
Exemplo: consideremos a seguinte chave de acesso: _52060433009911002506550120000007800267301615_
Isolando o _dígito verificador_, temos: _5206043300991100250655012000000780026730161_
|**Chave** | 5 | 2 | 0 | 6 | 0 | 4 | 3 | 3 | 0 | 0 | 9 | 9 | 1 | 1 | 0 | 0 | 2 | 5 | 0 | 6 | 5 | 5 | 0 | 1 | 2 | 0 | 0 | 0 | 0 | 0 | 0 | 7 | 8 | 0 | 0 | 2 | 6 | 7 | 3 | 0 | 1 | 6 | 1 |
|:------------------------|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
|**Pesos** | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 |
|**Ponderação** |20 | 6 | 0 |54 | 0 |28 |18 |15 | 0 | 0 |18 |81 | 8 | 7 | 0 | 0 | 8 |15 | 0 |54 |40 |35 | 0 | 5 | 8 | 0 | 0 | 0 | 0 | 0 | 0 |35 |32 | 0 | 0 |18 |48 |49 |18 | 0 | 4 |18 | 2 |
**Somatório das ponderações**: _644_
Dividindo o somatório das ponderações por **11**, temos: 644/11 = 58, restando **6**
Como o dígito verificador (DV) = 11 - (resto da divisão), temos: **11 - 6 = 5**
Neste caso o DV da chave de acesso da NF-e é igual a "5".
#### <a name="consistenciachave"></a> Verificação da _consistência_ da Chave de Acesso
Por ter uma [lei de formação](#lfchave) peculiar, o _[ValidadorChaveAcessoNFe](#vchave)_ verifica a consistência de uma determinada chave de acesso, observando:
* se os dois primeiros dígitos correspondem ao código, segundo o IBGE, de uma Unidade da Federação Brasileira;
* Se a data de emissão (**mês** e **ano**) *ano* de emissão não é **posterior** à data (mês e ano) atual;
* Se o *mês* de emissão, que corresponde ao terceiro par de dígitos, corresponde ao valor de um dos meses do ano;
* Se o *CNPJ* do emitente corresponde a um número de CNPJ válido.
> Desta forma, para que uma chave de acesso de NF-e seja válida, esta deverá passar pelo cálculo do Dígito Verificador e pelo teste de consistência.
### <a name="gchave"></a> GeradorChaveAcessoNFe
Gera uma [Chave de Acesso de NF-e](#chave) válida.
A chave gerada pelo [GeradorChaveAcessoNFe](#gchave) obedece às [regras de consistência](#consistenciachave) anteriormente citadas.
#### Utilização
>>> chave = GeradorChaveAcessoNFe.gerar()
>>> chave
<BRADocs4Py.bradocs4py.chaveacessonfe.ChaveAcessoNFe('25181230173834000160651227059459841838300521')>
>>> print(chave)
2518 1230 1738 3400 0160 6512 2705 9459 8418 3830 0521
>>> chave.rawValue
'25181230173834000160651227059459841838300521'
>>> chave.isValid
True
OU
>>> chave = gerarChaveAcessoNFe
>>> chave
<BRADocs4Py.bradocs4py.chaveacessonfe.ChaveAcessoNFe('11181205001709000125650428522143493956800409')>
>>> print(chave)
1118 1205 0017 0900 0125 6504 2852 2143 4939 5680 0409
>>> chave.rawValue
'11181205001709000125650428522143493956800409'
>>> chave.isValid
True
É possível passar para o gerador qualquer um dos seguintes parâmetros, ou combinação deles:
* UF - [Gera de uma chave de acesso para uma determinada Unidade da Federação](#gchaveUF) Brasileira
* anoEmissao - [Gera uma chave de acesso para um determinado ano de emissão](#gchaveAno)
* mesEmissao - [Gera uma chave de acesso para um determinado mês de emissão](#gchaveMes)
* cnpjEmitente - [Gera uma chave de acesso informando o CNPJ do emitente](#gchaveCNPJ)
* modelo - [Gera uma chame de acesso informando o modelo do documento fiscal](#gchaveModelo)
* serie - [Gera uma chave de acesso informando a série do Documento Fiscal](#gchaveSerie)
* numero - [Gera uma chave de acesso informando o núemro do Documento Fiscal](#gchaveNumero)
* formaEmissao - [Gera uma chave de acesso informando o tipo de emissão da NF-e](#gchaveEmissao)
##### <a name="gchaveUF"></a> Gerar uma chave de acesso para uma determinada Unidade da Federação (23 - Ceará):
>>> chave = GeradorChaveAcessoNFe.gerar(UF=23)
>>> chave.rawValue
'23181200840039000117652898295631409915000755'
##### <a name="gchaveAno"></a> Gerar uma chave de acesso para um determinado ano:
>>> chave = GeradorChaveAcessoNFe.gerar(anoEmissao=2015)
>>> chave.rawValue
'23151289106950000109651490922639616463100456'
##### <a name="gchaveMes"></a> Gerar uma chave de acesso para um determinado mês:
>>> chave = GeradorChaveAcessoNFe.gerar(mesEmissao=8)
>>> chave.rawValue
'15180853477826000102655678711686215463600041'
##### <a name="gchaveMesAno"></a> Gerar uma chave de acesso para uma determinada data (mês e ano) de emissão:
>>> chave = GeradorChaveAcessoNFe.gerar(anoEmissao=2015, mesEmissao=1)
>>> chave.rawValue
'29150139480855000100653317092547617382300904'
##### <a name="gchaveCNPJ"></a> Gerar uma chave de acesso informando o CNPJ do emitente:
>>> chave = GeradorChaveAcessoNFe.gerar(cnpjEmitente='64802611000136')
>>> chave.rawValue
'13181264802611000136651456599176257515300837'
##### <a name="gchaveModelo"></a> Gerar uma chave de acesso de uma NF-e, utilizada nas operações de venda no varejo (modelo de documento fiscal = 55)
>>> chave = GeradorChaveAcessoNFe.gerar(modelo=55)
>>> chave.rawValue
'27181282761929000106555079534095503558300935'
##### <a name="gchaveSerie"></a> Gerar uma chave de acesso para uma NF-e que não possui série:
>>> chave = GeradorChaveAcessoNFe.gerar(serie=0)
>>> chave.rawValue
'13181202699369000160650006987155021599900654'
> Nota: A série também pode ser informada como uma cadeia de caracteres numéricos. No exemplo acima, poderia ter sido informado **'000'** para _serie_.
##### <a name="gchaveNumero"></a> Gerar uma chave de acesso informando o número do documento fiscal:
>>> chave = GeradorChaveAcessoNFe.gerar(numero=1766829)
>>> chave.rawValue
'23181241761925000132652850017668297691400378'
##### <a name="gchaveEmissao"></a> Gerar uma chave de acesso para uma NF-e emitida com Contingência FS-IA, com impressão do DANFE em formulário de segurança (Tipo de emissã0 = 2)
>>> chave = GeradorChaveAcessoNFe.gerar(formaEmissao=2)
>>> chave.rawValue
'51181278981604000153656457693627102018200143'
Isto posto, desejando-se criar uma chave de acesso emitida no Ceará (Código IBGE=23) em Maio de 2016, para o CNPJ 64802611/0001-36, teríamos:
>>> chave = GeradorChaveAcessoNFe.gerar(formaEmissao=2, UF=23, anoEmissao=2016, mesEmissao=5, cnpjEmitente=64802611000136)
>>> chave.rawValue
'23160564802611000136554038699639442073100081'
>>> chave.isValid
True
> **Atenção**: a forma abreviada do gerador _(gerarChaveAcessoNFe)_ não permite a passagem de parâmetros.
### <a name="gtin"></a>GTIN
Representa um Número Global do Item Comercial - Global Trade Item Number (GTIN)
O GTIN é um identificador para itens comerciais desenvolvido e controlado pela [GS1][gs1], antiga EAN/UCC. Os GTINs,
anteriormente chamados de códigos EAN, são atribuídos para qualquer item (produto ou serviço) que pode ser
precificado, pedido ou faturado em qualquer ponto da cadeia de suprimentos. O GTIN é utilizado para recuperar
informação pré-definida e abrange desde as matérias primas até produtos acabados. GTIN é um termo “guarda-chuva”
para descrever toda a família de identificação das estruturas de dados GS1 para itens comerciais (produtos e serviços).
Os GTINs podem ter o tamanho de 8, 12, 13 ou 14 dígitos e podem ser construídos utilizando qualquer uma das quatro
estruturas de numeração dependendo da aplicação. O GTIN-8 é codificado no código de barras EAN-8. O GTIN-12 é mais
utilizado no código de barras UPC-A, o GTIN-13 é codificado no EAN-13 e o GTIN-14 no ITF-14.
#### Utilização
##### Criando uma instância de [GTIN](#gtin) a partir de um inteiro
>>> gtin = GTIN(6291041500213)
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-13 '6291041500213')>
>>> gtin.rawValue
'6291041500213'
>>> gtin.isValid
True
##### Criando uma instância de [GTIN](#gtin) a partir de uma cadeia de caracteres numéricos
>>> gtin = GTIN('35723189')
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-8 '35723189')>
>>> gtin.rawValue
'35723189'
>>> gtin.isValid
True
### <a name="vgtin"></a> ValidadorGTIN
Valida uma instância de GTIN, um inteiro ou uma cadeia de caracteres numéricos que representa um GTIN, a partir do [cálculo de seu dígito verificador][calculo-digito-gtin], o qual assegura a sua integridade.
> Nota: Muito embora o ValidadorGTIN valide uma instância de GTIN, a validação desta instância pode ser verificada através da sua propriedade _isValid_, conforme exemplos acima.
#### Utilização
>>> gtin = GTIN('35723189')
>>> ValidadorGTIN.validar(gtin)
True
>>> ValidadorGTIN.validar('3572318')
False
>>> ValidadorGTIN.validar('35723189')
True
>>> ValidadorGTIN.validar(6291041500213)
True
>>> ValidadorGTIN.validar('62910415OO213')
False
**OU**
>>> gtin = GTIN('35723189')
>>> validar_gtin(gtin)
True
>>> validar_gtin('3572318')
False
>>> validar_gtin('35723189')
True
>>> validar_gtin(6291041500213)
True
>>> validar_gtin('62910415OO213')
False
### <a name="ggtin"></a> GeradorGTIN
Gera uma instância de um [GTIN](#gtin) válido.
>IMPORTANTE: Este gerador de GTIN tem como intenção ajudar estudantes, programadores, analistas e testadores de sistemas computacionais a gerar GTINs válidas. Normalmente necessárias parar testar seus softwares em desenvolvimento. A má utilização dos dados aqui gerados é de total responsabilidade do usuário. Os números são gerados de forma aleatória, respeitando as regras de criação de um GTIN.
#### Utilização
>>> gtin = GeradorGTIN.gerar()
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-8 '93490399')>
**ou**
>>> gtin = gerar_gtin()
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-8 '33409382')>
É possível informar ao gerador o tipo de GTIN que se deseja gerar. Para isso, deve-se passar o _GeradorGTIN.TipoGTIN_ desejado.
##### Para gerar um GTIN-8
>>> gtin = GeradorGTIN.gerar(GeradorGTIN.TipoGTIN.GTIN8)
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-8 '33409382')>
Também é possível gerar GTINs chamando diretamente _gerar_gtin_:
>>> gtin = gerar_gtin(GeradorGTIN.TipoGTIN.GTIN13)
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-13 '4332497941617')>
Utilize:
* GeradorGTIN.TipoGTIN.GTIN8 para gerar GTIN-8
* GeradorGTIN.TipoGTIN.GTIN12 para gerar GTIN-12
* GeradorGTIN.TipoGTIN.GTIN13 para gerar GTIN-13, ou
* GeradorGTIN.TipoGTIN.GTIN14 para gerar GTIN-14
> Se não for passado nenhum tipo para o gerador, este gerará sempre um GTIN-8.
[gs1]: https://www.gs1br.org
[calculo-digito-gtin]: https://www.gs1.org/services/how-calculate-check-digit-manually
%package -n python3-bradocs4py
Summary: Implementa a funcionalidade validar_inscao_estadual.
Provides: python-bradocs4py
BuildRequires: python3-devel
BuildRequires: python3-setuptools
BuildRequires: python3-pip
%description -n python3-bradocs4py
[](https://pypi.org/project/bradocs4py/)
[](https://github.com/namio/BRADocs4Py.git)
[](https://pypi.org/project/bradocs4py/)
[](https://pypi.org/project/bradocs4py/)
[](https://pypi.org/project/bradocs4py/)
[](https://github.com/namio/BRADocs4Py/blob/master/LICENSE)
[](https://github.com/namio/BRADocs4Py.git)
[](https://saythanks.io/to/namio)
# BRADocs4Py
BRADocs4Py é uma biblioteca que visa fornecer componentes para trabalhar com tipos de dados específicos da realidade brasileira.
Esta biblioteca surgiu mediante a necessidade de se ter tipos específicos que possibilitem lidar com documentos de identificação próprios do Brasil, como é o caso do Cadastro de Pessoa Física (CPF) e do Cadastro Nacional de Pessoa Jurídica (CNPJ).
Além de conter classes que representam o modelo computacional dos principais documentos brasileiros, esta biblioteca também disponibiliza classes que permitem a validação e a geração de números válidos para estes documentos; sendo estas últimas disponibilizadas exclusivamente para fins de testes computacionais.
> This software is coded and documented in portuguese only as it is intended to be used to generate the necessary files for the brazilian government regarding to digital bookkeeping.
## Requisitos
* python
## Como instalar
$ pip install bradocs4py
## Objetivos do Projeto
A ideia inicial do projeto e unificar em uma única biblioteca módulos que permitam representar computacionalmente e validar documentos brasileiros - inicialmente CPF e CNPJ, além de permitir a geração de números válidos para estes documentos.
## Compatibilidade do Projeto
O projeto inicialmente suportará apenas Python 3.6.5+.
Outras linguagens de programação poderão ter versões especificas conforme minha disponibilidade de tempo.
## Status do Projeto
O projeto está em fase inicial de desenvolvimento.
| Módulo | Situação |
|:------------------------------------|:---------------:|
| [DocumentoIdentificacao](#di) |Funcional |
| [CPF](#cpf) |Funcional |
| [ValidadorCpf](#vcpf) |Funcional |
| [GeradorCpf](#gcpf) |Funcional |
| [Cnpj](#cnpj) |Funcional |
| [ValidadorCnpj](#vcnpj) |Funcional |
| [GeradorCnpj](#gcnpj) |Funcional |
| [InscricaoEstadual](#ie) |Funcional |
| [ValidadorInscricaoEstadual](#vie) |Funcional |
| [GeradorInscricaoEstadual](#gie) |Não implementado |
| [InscricaoSuframa](#is) |Funcional |
| [ValidadorSuframa](#vs) |Funcional |
| [GeradorSuframa](#gs) |Funcional |
| [ChaveAcessoNFe](#chave) |Funcional |
| [ValidadorChaveAcessoNFe](#vchave) |Funcional |
| [GeradorChaveAcessoNFe](#gchave) |Funcional |
| [GTIN](#gtin) |Funcional |
| [ValidadorGTIN](#vgtin) |Funcional |
| [GeradorGTIN](#ggtin) |Funcional |
### <a name="di"></a> DocumentoIdentificacao
Classe abstrata, não podendo ser instanciada diretamente, serve como base para todas as classes que representam um documento de identificação ou qualquer outro documento brasileiro que necessite de validação.
### <a name="cpf"></a> CPF
Classe usada para representar em código Pyhton um _Cadastro de Pessoa Física_ (CPF); permitindo representá-lo textualmente, com a devida formatação e identificar a sua validade.
#### Utilização
>>> cpf = CPF('52513127765')
>>> cpf
'525.131.277-65'
>>> cpf.isValid
True
>>> cpf.rawValue
52513127765
>>> cpf = CPF('abcdefghijk')
>>> cpf.isValid
False
>>> print(cpf)
abcdefghijk
>>> print(cpf.rawValue)
abcdefghijk
> Independente do conteúdo passado ao se criar uma instância de CPF, **sempre** obter-se-á uma instância deste. Caberá consultar a propriedade __isValid__ de uma instância de CPF para verificar se esta é válida ou não.
> A representação textual de uma instância de CPF só será exibida caso esta instância contenha um número válido de CPF; ao contrário será exibida a _string_ utilizada para criá-la.
> Para obter a _string_ utilizada ao instanciar um CPF, basta acessar a propriedade **rawValue** da instância criada.
### <a name="vcpf"></a> ValidadorCpf
Classe responsável por validar uma instância de CPF ou uma _string_ contendo a representação numérica de um CPF.
#### Utilização
>>> cpf = CPF('abcdefghijk')
>>> ValidadorCpf.validar(cpf)
False
>>> ValidadorCpf.validar('123.456.789-00')
False
Foi criado um CPF válido, porém foi digitado um caractere de separação diferente dos caracteres esperados (.-/ ). Mesmo assim, o validador informa tratar-se de um CPF correto
>>> cpf = CPF('508,697,212-40')
>>> ValidadorCpf.validar(cpf)
True
### <a name="gcpf"></a> GeradorCpf
Classe responsável por gerar aleatoriamente um CPF válido.
#### Utilização
>>> cpf = GeradorCpf.gerar()
>>> cpf.isValid
True
### <a name="cnpj"></a> Cnpj
Classe usada para representar em código Pyhton um _Cadastro Nacional de Pessoa Jurídica_ (CNPJ); permitindo representá-lo textualmente, com a devida formatação e identificar a sua validade.
#### Utilização
>>> cnpj = Cnpj('abcdefghijklmn')
>>> cnpj.isValid
False
>>> cnpj = Cnpj('12345678901234')
>>> cnpj.isValid
False
>>> cnpj = Cnpj('19.658.147/0001-0O')
>>> cnpj.isValid
False
>>> cnpj = Cnpj('19.658.147/0001-00')
>>> cnpj.isValid
True
> Independente do conteúdo passado ao se criar uma instância de CNPJ, **sempre** obter-se-á uma instância deste. Caberá consultar a propriedade __isValid__ de uma instância de CNPJ para verificar se esta é válida ou não.
> A representação textual de uma instância de CNPJ só será exibida caso esta instância contenha um número válido de CNPJ; ao contrário será exibida a _string_ utilizada para criá-la.
> Para obter a _string_ utilizada ao instanciar um CNPJ, basta acessar a propriedade **rawValue** da instância criada.
### <a name="vcnpj"></a> ValidadorCnpj
Classe responsável por validar uma instância de CNPJ ou uma _string_ contendo a representação numérica de um CNPJ.
#### Utilização
>>> cnpj = Cnpj('abcdefghijklmn')
>>> ValidadorCnpj.validar(cnpj)
False
>>> cnpj = Cnpj('19.658.147/0001-0O')
>>>ValidadorCnpj.validar(cnpj)
False
>>> ValidadorCnpj.validar('12345678901234')
False
>>> cnpj = Cnpj('34 633 423,0001/60')
>>> ValidadorCnpj.validar(cnpj)
True
>>> ValidadorCnpj.validar('05.692.744/0001-38')
True
### <a name="gcnpj"></a> GeradorCnpj
Classe responsável por gerar aleatoriamente um CNPJ válido.
#### Utilização
>>> cnpj = GeradorCnpj.gerar()
>>> cnpj.isValid
True
### <a name="is"></a> InscricaoSuframa
Representa o número de inscrição na Superintendência da Zona Franca de Manaus (SUFRAMA)
> A SUFRAMA mantém controle sobre as empresas com insentivo fiscal, identificando-as através do número de _Inscrição SUFRAMA_.
A composição deste indicador é: _SS.NNNN.LLD_, onde:
**SS** representa o __código do setor de atividade__ da empresa, conforme exemplo abaixo:
| Código | Descrição |
| :----: | :---------------------------|
| 01 e 02 | Cooperativa |
| 10 e 11 | Comércio |
| 20 | Indústria com projeto pleno |
| 60 | Serviços |
**NNNN** número sequencial
**LL** representa o código da licalidade da Unidade Administrativa da Suframa que habilitou a empresa, conforme exemplo abaixo:
| Código | Descrição |
| :----: | :-----------|
| 01 | Manaus |
| 10 | Boa Vista |
| 30 | Porto Velho |
**D** dígito verificador
#### Validação
* Campo numérico com 9 posições (incluindo o dígito verificador).
* Pode iniciar por 0 (zero), mas não pode iniciar por 00.
* Dígito verificador calculado por [__módulo 11__](https://pt.wikipedia.org/wiki/D%C3%ADgito_verificador#Módulo_11 "Método de cálculo do dígito verificador usando Módulo 11"), pesos 2 a 9.
#### Utilização
>>> x = InscricaoSuframa('01.1234.129')
>>> x.rawValue
'011234129'
>>> print(x)
01.1234.129
>>> x.isValid
False
>>> x = InscricaoSuframa('101580100')
>>> x.rawValue
'101580100'
>>> print(x)
10.1580.100
>>> x.isValid
True
>>> x = InscricaoSuframa('1015801OO')
>>> x.rawValue
'1015801OO'
>>> print(x)
1015801OO
>>> x.isValid
False
### <a name="vs"></a> ValidadorSuframa
Valida uma instância de InscricaoSuframa ou uma _string_ contendo a representação numérica de uma Inscrição Suframa.
#### Utilização
# Validação de uma _string_ representando uma Inscrição Suframa:
>>> ValidadorSuframa.validar('101580100')
True
# Validação de uma _string_ representando uma Inscrição Suframa inválida (contendo caracteres não numéricos):
>>> ValidadorSuframa.validar('1015801OO')
False
# Validação de uma instância de InscriçãoSuframa:
>>> x = InscricaoSuframa('01.1234.129')
>>> ValidadorSuframa.validar(x)
False
### <a name="gs"></a> GeradorSuframa
Gera aleatoriamente uma Inscrição Suframa válida
>>> x = GeradorSuframa.gerar()
>>> x.isValid
True
> **IMPORTANTE**: O __GeradorSuframa__ tem por objetivo ajudar estudantes, programadores, analistas de sistemas e testadores de código a gerar Inscrições Suframa válidas visando auxiliar as rotinas de testes de softwares em desenvolvimento.
> A má utilização dos dados gerados pelo __GeradorSuframa__ é de **total responsabilidade do usuário** desta biblioteca.
> As inscrições são geradas de forma aleatória, respeitando as leis de formação estabelecidas pela SUFRAMA.
### <a name="ie"></a> InscricaoEstadual
Representa, em código Pyhton, uma _Inscrição Estadual_ (IE), ou o registro do contribuinte no cadastro do ICMS mantido pela Receita Estadual; permitindo representá-lo textualmente, com a devida formatação e identificar a sua validade.
#### Utilização
>>> ie = InscricaoEstadual('613.855.219.926', 'SP')
>>> ie.isValid
True
>>> ie.rawValue
'613855219926'
>>> ie.UF
'SP'
>>> print(ie)
613.855.219.926
### <a name="vie"></a> ValidadorInscricaoEstadual
Valida a consistência de uma instância de InscricaoEstadual ou uma _string_ contendo a representação numérica de uma Inscrição Estadual para uma determinada Unidade da Federação, informada juntamente com a representação numérica da IE a qual se deseja validar.
> A validação da Inscrição Estadual para cada Unidade da Federação brasileira, leva em consideração o disposto no [__Convênio 57/59__](http://www.sintegra.gov.br/conv_5795.html "ConvênioICMS 57/59"), como também as orientações e especificidades contidas na página [Conferências de Inscrições Estaduais](http://www.sintegra.gov.br/insc_est.html "Conferência de Inscrições Estaduais") do SINTEGRA.
#### Utilização
>>> ie = InscricaoEstadual('613.855.219.926', 'SP')
>>> ValidadorInscricaoEstadual.validar(ie)
True
>>> ValidadorInscricaoEstadual.validarStr('207653461', 'RN')
True
>>> ValidadorInscricaoEstadual.validarStr('209564598', 'TO')
False
> **NOTA**: Caso não se deseje utilizar o __ValidadorInscricaoEstadual__, pode-se utilizar o validador específico para uma determinada Unidade da Federação.
<p>Cada Unidade da Federação brasileira possui o seu próprio validador, definido por: **Validador**XX, onde _XX_ deve ser substituído pela sigla da Unidade da Federação desejada.</p>
<p>O Exemplo a seguir mostra como utilizar somente o validador específico para o Ceará, visando validar uma Inscrição Estadual deste Estado:</p>
>>> from bradocs4py.validadoresie import ValidadorCE
>>> ValidadorCE.validar('1234567')
False
>>> ValidadorCE.validar('50374156-6')
True
> **IMPORTANTE**: Ao contrário de ValidadorInscricaoEstadual, os validadores específicos de cada UF validam somente uma cadeia de caracteres (_string_) contendo o número representativo da Inscrição Estadual a ser validada.
### <a name="chave"></a> ChaveAcessoNFe
Representa a **Chave de Acesso** de uma Nota Fiscal Eletrônica.
#### <a name="lfchave"></a> Lei de formação de uma Chave de Acesso de NF-e
A Chave de Acesso da Nota Fiscal Eletrônica é representada por uma sequência de 44 caracteres numéricos, devendo ser composta pelos seguintes campos que se encontram dispersos no Layout da NF-e:
* UF - Código da UF do emitente do Documento Fiscal
* AAMM - Ano e mês da emissão da NF-e
* CNPJ - CNPJ do emitente do Documento Fiscal
* Modelo - Modelo do Documento Fiscal
* Série - Série do Documento Fiscal
* Número - Número do Documento Fiscal
* Forma Emissão - Forma de emissão do Documento Fiscal
* Código Numérico - Código numérico que compõe a Chave de Acesso
* DV - Dígito verificados
| Código | UF | AAMM | CNPJ | Modelo | Série | Número | Forma Emissão | Código Numérico | DV |
| :--------:|:----:|:----:|:----:|:------:|:-----:|:------:|:-------------:|:---------------:|:----:|
|Quantidade de caracteres |02 |04 |14 |02 |03 |09 |01 |08 |01 |
#### Utilização
>>> ca = ChaveAcessoNFe('23 1811 06850713000120 55 001 001766829 1 11103011 2')
>>> ca
<BRADocs4Py.bradocs4py.chaveacessonfe.ChaveAcessoNFe('23181106850713000120550010017668291111030112')>
>>> print(ca)
2318 1106 8507 1300 0120 5500 1001 7668 2911 1103 0112
>>> ca.rawValue
'23181106850713000120550010017668291111030112'
>>> ca.isValid
True
### <a name="vchave"></a> ValidadorChaveAcessoNFe
Valida a consistência e a integridade de uma instância de [ChaveAcessoNFe](#chave) ou uma _string_ contendo a representação numérica de uma Chave de Acesso, através do cálculo de seu _dígito verificador_.
> O **Dígito Verificador** (DV) visa garantir a integridade da Chave de Acesso, protegendo-a principalmente contra digitações erradas.
#### Utilização
>>> chave = ChaveAcessoNFe(35181298957205000164667451830925015791400679)
>>> validarChaveAcessoNFe(chave)
True
>>> ValidadorChaveAcessoNFe.validar(52060433009911002506550120000007800267301615)
True
>>> ValidadorChaveAcessoNFe.validar('52060433009911002506550120000007800267301615')
True
>>> ValidadorChaveAcessoNFe.validar('52060433009911002506550120000007800267301625')
False
ou
>>> validarChaveAcessoNFe(52060433009911002506550120000007800267301615)
True
>>> validarChaveAcessoNFe('52060433009911002506550120000007800267301615')
True
>>> validarChaveAcessoNFe('52060433009911002506550120000007800267301625')
False
>>> validarChaveAcessoNFe(chave)
True
#### <a name="dvchave"></a> Cálculo do dígito verificador
O dígito verificador da chave de acesso da NF-e é baseado em um cálculo do módulo 11. O módulo 11 de um número é calculado multiplicando-se cada algarismo pela sequência de multiplicadores 2,3,4,5,6,7,8,9,2,3, ..., posicionados da direita para a esquerda.
A somatória dos resultados das ponderações dos algarismos é dividida por 11 e o DV (dígito verificador) será a diferença entre o divisor (11) e o resto da divisão:
DV = 11 - (resto da divisão)
> Quando o resto da divisão for 0 (zero) ou 1 (um), o DV deverá ser igual a 0 (zero).
Exemplo: consideremos a seguinte chave de acesso: _52060433009911002506550120000007800267301615_
Isolando o _dígito verificador_, temos: _5206043300991100250655012000000780026730161_
|**Chave** | 5 | 2 | 0 | 6 | 0 | 4 | 3 | 3 | 0 | 0 | 9 | 9 | 1 | 1 | 0 | 0 | 2 | 5 | 0 | 6 | 5 | 5 | 0 | 1 | 2 | 0 | 0 | 0 | 0 | 0 | 0 | 7 | 8 | 0 | 0 | 2 | 6 | 7 | 3 | 0 | 1 | 6 | 1 |
|:------------------------|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
|**Pesos** | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 |
|**Ponderação** |20 | 6 | 0 |54 | 0 |28 |18 |15 | 0 | 0 |18 |81 | 8 | 7 | 0 | 0 | 8 |15 | 0 |54 |40 |35 | 0 | 5 | 8 | 0 | 0 | 0 | 0 | 0 | 0 |35 |32 | 0 | 0 |18 |48 |49 |18 | 0 | 4 |18 | 2 |
**Somatório das ponderações**: _644_
Dividindo o somatório das ponderações por **11**, temos: 644/11 = 58, restando **6**
Como o dígito verificador (DV) = 11 - (resto da divisão), temos: **11 - 6 = 5**
Neste caso o DV da chave de acesso da NF-e é igual a "5".
#### <a name="consistenciachave"></a> Verificação da _consistência_ da Chave de Acesso
Por ter uma [lei de formação](#lfchave) peculiar, o _[ValidadorChaveAcessoNFe](#vchave)_ verifica a consistência de uma determinada chave de acesso, observando:
* se os dois primeiros dígitos correspondem ao código, segundo o IBGE, de uma Unidade da Federação Brasileira;
* Se a data de emissão (**mês** e **ano**) *ano* de emissão não é **posterior** à data (mês e ano) atual;
* Se o *mês* de emissão, que corresponde ao terceiro par de dígitos, corresponde ao valor de um dos meses do ano;
* Se o *CNPJ* do emitente corresponde a um número de CNPJ válido.
> Desta forma, para que uma chave de acesso de NF-e seja válida, esta deverá passar pelo cálculo do Dígito Verificador e pelo teste de consistência.
### <a name="gchave"></a> GeradorChaveAcessoNFe
Gera uma [Chave de Acesso de NF-e](#chave) válida.
A chave gerada pelo [GeradorChaveAcessoNFe](#gchave) obedece às [regras de consistência](#consistenciachave) anteriormente citadas.
#### Utilização
>>> chave = GeradorChaveAcessoNFe.gerar()
>>> chave
<BRADocs4Py.bradocs4py.chaveacessonfe.ChaveAcessoNFe('25181230173834000160651227059459841838300521')>
>>> print(chave)
2518 1230 1738 3400 0160 6512 2705 9459 8418 3830 0521
>>> chave.rawValue
'25181230173834000160651227059459841838300521'
>>> chave.isValid
True
OU
>>> chave = gerarChaveAcessoNFe
>>> chave
<BRADocs4Py.bradocs4py.chaveacessonfe.ChaveAcessoNFe('11181205001709000125650428522143493956800409')>
>>> print(chave)
1118 1205 0017 0900 0125 6504 2852 2143 4939 5680 0409
>>> chave.rawValue
'11181205001709000125650428522143493956800409'
>>> chave.isValid
True
É possível passar para o gerador qualquer um dos seguintes parâmetros, ou combinação deles:
* UF - [Gera de uma chave de acesso para uma determinada Unidade da Federação](#gchaveUF) Brasileira
* anoEmissao - [Gera uma chave de acesso para um determinado ano de emissão](#gchaveAno)
* mesEmissao - [Gera uma chave de acesso para um determinado mês de emissão](#gchaveMes)
* cnpjEmitente - [Gera uma chave de acesso informando o CNPJ do emitente](#gchaveCNPJ)
* modelo - [Gera uma chame de acesso informando o modelo do documento fiscal](#gchaveModelo)
* serie - [Gera uma chave de acesso informando a série do Documento Fiscal](#gchaveSerie)
* numero - [Gera uma chave de acesso informando o núemro do Documento Fiscal](#gchaveNumero)
* formaEmissao - [Gera uma chave de acesso informando o tipo de emissão da NF-e](#gchaveEmissao)
##### <a name="gchaveUF"></a> Gerar uma chave de acesso para uma determinada Unidade da Federação (23 - Ceará):
>>> chave = GeradorChaveAcessoNFe.gerar(UF=23)
>>> chave.rawValue
'23181200840039000117652898295631409915000755'
##### <a name="gchaveAno"></a> Gerar uma chave de acesso para um determinado ano:
>>> chave = GeradorChaveAcessoNFe.gerar(anoEmissao=2015)
>>> chave.rawValue
'23151289106950000109651490922639616463100456'
##### <a name="gchaveMes"></a> Gerar uma chave de acesso para um determinado mês:
>>> chave = GeradorChaveAcessoNFe.gerar(mesEmissao=8)
>>> chave.rawValue
'15180853477826000102655678711686215463600041'
##### <a name="gchaveMesAno"></a> Gerar uma chave de acesso para uma determinada data (mês e ano) de emissão:
>>> chave = GeradorChaveAcessoNFe.gerar(anoEmissao=2015, mesEmissao=1)
>>> chave.rawValue
'29150139480855000100653317092547617382300904'
##### <a name="gchaveCNPJ"></a> Gerar uma chave de acesso informando o CNPJ do emitente:
>>> chave = GeradorChaveAcessoNFe.gerar(cnpjEmitente='64802611000136')
>>> chave.rawValue
'13181264802611000136651456599176257515300837'
##### <a name="gchaveModelo"></a> Gerar uma chave de acesso de uma NF-e, utilizada nas operações de venda no varejo (modelo de documento fiscal = 55)
>>> chave = GeradorChaveAcessoNFe.gerar(modelo=55)
>>> chave.rawValue
'27181282761929000106555079534095503558300935'
##### <a name="gchaveSerie"></a> Gerar uma chave de acesso para uma NF-e que não possui série:
>>> chave = GeradorChaveAcessoNFe.gerar(serie=0)
>>> chave.rawValue
'13181202699369000160650006987155021599900654'
> Nota: A série também pode ser informada como uma cadeia de caracteres numéricos. No exemplo acima, poderia ter sido informado **'000'** para _serie_.
##### <a name="gchaveNumero"></a> Gerar uma chave de acesso informando o número do documento fiscal:
>>> chave = GeradorChaveAcessoNFe.gerar(numero=1766829)
>>> chave.rawValue
'23181241761925000132652850017668297691400378'
##### <a name="gchaveEmissao"></a> Gerar uma chave de acesso para uma NF-e emitida com Contingência FS-IA, com impressão do DANFE em formulário de segurança (Tipo de emissã0 = 2)
>>> chave = GeradorChaveAcessoNFe.gerar(formaEmissao=2)
>>> chave.rawValue
'51181278981604000153656457693627102018200143'
Isto posto, desejando-se criar uma chave de acesso emitida no Ceará (Código IBGE=23) em Maio de 2016, para o CNPJ 64802611/0001-36, teríamos:
>>> chave = GeradorChaveAcessoNFe.gerar(formaEmissao=2, UF=23, anoEmissao=2016, mesEmissao=5, cnpjEmitente=64802611000136)
>>> chave.rawValue
'23160564802611000136554038699639442073100081'
>>> chave.isValid
True
> **Atenção**: a forma abreviada do gerador _(gerarChaveAcessoNFe)_ não permite a passagem de parâmetros.
### <a name="gtin"></a>GTIN
Representa um Número Global do Item Comercial - Global Trade Item Number (GTIN)
O GTIN é um identificador para itens comerciais desenvolvido e controlado pela [GS1][gs1], antiga EAN/UCC. Os GTINs,
anteriormente chamados de códigos EAN, são atribuídos para qualquer item (produto ou serviço) que pode ser
precificado, pedido ou faturado em qualquer ponto da cadeia de suprimentos. O GTIN é utilizado para recuperar
informação pré-definida e abrange desde as matérias primas até produtos acabados. GTIN é um termo “guarda-chuva”
para descrever toda a família de identificação das estruturas de dados GS1 para itens comerciais (produtos e serviços).
Os GTINs podem ter o tamanho de 8, 12, 13 ou 14 dígitos e podem ser construídos utilizando qualquer uma das quatro
estruturas de numeração dependendo da aplicação. O GTIN-8 é codificado no código de barras EAN-8. O GTIN-12 é mais
utilizado no código de barras UPC-A, o GTIN-13 é codificado no EAN-13 e o GTIN-14 no ITF-14.
#### Utilização
##### Criando uma instância de [GTIN](#gtin) a partir de um inteiro
>>> gtin = GTIN(6291041500213)
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-13 '6291041500213')>
>>> gtin.rawValue
'6291041500213'
>>> gtin.isValid
True
##### Criando uma instância de [GTIN](#gtin) a partir de uma cadeia de caracteres numéricos
>>> gtin = GTIN('35723189')
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-8 '35723189')>
>>> gtin.rawValue
'35723189'
>>> gtin.isValid
True
### <a name="vgtin"></a> ValidadorGTIN
Valida uma instância de GTIN, um inteiro ou uma cadeia de caracteres numéricos que representa um GTIN, a partir do [cálculo de seu dígito verificador][calculo-digito-gtin], o qual assegura a sua integridade.
> Nota: Muito embora o ValidadorGTIN valide uma instância de GTIN, a validação desta instância pode ser verificada através da sua propriedade _isValid_, conforme exemplos acima.
#### Utilização
>>> gtin = GTIN('35723189')
>>> ValidadorGTIN.validar(gtin)
True
>>> ValidadorGTIN.validar('3572318')
False
>>> ValidadorGTIN.validar('35723189')
True
>>> ValidadorGTIN.validar(6291041500213)
True
>>> ValidadorGTIN.validar('62910415OO213')
False
**OU**
>>> gtin = GTIN('35723189')
>>> validar_gtin(gtin)
True
>>> validar_gtin('3572318')
False
>>> validar_gtin('35723189')
True
>>> validar_gtin(6291041500213)
True
>>> validar_gtin('62910415OO213')
False
### <a name="ggtin"></a> GeradorGTIN
Gera uma instância de um [GTIN](#gtin) válido.
>IMPORTANTE: Este gerador de GTIN tem como intenção ajudar estudantes, programadores, analistas e testadores de sistemas computacionais a gerar GTINs válidas. Normalmente necessárias parar testar seus softwares em desenvolvimento. A má utilização dos dados aqui gerados é de total responsabilidade do usuário. Os números são gerados de forma aleatória, respeitando as regras de criação de um GTIN.
#### Utilização
>>> gtin = GeradorGTIN.gerar()
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-8 '93490399')>
**ou**
>>> gtin = gerar_gtin()
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-8 '33409382')>
É possível informar ao gerador o tipo de GTIN que se deseja gerar. Para isso, deve-se passar o _GeradorGTIN.TipoGTIN_ desejado.
##### Para gerar um GTIN-8
>>> gtin = GeradorGTIN.gerar(GeradorGTIN.TipoGTIN.GTIN8)
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-8 '33409382')>
Também é possível gerar GTINs chamando diretamente _gerar_gtin_:
>>> gtin = gerar_gtin(GeradorGTIN.TipoGTIN.GTIN13)
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-13 '4332497941617')>
Utilize:
* GeradorGTIN.TipoGTIN.GTIN8 para gerar GTIN-8
* GeradorGTIN.TipoGTIN.GTIN12 para gerar GTIN-12
* GeradorGTIN.TipoGTIN.GTIN13 para gerar GTIN-13, ou
* GeradorGTIN.TipoGTIN.GTIN14 para gerar GTIN-14
> Se não for passado nenhum tipo para o gerador, este gerará sempre um GTIN-8.
[gs1]: https://www.gs1br.org
[calculo-digito-gtin]: https://www.gs1.org/services/how-calculate-check-digit-manually
%package help
Summary: Development documents and examples for bradocs4py
Provides: python3-bradocs4py-doc
%description help
[](https://pypi.org/project/bradocs4py/)
[](https://github.com/namio/BRADocs4Py.git)
[](https://pypi.org/project/bradocs4py/)
[](https://pypi.org/project/bradocs4py/)
[](https://pypi.org/project/bradocs4py/)
[](https://github.com/namio/BRADocs4Py/blob/master/LICENSE)
[](https://github.com/namio/BRADocs4Py.git)
[](https://saythanks.io/to/namio)
# BRADocs4Py
BRADocs4Py é uma biblioteca que visa fornecer componentes para trabalhar com tipos de dados específicos da realidade brasileira.
Esta biblioteca surgiu mediante a necessidade de se ter tipos específicos que possibilitem lidar com documentos de identificação próprios do Brasil, como é o caso do Cadastro de Pessoa Física (CPF) e do Cadastro Nacional de Pessoa Jurídica (CNPJ).
Além de conter classes que representam o modelo computacional dos principais documentos brasileiros, esta biblioteca também disponibiliza classes que permitem a validação e a geração de números válidos para estes documentos; sendo estas últimas disponibilizadas exclusivamente para fins de testes computacionais.
> This software is coded and documented in portuguese only as it is intended to be used to generate the necessary files for the brazilian government regarding to digital bookkeeping.
## Requisitos
* python
## Como instalar
$ pip install bradocs4py
## Objetivos do Projeto
A ideia inicial do projeto e unificar em uma única biblioteca módulos que permitam representar computacionalmente e validar documentos brasileiros - inicialmente CPF e CNPJ, além de permitir a geração de números válidos para estes documentos.
## Compatibilidade do Projeto
O projeto inicialmente suportará apenas Python 3.6.5+.
Outras linguagens de programação poderão ter versões especificas conforme minha disponibilidade de tempo.
## Status do Projeto
O projeto está em fase inicial de desenvolvimento.
| Módulo | Situação |
|:------------------------------------|:---------------:|
| [DocumentoIdentificacao](#di) |Funcional |
| [CPF](#cpf) |Funcional |
| [ValidadorCpf](#vcpf) |Funcional |
| [GeradorCpf](#gcpf) |Funcional |
| [Cnpj](#cnpj) |Funcional |
| [ValidadorCnpj](#vcnpj) |Funcional |
| [GeradorCnpj](#gcnpj) |Funcional |
| [InscricaoEstadual](#ie) |Funcional |
| [ValidadorInscricaoEstadual](#vie) |Funcional |
| [GeradorInscricaoEstadual](#gie) |Não implementado |
| [InscricaoSuframa](#is) |Funcional |
| [ValidadorSuframa](#vs) |Funcional |
| [GeradorSuframa](#gs) |Funcional |
| [ChaveAcessoNFe](#chave) |Funcional |
| [ValidadorChaveAcessoNFe](#vchave) |Funcional |
| [GeradorChaveAcessoNFe](#gchave) |Funcional |
| [GTIN](#gtin) |Funcional |
| [ValidadorGTIN](#vgtin) |Funcional |
| [GeradorGTIN](#ggtin) |Funcional |
### <a name="di"></a> DocumentoIdentificacao
Classe abstrata, não podendo ser instanciada diretamente, serve como base para todas as classes que representam um documento de identificação ou qualquer outro documento brasileiro que necessite de validação.
### <a name="cpf"></a> CPF
Classe usada para representar em código Pyhton um _Cadastro de Pessoa Física_ (CPF); permitindo representá-lo textualmente, com a devida formatação e identificar a sua validade.
#### Utilização
>>> cpf = CPF('52513127765')
>>> cpf
'525.131.277-65'
>>> cpf.isValid
True
>>> cpf.rawValue
52513127765
>>> cpf = CPF('abcdefghijk')
>>> cpf.isValid
False
>>> print(cpf)
abcdefghijk
>>> print(cpf.rawValue)
abcdefghijk
> Independente do conteúdo passado ao se criar uma instância de CPF, **sempre** obter-se-á uma instância deste. Caberá consultar a propriedade __isValid__ de uma instância de CPF para verificar se esta é válida ou não.
> A representação textual de uma instância de CPF só será exibida caso esta instância contenha um número válido de CPF; ao contrário será exibida a _string_ utilizada para criá-la.
> Para obter a _string_ utilizada ao instanciar um CPF, basta acessar a propriedade **rawValue** da instância criada.
### <a name="vcpf"></a> ValidadorCpf
Classe responsável por validar uma instância de CPF ou uma _string_ contendo a representação numérica de um CPF.
#### Utilização
>>> cpf = CPF('abcdefghijk')
>>> ValidadorCpf.validar(cpf)
False
>>> ValidadorCpf.validar('123.456.789-00')
False
Foi criado um CPF válido, porém foi digitado um caractere de separação diferente dos caracteres esperados (.-/ ). Mesmo assim, o validador informa tratar-se de um CPF correto
>>> cpf = CPF('508,697,212-40')
>>> ValidadorCpf.validar(cpf)
True
### <a name="gcpf"></a> GeradorCpf
Classe responsável por gerar aleatoriamente um CPF válido.
#### Utilização
>>> cpf = GeradorCpf.gerar()
>>> cpf.isValid
True
### <a name="cnpj"></a> Cnpj
Classe usada para representar em código Pyhton um _Cadastro Nacional de Pessoa Jurídica_ (CNPJ); permitindo representá-lo textualmente, com a devida formatação e identificar a sua validade.
#### Utilização
>>> cnpj = Cnpj('abcdefghijklmn')
>>> cnpj.isValid
False
>>> cnpj = Cnpj('12345678901234')
>>> cnpj.isValid
False
>>> cnpj = Cnpj('19.658.147/0001-0O')
>>> cnpj.isValid
False
>>> cnpj = Cnpj('19.658.147/0001-00')
>>> cnpj.isValid
True
> Independente do conteúdo passado ao se criar uma instância de CNPJ, **sempre** obter-se-á uma instância deste. Caberá consultar a propriedade __isValid__ de uma instância de CNPJ para verificar se esta é válida ou não.
> A representação textual de uma instância de CNPJ só será exibida caso esta instância contenha um número válido de CNPJ; ao contrário será exibida a _string_ utilizada para criá-la.
> Para obter a _string_ utilizada ao instanciar um CNPJ, basta acessar a propriedade **rawValue** da instância criada.
### <a name="vcnpj"></a> ValidadorCnpj
Classe responsável por validar uma instância de CNPJ ou uma _string_ contendo a representação numérica de um CNPJ.
#### Utilização
>>> cnpj = Cnpj('abcdefghijklmn')
>>> ValidadorCnpj.validar(cnpj)
False
>>> cnpj = Cnpj('19.658.147/0001-0O')
>>>ValidadorCnpj.validar(cnpj)
False
>>> ValidadorCnpj.validar('12345678901234')
False
>>> cnpj = Cnpj('34 633 423,0001/60')
>>> ValidadorCnpj.validar(cnpj)
True
>>> ValidadorCnpj.validar('05.692.744/0001-38')
True
### <a name="gcnpj"></a> GeradorCnpj
Classe responsável por gerar aleatoriamente um CNPJ válido.
#### Utilização
>>> cnpj = GeradorCnpj.gerar()
>>> cnpj.isValid
True
### <a name="is"></a> InscricaoSuframa
Representa o número de inscrição na Superintendência da Zona Franca de Manaus (SUFRAMA)
> A SUFRAMA mantém controle sobre as empresas com insentivo fiscal, identificando-as através do número de _Inscrição SUFRAMA_.
A composição deste indicador é: _SS.NNNN.LLD_, onde:
**SS** representa o __código do setor de atividade__ da empresa, conforme exemplo abaixo:
| Código | Descrição |
| :----: | :---------------------------|
| 01 e 02 | Cooperativa |
| 10 e 11 | Comércio |
| 20 | Indústria com projeto pleno |
| 60 | Serviços |
**NNNN** número sequencial
**LL** representa o código da licalidade da Unidade Administrativa da Suframa que habilitou a empresa, conforme exemplo abaixo:
| Código | Descrição |
| :----: | :-----------|
| 01 | Manaus |
| 10 | Boa Vista |
| 30 | Porto Velho |
**D** dígito verificador
#### Validação
* Campo numérico com 9 posições (incluindo o dígito verificador).
* Pode iniciar por 0 (zero), mas não pode iniciar por 00.
* Dígito verificador calculado por [__módulo 11__](https://pt.wikipedia.org/wiki/D%C3%ADgito_verificador#Módulo_11 "Método de cálculo do dígito verificador usando Módulo 11"), pesos 2 a 9.
#### Utilização
>>> x = InscricaoSuframa('01.1234.129')
>>> x.rawValue
'011234129'
>>> print(x)
01.1234.129
>>> x.isValid
False
>>> x = InscricaoSuframa('101580100')
>>> x.rawValue
'101580100'
>>> print(x)
10.1580.100
>>> x.isValid
True
>>> x = InscricaoSuframa('1015801OO')
>>> x.rawValue
'1015801OO'
>>> print(x)
1015801OO
>>> x.isValid
False
### <a name="vs"></a> ValidadorSuframa
Valida uma instância de InscricaoSuframa ou uma _string_ contendo a representação numérica de uma Inscrição Suframa.
#### Utilização
# Validação de uma _string_ representando uma Inscrição Suframa:
>>> ValidadorSuframa.validar('101580100')
True
# Validação de uma _string_ representando uma Inscrição Suframa inválida (contendo caracteres não numéricos):
>>> ValidadorSuframa.validar('1015801OO')
False
# Validação de uma instância de InscriçãoSuframa:
>>> x = InscricaoSuframa('01.1234.129')
>>> ValidadorSuframa.validar(x)
False
### <a name="gs"></a> GeradorSuframa
Gera aleatoriamente uma Inscrição Suframa válida
>>> x = GeradorSuframa.gerar()
>>> x.isValid
True
> **IMPORTANTE**: O __GeradorSuframa__ tem por objetivo ajudar estudantes, programadores, analistas de sistemas e testadores de código a gerar Inscrições Suframa válidas visando auxiliar as rotinas de testes de softwares em desenvolvimento.
> A má utilização dos dados gerados pelo __GeradorSuframa__ é de **total responsabilidade do usuário** desta biblioteca.
> As inscrições são geradas de forma aleatória, respeitando as leis de formação estabelecidas pela SUFRAMA.
### <a name="ie"></a> InscricaoEstadual
Representa, em código Pyhton, uma _Inscrição Estadual_ (IE), ou o registro do contribuinte no cadastro do ICMS mantido pela Receita Estadual; permitindo representá-lo textualmente, com a devida formatação e identificar a sua validade.
#### Utilização
>>> ie = InscricaoEstadual('613.855.219.926', 'SP')
>>> ie.isValid
True
>>> ie.rawValue
'613855219926'
>>> ie.UF
'SP'
>>> print(ie)
613.855.219.926
### <a name="vie"></a> ValidadorInscricaoEstadual
Valida a consistência de uma instância de InscricaoEstadual ou uma _string_ contendo a representação numérica de uma Inscrição Estadual para uma determinada Unidade da Federação, informada juntamente com a representação numérica da IE a qual se deseja validar.
> A validação da Inscrição Estadual para cada Unidade da Federação brasileira, leva em consideração o disposto no [__Convênio 57/59__](http://www.sintegra.gov.br/conv_5795.html "ConvênioICMS 57/59"), como também as orientações e especificidades contidas na página [Conferências de Inscrições Estaduais](http://www.sintegra.gov.br/insc_est.html "Conferência de Inscrições Estaduais") do SINTEGRA.
#### Utilização
>>> ie = InscricaoEstadual('613.855.219.926', 'SP')
>>> ValidadorInscricaoEstadual.validar(ie)
True
>>> ValidadorInscricaoEstadual.validarStr('207653461', 'RN')
True
>>> ValidadorInscricaoEstadual.validarStr('209564598', 'TO')
False
> **NOTA**: Caso não se deseje utilizar o __ValidadorInscricaoEstadual__, pode-se utilizar o validador específico para uma determinada Unidade da Federação.
<p>Cada Unidade da Federação brasileira possui o seu próprio validador, definido por: **Validador**XX, onde _XX_ deve ser substituído pela sigla da Unidade da Federação desejada.</p>
<p>O Exemplo a seguir mostra como utilizar somente o validador específico para o Ceará, visando validar uma Inscrição Estadual deste Estado:</p>
>>> from bradocs4py.validadoresie import ValidadorCE
>>> ValidadorCE.validar('1234567')
False
>>> ValidadorCE.validar('50374156-6')
True
> **IMPORTANTE**: Ao contrário de ValidadorInscricaoEstadual, os validadores específicos de cada UF validam somente uma cadeia de caracteres (_string_) contendo o número representativo da Inscrição Estadual a ser validada.
### <a name="chave"></a> ChaveAcessoNFe
Representa a **Chave de Acesso** de uma Nota Fiscal Eletrônica.
#### <a name="lfchave"></a> Lei de formação de uma Chave de Acesso de NF-e
A Chave de Acesso da Nota Fiscal Eletrônica é representada por uma sequência de 44 caracteres numéricos, devendo ser composta pelos seguintes campos que se encontram dispersos no Layout da NF-e:
* UF - Código da UF do emitente do Documento Fiscal
* AAMM - Ano e mês da emissão da NF-e
* CNPJ - CNPJ do emitente do Documento Fiscal
* Modelo - Modelo do Documento Fiscal
* Série - Série do Documento Fiscal
* Número - Número do Documento Fiscal
* Forma Emissão - Forma de emissão do Documento Fiscal
* Código Numérico - Código numérico que compõe a Chave de Acesso
* DV - Dígito verificados
| Código | UF | AAMM | CNPJ | Modelo | Série | Número | Forma Emissão | Código Numérico | DV |
| :--------:|:----:|:----:|:----:|:------:|:-----:|:------:|:-------------:|:---------------:|:----:|
|Quantidade de caracteres |02 |04 |14 |02 |03 |09 |01 |08 |01 |
#### Utilização
>>> ca = ChaveAcessoNFe('23 1811 06850713000120 55 001 001766829 1 11103011 2')
>>> ca
<BRADocs4Py.bradocs4py.chaveacessonfe.ChaveAcessoNFe('23181106850713000120550010017668291111030112')>
>>> print(ca)
2318 1106 8507 1300 0120 5500 1001 7668 2911 1103 0112
>>> ca.rawValue
'23181106850713000120550010017668291111030112'
>>> ca.isValid
True
### <a name="vchave"></a> ValidadorChaveAcessoNFe
Valida a consistência e a integridade de uma instância de [ChaveAcessoNFe](#chave) ou uma _string_ contendo a representação numérica de uma Chave de Acesso, através do cálculo de seu _dígito verificador_.
> O **Dígito Verificador** (DV) visa garantir a integridade da Chave de Acesso, protegendo-a principalmente contra digitações erradas.
#### Utilização
>>> chave = ChaveAcessoNFe(35181298957205000164667451830925015791400679)
>>> validarChaveAcessoNFe(chave)
True
>>> ValidadorChaveAcessoNFe.validar(52060433009911002506550120000007800267301615)
True
>>> ValidadorChaveAcessoNFe.validar('52060433009911002506550120000007800267301615')
True
>>> ValidadorChaveAcessoNFe.validar('52060433009911002506550120000007800267301625')
False
ou
>>> validarChaveAcessoNFe(52060433009911002506550120000007800267301615)
True
>>> validarChaveAcessoNFe('52060433009911002506550120000007800267301615')
True
>>> validarChaveAcessoNFe('52060433009911002506550120000007800267301625')
False
>>> validarChaveAcessoNFe(chave)
True
#### <a name="dvchave"></a> Cálculo do dígito verificador
O dígito verificador da chave de acesso da NF-e é baseado em um cálculo do módulo 11. O módulo 11 de um número é calculado multiplicando-se cada algarismo pela sequência de multiplicadores 2,3,4,5,6,7,8,9,2,3, ..., posicionados da direita para a esquerda.
A somatória dos resultados das ponderações dos algarismos é dividida por 11 e o DV (dígito verificador) será a diferença entre o divisor (11) e o resto da divisão:
DV = 11 - (resto da divisão)
> Quando o resto da divisão for 0 (zero) ou 1 (um), o DV deverá ser igual a 0 (zero).
Exemplo: consideremos a seguinte chave de acesso: _52060433009911002506550120000007800267301615_
Isolando o _dígito verificador_, temos: _5206043300991100250655012000000780026730161_
|**Chave** | 5 | 2 | 0 | 6 | 0 | 4 | 3 | 3 | 0 | 0 | 9 | 9 | 1 | 1 | 0 | 0 | 2 | 5 | 0 | 6 | 5 | 5 | 0 | 1 | 2 | 0 | 0 | 0 | 0 | 0 | 0 | 7 | 8 | 0 | 0 | 2 | 6 | 7 | 3 | 0 | 1 | 6 | 1 |
|:------------------------|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
|**Pesos** | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 |
|**Ponderação** |20 | 6 | 0 |54 | 0 |28 |18 |15 | 0 | 0 |18 |81 | 8 | 7 | 0 | 0 | 8 |15 | 0 |54 |40 |35 | 0 | 5 | 8 | 0 | 0 | 0 | 0 | 0 | 0 |35 |32 | 0 | 0 |18 |48 |49 |18 | 0 | 4 |18 | 2 |
**Somatório das ponderações**: _644_
Dividindo o somatório das ponderações por **11**, temos: 644/11 = 58, restando **6**
Como o dígito verificador (DV) = 11 - (resto da divisão), temos: **11 - 6 = 5**
Neste caso o DV da chave de acesso da NF-e é igual a "5".
#### <a name="consistenciachave"></a> Verificação da _consistência_ da Chave de Acesso
Por ter uma [lei de formação](#lfchave) peculiar, o _[ValidadorChaveAcessoNFe](#vchave)_ verifica a consistência de uma determinada chave de acesso, observando:
* se os dois primeiros dígitos correspondem ao código, segundo o IBGE, de uma Unidade da Federação Brasileira;
* Se a data de emissão (**mês** e **ano**) *ano* de emissão não é **posterior** à data (mês e ano) atual;
* Se o *mês* de emissão, que corresponde ao terceiro par de dígitos, corresponde ao valor de um dos meses do ano;
* Se o *CNPJ* do emitente corresponde a um número de CNPJ válido.
> Desta forma, para que uma chave de acesso de NF-e seja válida, esta deverá passar pelo cálculo do Dígito Verificador e pelo teste de consistência.
### <a name="gchave"></a> GeradorChaveAcessoNFe
Gera uma [Chave de Acesso de NF-e](#chave) válida.
A chave gerada pelo [GeradorChaveAcessoNFe](#gchave) obedece às [regras de consistência](#consistenciachave) anteriormente citadas.
#### Utilização
>>> chave = GeradorChaveAcessoNFe.gerar()
>>> chave
<BRADocs4Py.bradocs4py.chaveacessonfe.ChaveAcessoNFe('25181230173834000160651227059459841838300521')>
>>> print(chave)
2518 1230 1738 3400 0160 6512 2705 9459 8418 3830 0521
>>> chave.rawValue
'25181230173834000160651227059459841838300521'
>>> chave.isValid
True
OU
>>> chave = gerarChaveAcessoNFe
>>> chave
<BRADocs4Py.bradocs4py.chaveacessonfe.ChaveAcessoNFe('11181205001709000125650428522143493956800409')>
>>> print(chave)
1118 1205 0017 0900 0125 6504 2852 2143 4939 5680 0409
>>> chave.rawValue
'11181205001709000125650428522143493956800409'
>>> chave.isValid
True
É possível passar para o gerador qualquer um dos seguintes parâmetros, ou combinação deles:
* UF - [Gera de uma chave de acesso para uma determinada Unidade da Federação](#gchaveUF) Brasileira
* anoEmissao - [Gera uma chave de acesso para um determinado ano de emissão](#gchaveAno)
* mesEmissao - [Gera uma chave de acesso para um determinado mês de emissão](#gchaveMes)
* cnpjEmitente - [Gera uma chave de acesso informando o CNPJ do emitente](#gchaveCNPJ)
* modelo - [Gera uma chame de acesso informando o modelo do documento fiscal](#gchaveModelo)
* serie - [Gera uma chave de acesso informando a série do Documento Fiscal](#gchaveSerie)
* numero - [Gera uma chave de acesso informando o núemro do Documento Fiscal](#gchaveNumero)
* formaEmissao - [Gera uma chave de acesso informando o tipo de emissão da NF-e](#gchaveEmissao)
##### <a name="gchaveUF"></a> Gerar uma chave de acesso para uma determinada Unidade da Federação (23 - Ceará):
>>> chave = GeradorChaveAcessoNFe.gerar(UF=23)
>>> chave.rawValue
'23181200840039000117652898295631409915000755'
##### <a name="gchaveAno"></a> Gerar uma chave de acesso para um determinado ano:
>>> chave = GeradorChaveAcessoNFe.gerar(anoEmissao=2015)
>>> chave.rawValue
'23151289106950000109651490922639616463100456'
##### <a name="gchaveMes"></a> Gerar uma chave de acesso para um determinado mês:
>>> chave = GeradorChaveAcessoNFe.gerar(mesEmissao=8)
>>> chave.rawValue
'15180853477826000102655678711686215463600041'
##### <a name="gchaveMesAno"></a> Gerar uma chave de acesso para uma determinada data (mês e ano) de emissão:
>>> chave = GeradorChaveAcessoNFe.gerar(anoEmissao=2015, mesEmissao=1)
>>> chave.rawValue
'29150139480855000100653317092547617382300904'
##### <a name="gchaveCNPJ"></a> Gerar uma chave de acesso informando o CNPJ do emitente:
>>> chave = GeradorChaveAcessoNFe.gerar(cnpjEmitente='64802611000136')
>>> chave.rawValue
'13181264802611000136651456599176257515300837'
##### <a name="gchaveModelo"></a> Gerar uma chave de acesso de uma NF-e, utilizada nas operações de venda no varejo (modelo de documento fiscal = 55)
>>> chave = GeradorChaveAcessoNFe.gerar(modelo=55)
>>> chave.rawValue
'27181282761929000106555079534095503558300935'
##### <a name="gchaveSerie"></a> Gerar uma chave de acesso para uma NF-e que não possui série:
>>> chave = GeradorChaveAcessoNFe.gerar(serie=0)
>>> chave.rawValue
'13181202699369000160650006987155021599900654'
> Nota: A série também pode ser informada como uma cadeia de caracteres numéricos. No exemplo acima, poderia ter sido informado **'000'** para _serie_.
##### <a name="gchaveNumero"></a> Gerar uma chave de acesso informando o número do documento fiscal:
>>> chave = GeradorChaveAcessoNFe.gerar(numero=1766829)
>>> chave.rawValue
'23181241761925000132652850017668297691400378'
##### <a name="gchaveEmissao"></a> Gerar uma chave de acesso para uma NF-e emitida com Contingência FS-IA, com impressão do DANFE em formulário de segurança (Tipo de emissã0 = 2)
>>> chave = GeradorChaveAcessoNFe.gerar(formaEmissao=2)
>>> chave.rawValue
'51181278981604000153656457693627102018200143'
Isto posto, desejando-se criar uma chave de acesso emitida no Ceará (Código IBGE=23) em Maio de 2016, para o CNPJ 64802611/0001-36, teríamos:
>>> chave = GeradorChaveAcessoNFe.gerar(formaEmissao=2, UF=23, anoEmissao=2016, mesEmissao=5, cnpjEmitente=64802611000136)
>>> chave.rawValue
'23160564802611000136554038699639442073100081'
>>> chave.isValid
True
> **Atenção**: a forma abreviada do gerador _(gerarChaveAcessoNFe)_ não permite a passagem de parâmetros.
### <a name="gtin"></a>GTIN
Representa um Número Global do Item Comercial - Global Trade Item Number (GTIN)
O GTIN é um identificador para itens comerciais desenvolvido e controlado pela [GS1][gs1], antiga EAN/UCC. Os GTINs,
anteriormente chamados de códigos EAN, são atribuídos para qualquer item (produto ou serviço) que pode ser
precificado, pedido ou faturado em qualquer ponto da cadeia de suprimentos. O GTIN é utilizado para recuperar
informação pré-definida e abrange desde as matérias primas até produtos acabados. GTIN é um termo “guarda-chuva”
para descrever toda a família de identificação das estruturas de dados GS1 para itens comerciais (produtos e serviços).
Os GTINs podem ter o tamanho de 8, 12, 13 ou 14 dígitos e podem ser construídos utilizando qualquer uma das quatro
estruturas de numeração dependendo da aplicação. O GTIN-8 é codificado no código de barras EAN-8. O GTIN-12 é mais
utilizado no código de barras UPC-A, o GTIN-13 é codificado no EAN-13 e o GTIN-14 no ITF-14.
#### Utilização
##### Criando uma instância de [GTIN](#gtin) a partir de um inteiro
>>> gtin = GTIN(6291041500213)
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-13 '6291041500213')>
>>> gtin.rawValue
'6291041500213'
>>> gtin.isValid
True
##### Criando uma instância de [GTIN](#gtin) a partir de uma cadeia de caracteres numéricos
>>> gtin = GTIN('35723189')
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-8 '35723189')>
>>> gtin.rawValue
'35723189'
>>> gtin.isValid
True
### <a name="vgtin"></a> ValidadorGTIN
Valida uma instância de GTIN, um inteiro ou uma cadeia de caracteres numéricos que representa um GTIN, a partir do [cálculo de seu dígito verificador][calculo-digito-gtin], o qual assegura a sua integridade.
> Nota: Muito embora o ValidadorGTIN valide uma instância de GTIN, a validação desta instância pode ser verificada através da sua propriedade _isValid_, conforme exemplos acima.
#### Utilização
>>> gtin = GTIN('35723189')
>>> ValidadorGTIN.validar(gtin)
True
>>> ValidadorGTIN.validar('3572318')
False
>>> ValidadorGTIN.validar('35723189')
True
>>> ValidadorGTIN.validar(6291041500213)
True
>>> ValidadorGTIN.validar('62910415OO213')
False
**OU**
>>> gtin = GTIN('35723189')
>>> validar_gtin(gtin)
True
>>> validar_gtin('3572318')
False
>>> validar_gtin('35723189')
True
>>> validar_gtin(6291041500213)
True
>>> validar_gtin('62910415OO213')
False
### <a name="ggtin"></a> GeradorGTIN
Gera uma instância de um [GTIN](#gtin) válido.
>IMPORTANTE: Este gerador de GTIN tem como intenção ajudar estudantes, programadores, analistas e testadores de sistemas computacionais a gerar GTINs válidas. Normalmente necessárias parar testar seus softwares em desenvolvimento. A má utilização dos dados aqui gerados é de total responsabilidade do usuário. Os números são gerados de forma aleatória, respeitando as regras de criação de um GTIN.
#### Utilização
>>> gtin = GeradorGTIN.gerar()
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-8 '93490399')>
**ou**
>>> gtin = gerar_gtin()
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-8 '33409382')>
É possível informar ao gerador o tipo de GTIN que se deseja gerar. Para isso, deve-se passar o _GeradorGTIN.TipoGTIN_ desejado.
##### Para gerar um GTIN-8
>>> gtin = GeradorGTIN.gerar(GeradorGTIN.TipoGTIN.GTIN8)
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-8 '33409382')>
Também é possível gerar GTINs chamando diretamente _gerar_gtin_:
>>> gtin = gerar_gtin(GeradorGTIN.TipoGTIN.GTIN13)
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-13 '4332497941617')>
Utilize:
* GeradorGTIN.TipoGTIN.GTIN8 para gerar GTIN-8
* GeradorGTIN.TipoGTIN.GTIN12 para gerar GTIN-12
* GeradorGTIN.TipoGTIN.GTIN13 para gerar GTIN-13, ou
* GeradorGTIN.TipoGTIN.GTIN14 para gerar GTIN-14
> Se não for passado nenhum tipo para o gerador, este gerará sempre um GTIN-8.
[gs1]: https://www.gs1br.org
[calculo-digito-gtin]: https://www.gs1.org/services/how-calculate-check-digit-manually
%prep
%autosetup -n bradocs4py-1.3.1.0
%build
%py3_build
%install
%py3_install
install -d -m755 %{buildroot}/%{_pkgdocdir}
if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi
if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi
if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi
if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi
pushd %{buildroot}
if [ -d usr/lib ]; then
find usr/lib -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
if [ -d usr/lib64 ]; then
find usr/lib64 -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
if [ -d usr/bin ]; then
find usr/bin -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
if [ -d usr/sbin ]; then
find usr/sbin -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
touch doclist.lst
if [ -d usr/share/man ]; then
find usr/share/man -type f -printf "\"/%h/%f.gz\"\n" >> doclist.lst
fi
popd
mv %{buildroot}/filelist.lst .
mv %{buildroot}/doclist.lst .
%files -n python3-bradocs4py -f filelist.lst
%dir %{python3_sitelib}/*
%files help -f doclist.lst
%{_docdir}/*
%changelog
* Thu Jun 08 2023 Python_Bot <Python_Bot@openeuler.org> - 1.3.1.0-1
- Package Spec generated