Receita-WS

Para tal, ele acessa o serviço web Receita WS desenvolvido na Anatel. Este por sua vez é um encapsulamento, com cache em banco de dados corporativo, do Serviço Web Infoconv, disponibilizado pela Serpro/Receita Federal, por meio de convênio firmado com a Anatel.

Instalação

python

Caso não tenha o python instalado, baixe a versão para a sua plataforma neste link e siga as instruções.

? Alternativamente, para uma plataforma de desenvolvimento mais versátil recomendamos que seja instalado o miniconda, que é uma versão mínima do Anaconda.

? Para uma versão otimizada do miniconda, com excelentes defaults, recomendamos ainda que seja instalado o miniforge,

Ambiente Virtual

Primeiramente é recomendado a criação de ambiente virtual para instalar o módulo, assim a versão python deste e suas dependências não afetam a instalação do python padrão:

Modo 1 - Utilizando o módulo venv (disponível em qualquer instalação padrão do python3):

python -m venv <pasta>

Desse modo será criado o ambiente virtual na <pasta>

Para ativar o ambiente virtual:

Windows

Utilizando o Prompt de Comando: cmd.exe

<pasta>\Scripts\activate.bat

Utilizando o PowerShell:

<pasta>\Scripts\Activate.ps1

Linux e MacOS

source <pasta>/bin/activate

Modo 2 (Recomendado) - Utilizando o conda (disponível em qualquer uma das instalações: Anaconda | Miniconda | Miniforge):

conda create -n <nome> python=3.10 -y

Desse modo será criado um ambiente virtual designado <nome> criado na pasta interna do conda.

Para ativar o ambiente virtual conda:

conda activate <nome>

Troque o comando conda por mamba, caso este tenha sido instalado

Instalação do módulo `receitaws`

Com o ambiente virtual criado e ativado, em qualquer um dos modos mostrados no parágrafo anterior, basta efetuar o comando:

python -m pip install git+https://git.anatel.gov.br/rsilva/receitaws.git

? Como este é um serviço de uso exclusivo na rede interna da Anatel e por logins autorizados, a instalação é feita diretamente pelo repositório:

Como utilizar

A presente biblioteca receitaws possui somente 1 módulo: consultas, cuja API principal é a função requisitar_em_lote:

Script em linha de comando

A API principal requisitar_em _lote é exposta em linha de comando chamando diretamente o módulo da seguinte maneira:

python -m receitaws [OPTIONS] FILENAME CPF_USUARIO

Dentro de outro módulo ou script python

from receitaws.consultas import requisitar_em_lote

requisitar_em_lote

 requisitar_em_lote (entrada:str, cpf_usuario:str, tipo:str, origem:str,
                     ambiente:str='hm', cache:int=36, saida:str=None,
                     n_workers:int=2)

Lê o arquivo entrada com um CPF | CPNJ por linha ou o objeto python iterável. Faz a requisição no ambiente do receita-ws e salva os resultados em saida

	Type	Default	Details
entrada	str		Arquivo texto de entrada: 1 CPF \| CNPJ por linha ou objeto python iterável
cpf_usuario	str		CPF do usuário requisitante
tipo	str		Tipo de Requisição CPF \| CNPJ
origem	str		Texto com identificação da requisição: e.g. ‘Teste’
ambiente	str	hm	Ambiente onde realizar a requisição: hm \| pd
cache	int	36	Tempo de expiração do cache em meses
saida	str	None	Arquivo de saída da requisição
n_workers	int	2	Número de requisições a serem efetuadas em paralelo
Returns	DataFrame

Parâmetros obrigatórios:

entrada: Arquivo texto de entrada: 1 CPF | CNPJ por linha OU objeto python iterável
cpf_usuario: CPF do usuário requisitante
tipo: Tipo de Requisição CPF | CNPJ
origem: Texto com identificação da requisição: e.g. ‘Teste’

cpf = CPF()
cpf_usuario = cpf.generate()

?? Como arquivo de entrada é esperado um arquivo texto, e.g. csv | txt | tsv etc... com 1 registro por linha!

requisitar_em_lote(entrada=r'D:\Code\receitaws\dados\cpf.csv', 
                     cpf_usuario=cpf_usuario,
                     tipo='cpf',
                     origem='Teste HM',
                     ambiente='hm',
                     cache=3,
                     saida=r'D:\Code\receitaws\dados\resultados_cpf_hm.csv')

.dataframe tbody tr th {
    vertical-align: top;
}

.dataframe thead th {
    text-align: right;
}

</style>

	cpf	nome	situacaoCadastral.codigo	situacaoCadastral.valor	paisResidencia.residenteExterior	nomeMae	dataNascimento	sexo.codigo	sexo.valor	...	telefone.numero	unidadeAdministrativaCodigo	estrangeiro	dataAtualizacao	dataRegistroAnatel	resultado	ocupacao.naturezaOcupacaoDescricao
0	33481695268	Ls Ifmqinlkurrssezna	2	Suspensa	True	Cqyqxgqgumqinlkurrssezna	1997-09-12	1	Masculino	...	97219728	7439828	False	1937-04-06	2022-09-27	CPF encontrado	NaN
1	47819847034	Tuxktnciwueq Koithctjx	0	Regular	True	Abpcgqu Koithctjx	1980-01-13	9	Sem informacao	...	15966520	6976220	False	1928-09-13	2022-09-27	CPF encontrado	Membro ou servidor público da administração di...
2	18876126880	Nyopkqyx Rwdykddcmmro	8	Nula	True	Edcgltyiqsprxfddcmmro	1986-12-22	9	Sem informacao	...	32104647	5700228	False	1965-09-17	2022-09-27	CPF encontrado	NaN
3	58201343204	J Y Ubevpjgbcvzubibdhvje	0	Regular	True	Razgqipmdwypegctupbrzubibdhvje	1924-12-17	9	Sem informacao	...	60991414	0021524	False	1965-05-22	2022-09-27	CPF encontrado	NaN
4	21996857134	Zzhpkuwfqwqlckrmbguszqfcfbb	4	Pendente de Regularizacao	True	Byezpzzzlckrmbguszqfcfbb	1963-12-08	2	Feminino	...	03848341	8697223	False	1930-03-25	2022-09-27	CPF encontrado	Membro ou servidor público da administração di...
5	25367495842	Tdexnrovkjpylffcuua	8	Nula	True	Wycxfbgojbksdxzjllffcuua	1985-07-31	1	Masculino	...	63426936	6092170	False	2006-08-24	2022-09-27	CPF encontrado	NaN
6	58948023691	Cxdb Nqfhnlutcni Cti	9	Cancelada de Oficio	False	NaN	1961-09-21	9	Sem informacao	...	01723291	1333898	True	1962-11-25	2022-09-27	CPF encontrado	Empregado de instituições financeiras públicas...
7	09465085693	Qzztsrsjcnsmtob Nzkiktjm	5	Cancelada por Multiplicidade	False	Pig Fdidrejqnfqcjlqttsiyxsv	1972-08-18	1	Masculino	...	96816835	6426935	True	1948-05-14	2022-09-27	CPF encontrado	NaN
8	83792430487	Vcm Ntdwndjxdxsxovdy	1	Cancelada por Encerramento de Espolio	False	Efmyumjtdwndjxdxsxovdy	1932-02-23	1	Masculino	...	92991603	3370473	True	2007-02-03	2022-09-27	CPF encontrado	NaN
9	58066098200	Mvggvgmtra Wpgxdrrgeu	2	Suspensa	True	Jlgabppbailxftfdevggl	1938-10-04	9	Sem informacao	...	85120080	1864416	False	1954-02-15	2022-09-27	CPF encontrado	NaN

10 rows × 32 columns

?? Ao importar a função acima dentro de um módulo python, o seu uso é mais versátil. O argumento entrada pode ser tanto o caminho para um arquivo texte com 1 registro por linha quanto um objeto python iterável, como uma lista por exemplo

entrada = [cpf.generate() for _ in range(10)]

requisitar_em_lote(entrada=entrada, 
                     cpf_usuario=cpf_usuario,
                     tipo='cpf',
                     ambiente='hm',
                     origem='Teste HM',
                     cache=3,
                     saida=r'D:\Code\receitaws\dados\resultados_cpf_hm.csv')

.dataframe tbody tr th {
    vertical-align: top;
}

.dataframe thead th {
    text-align: right;
}

</style>

	cpf	nome	situacaoCadastral.codigo	situacaoCadastral.valor	paisResidencia.residenteExterior	paisResidencia.codigoPais	nomeMae	dataNascimento	sexo.codigo	sexo.valor	...	telefone.ddd	telefone.numero	unidadeAdministrativaCodigo	estrangeiro	tituloEleitor	dataAtualizacao	dataRegistroAnatel	resultado	erro
0	05057557262	Zgu Wxgwawlnjmgluhqp	3.0	Cancelada por Obito sem Espolio	False	0.0	Lmvbfjkntngwawlnjmgluhqp	1964-05-21	9.0	Sem informacao	...	3	29434313	9654413	True	0000000000000	1957-07-31	2022-10-05	CPF encontrado
1	07056996094		NaN	NaN	NaN	NaN		1900-01-01	NaN	NaN	...	NaN	NaN		False		1900-01-01	1900-01-01	Erro INFOCONV: CPF - Erro 04 - CPF não encontr...	E04
2	11075083206		NaN	NaN	NaN	NaN		1900-01-01	NaN	NaN	...	NaN	NaN		False		1900-01-01	1900-01-01	Erro INFOCONV: CPF - Erro 04 - CPF não encontr...	E04
3	20718665503		NaN	NaN	NaN	NaN		1900-01-01	NaN	NaN	...	NaN	NaN		False		1900-01-01	1900-01-01	Erro INFOCONV: CPF - Erro 04 - CPF não encontr...	E04
4	64208996480		NaN	NaN	NaN	NaN		1900-01-01	NaN	NaN	...	NaN	NaN		False		1900-01-01	1900-01-01	Erro INFOCONV: CPF - Erro 04 - CPF não encontr...	E04
5	11857448863	Nxvummi Uztqqja	3.0	Cancelada por Obito sem Espolio	False	0.0	Vtvgqiijjzyczi Uztqqja	1909-09-10	2.0	Feminino	...	3	00894523	0603123	True	0000000000000	1998-06-26	2022-10-05	CPF encontrado
6	69050644759		NaN	NaN	NaN	NaN		1900-01-01	NaN	NaN	...	NaN	NaN		False		1900-01-01	1900-01-01	Erro INFOCONV: CPF - Erro 04 - CPF não encontr...	E04
7	65670773870		NaN	NaN	NaN	NaN		1900-01-01	NaN	NaN	...	NaN	NaN		False		1900-01-01	1900-01-01	Erro INFOCONV: CPF - Erro 04 - CPF não encontr...	E04
8	23750763461		NaN	NaN	NaN	NaN		1900-01-01	NaN	NaN	...	NaN	NaN		False		1900-01-01	1900-01-01	Erro INFOCONV: CPF - Erro 04 - CPF não encontr...	E04
9	24951994704	Gpbjcbmmzeluopwktlzksaehpge	9.0	Cancelada de Oficio	False	0.0	Qetrfujyurlnzotflkbsaehpge	1997-08-21	1.0	Masculino	...	65	63758088	0757745	True	0000000000000	1900-07-30	2022-10-05	CPF encontrado

10 rows × 30 columns

Ambientes

A mesma requisição pode ser feita nos ambientes: * Homologação: hm (Padrão) * Produção: pd

Utilização do Cache em Banco

O argumento cache é o número de meses que devemos considerar antes de fazer a requisição.

Caso o intervalo de tempo entre a data da requisição e a data de atualização do registro em banco corporativo for inferior ao cache, o registro do banco é retornado em lugar de se fazer a requisição ao Infoconv da receita federal ??

Isso foi uma solução para evitar requisições, e por conseguinte cobranças desnecessárias, de registros que já estão com atualização recente em banco ??

Arquivo de Saída

O formato do arquivo de saída é automaticamente identificado pela extensão do argumento saida, os valores possíveis são csv | xlsx | html | md, para salvamento em formato tabular, ou no formato json. Caso seja fornecido uma extensão não suportada ou não seja fornecido um nome de arquivo de saída, será salvo um csv na pasta onde é feita a requisição.

?? Todos os dados retornados pelo web service são salvos!

ronaldokun/receitaws