Package: bradocs4py
BRADocs4PyBRADocs4Py é 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.RequisitospythonComo instalar$ pip install bradocs4pyObjetivos do ProjetoA 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 ProjetoO 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 ProjetoO projeto está em fase inicial de desenvolvimento.MóduloSituaçãoDocumentoIdentificacaoFuncionalCPFFuncionalValidadorCpfFuncionalGeradorCpfFuncionalCnpjFuncionalValidadorCnpjFuncionalGeradorCnpjFuncionalInscricaoEstadualFuncionalValidadorInscricaoEstadualFuncionalGeradorInscricaoEstadualNão implementadoInscricaoSuframaFuncionalValidadorSuframaFuncionalGeradorSuframaFuncionalChaveAcessoNFeFuncionalValidadorChaveAcessoNFeFuncionalGeradorChaveAcessoNFeFuncionalGTINFuncionalValidadorGTINFuncionalGeradorGTINFuncionalDocumentoIdentificacaoClasse 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.CPFClasse usada para representar em código Pyhton umCadastro 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)
abcdefghijkIndependente do conteúdo passado ao se criar uma instância de CPF,sempreobter-se-á uma instância deste. Caberá consultar a propriedadeisValidde 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 astringutilizada para criá-la.Para obter astringutilizada ao instanciar um CPF, basta acessar a propriedaderawValueda instância criada.ValidadorCpfClasse responsável por validar uma instância de CPF ou umastringcontendo 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)
TrueGeradorCpfClasse responsável por gerar aleatoriamente um CPF válido.Utilização>>> cpf = GeradorCpf.gerar()
>>> cpf.isValid
TrueCnpjClasse usada para representar em código Pyhton umCadastro 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
TrueIndependente do conteúdo passado ao se criar uma instância de CNPJ,sempreobter-se-á uma instância deste. Caberá consultar a propriedadeisValidde 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 astringutilizada para criá-la.Para obter astringutilizada ao instanciar um CNPJ, basta acessar a propriedaderawValueda instância criada.ValidadorCnpjClasse responsável por validar uma instância de CNPJ ou umastringcontendo 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')
TrueGeradorCnpjClasse responsável por gerar aleatoriamente um CNPJ válido.Utilização>>> cnpj = GeradorCnpj.gerar()
>>> cnpj.isValid
TrueInscricaoSuframaRepresenta 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 deInscrição SUFRAMA.A composição deste indicador é:SS.NNNN.LLD, onde:SSrepresenta ocódigo do setor de atividadeda empresa, conforme exemplo abaixo:CódigoDescrição01 e 02Cooperativa10 e 11Comércio20Indústria com projeto pleno60ServiçosNNNNnúmero sequencialLLrepresenta o código da licalidade da Unidade Administrativa da Suframa que habilitou a empresa, conforme exemplo abaixo:CódigoDescrição01Manaus10Boa Vista30Porto VelhoDdígito verificadorValidaçãoCampo 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 pormó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
FalseValidadorSuframaValida uma instância de InscricaoSuframa ou umastringcontendo 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)
FalseGeradorSuframaGera aleatoriamente uma Inscrição Suframa válida>>> x = GeradorSuframa.gerar()
>>> x.isValid
TrueIMPORTANTE: OGeradorSuframatem 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 peloGeradorSuframaé detotal responsabilidade do usuáriodesta biblioteca.As inscrições são geradas de forma aleatória, respeitando as leis de formação estabelecidas pela SUFRAMA.InscricaoEstadualRepresenta, em código Pyhton, umaInscriçã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.926ValidadorInscricaoEstadualValida a consistência de uma instância de InscricaoEstadual ou umastringcontendo 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 noConvênio 57/59, como também as orientações e especificidades contidas na páginaConferências de Inscrições Estaduaisdo SINTEGRA.Utilização>>> ie = InscricaoEstadual('613.855.219.926', 'SP')
>>> ValidadorInscricaoEstadual.validar(ie)
True

>>> ValidadorInscricaoEstadual.validarStr('207653461', 'RN')
True
>>> ValidadorInscricaoEstadual.validarStr('209564598', 'TO')
FalseNOTA: Caso não se deseje utilizar oValidadorInscricaoEstadual, pode-se utilizar o validador específico para uma determinada Unidade da Federação.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.O Exemplo a seguir mostra como utilizar somente o validador específico para o Ceará, visando validar uma Inscrição Estadual deste Estado:>>> from bradocs4py.validadoresie import ValidadorCE
>>> ValidadorCE.validar('1234567')
False
>>> ValidadorCE.validar('50374156-6')
TrueIMPORTANTE: 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.ChaveAcessoNFeRepresenta aChave de Acessode uma Nota Fiscal Eletrônica.Lei de formação de uma Chave de Acesso de NF-eA 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 FiscalAAMM - Ano e mês da emissão da NF-eCNPJ - CNPJ do emitente do Documento FiscalModelo - Modelo do Documento FiscalSérie - Série do Documento FiscalNúmero - Número do Documento FiscalForma Emissão - Forma de emissão do Documento FiscalCódigo Numérico - Código numérico que compõe a Chave de AcessoDV - Dígito verificadosCódigoUFAAMMCNPJModeloSérieNúmeroForma EmissãoCódigo NuméricoDVQuantidade de caracteres020414020309010801Utilizaçã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
TrueValidadorChaveAcessoNFeValida a consistência e a integridade de uma instância deChaveAcessoNFeou umastringcontendo a representação numérica de uma Chave de Acesso, através do cálculo de seudígito verificador.ODí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)
TrueCálculo do dígito verificadorO 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:52060433009911002506550120000007800267301615Isolando odígito verificador, temos:5206043300991100250655012000000780026730161Chave5206043300991100250655012000000780026730161Pesos4329876543298765432987654329876543298765432Ponderação2060540281815001881870081505440350580000003532001848491804182Somatório das ponderações:644Dividindo o somatório das ponderações por11, temos: 644/11 = 58, restando6Como o dígito verificador (DV) = 11 - (resto da divisão), temos:11 - 6 = 5Neste caso o DV da chave de acesso da NF-e é igual a "5".Verificação daconsistênciada Chave de AcessoPor ter umalei de formaçãopeculiar, oValidadorChaveAcessoNFeverifica 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êseano)anode emissão não éposteriorà data (mês e ano) atual;Se omêsde emissão, que corresponde ao terceiro par de dígitos, corresponde ao valor de um dos meses do ano;Se oCNPJdo 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.GeradorChaveAcessoNFeGera umaChave de Acesso de NF-eválida.A chave gerada peloGeradorChaveAcessoNFeobedece àsregras de consistênciaanteriormente 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çãoBrasileiraanoEmissao -Gera uma chave de acesso para um determinado ano de emissãomesEmissao -Gera uma chave de acesso para um determinado mês de emissãocnpjEmitente -Gera uma chave de acesso informando o CNPJ do emitentemodelo -Gera uma chame de acesso informando o modelo do documento fiscalserie -Gera uma chave de acesso informando a série do Documento Fiscalnumero -Gera uma chave de acesso informando o núemro do Documento FiscalformaEmissao -Gera uma chave de acesso informando o tipo de emissão da NF-eGerar uma chave de acesso para uma determinada Unidade da Federação (23 - Ceará):>>> chave = GeradorChaveAcessoNFe.gerar(UF=23)
>>> chave.rawValue
'23181200840039000117652898295631409915000755'Gerar uma chave de acesso para um determinado ano:>>> chave = GeradorChaveAcessoNFe.gerar(anoEmissao=2015)
>>> chave.rawValue
'23151289106950000109651490922639616463100456'Gerar uma chave de acesso para um determinado mês:>>> chave = GeradorChaveAcessoNFe.gerar(mesEmissao=8)
>>> chave.rawValue
'15180853477826000102655678711686215463600041'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'Gerar uma chave de acesso informando o CNPJ do emitente:>>> chave = GeradorChaveAcessoNFe.gerar(cnpjEmitente='64802611000136')
>>> chave.rawValue
'13181264802611000136651456599176257515300837'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'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'paraserie.Gerar uma chave de acesso informando o número do documento fiscal:>>> chave = GeradorChaveAcessoNFe.gerar(numero=1766829)
>>> chave.rawValue
'23181241761925000132652850017668297691400378'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
TrueAtenção: a forma abreviada do gerador(gerarChaveAcessoNFe)não permite a passagem de parâmetros.GTINRepresenta um Número Global do Item Comercial - Global Trade Item Number (GTIN)O GTIN é um identificador para itens comerciais desenvolvido e controlado pelaGS1, 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çãoCriando uma instância deGTINa partir de um inteiro>>> gtin = GTIN(6291041500213)
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-13 '6291041500213')>
>>> gtin.rawValue
'6291041500213'
>>> gtin.isValid
TrueCriando uma instância deGTINa partir de uma cadeia de caracteres numéricos>>> gtin = GTIN('35723189')
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-8 '35723189')>
>>> gtin.rawValue
'35723189'
>>> gtin.isValid
TrueValidadorGTINValida uma instância de GTIN, um inteiro ou uma cadeia de caracteres numéricos que representa um GTIN, a partir docálculo de seu dígito verificador, 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 propriedadeisValid, 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')
FalseOU>>> gtin = GTIN('35723189')
>>> validar_gtin(gtin)
True
>>> validar_gtin('3572318')
False
>>> validar_gtin('35723189')
True
>>> validar_gtin(6291041500213)
True
>>> validar_gtin('62910415OO213')
FalseGeradorGTINGera uma instância de umGTINvá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 oGeradorGTIN.TipoGTINdesejado.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 diretamentegerar_gtin:>>> gtin = gerar_gtin(GeradorGTIN.TipoGTIN.GTIN13)
>>> gtin
<BRADocs4Py.bradocs4py.gtin.GTIN(GTIN-13 '4332497941617')>Utilize:GeradorGTIN.TipoGTIN.GTIN8 para gerar GTIN-8GeradorGTIN.TipoGTIN.GTIN12 para gerar GTIN-12GeradorGTIN.TipoGTIN.GTIN13 para gerar GTIN-13, ouGeradorGTIN.TipoGTIN.GTIN14 para gerar GTIN-14Se não for passado nenhum tipo para o gerador, este gerará sempre um GTIN-8.