Este pequeno tutorial tem por objetivo ilustrar como usar o R para obter dados a partir da API do SICONFI disponibilizada pela Secretaria do Tesouro Nacional-STN, cuja documentação pode ser consultada em: http://apidatalake.tesouro.gov.br/docs/siconfi/tt#/
Para quem quiser saber um pouco mais o que é uma API (Application Programming Interface, ou em português: Interface de Programação de Aplicativos), consultar https://pt.wikipedia.org/wiki/Interface_de_programação_de_aplicações
Também vamos mostrar como utilizar o pacote ckanr para acessar, pesquisar e obter dados de sites que disponibilizam bases de dados com uso do aplicativo CKAN( Comprehensive Knowledge Archive Network ). O CKAN é uma ferramenta para a confecção de websites de dados abertos. Pode ser visto como uma espécie de gerenciador de conteúdo para dados abertos.
Instituições nacionais que utilizam essa ferramenta para disponibilizar dados é o Portal Brasileiro de Dados Abertos (dados.gov.br), a Comissão de Valores Mombiliários - CVM (http://dados.cvm.gov.br/), o Banco Central do Brasil - BCB (https://dadosabertos.bcb.gov.br/) e a Secretaria do Tesouro Nacional - STN (https://apickan.tesouro.gov.br/ckan) para citar alguns.
De acordo com a documentação da API é possível obter dados sobre os seguintes demonstrativos/relatórios:
As URL de consulta para a obtenção de dados de cada um desses demonstrativos/relatórios é constituída de uma URL básica mais um “pedaço” específico para cada um dos demonstrativos/relatórios acima.
A URL básica é "apidatalake.tesouro.gov.br/ords/siconfi/tt/" e acrescentamos a ela uma informação que indicará em que demonstrativo/relatório estamos interessados. Por exemplo: se acrescentarmos /rreo à URL básica podemos consultar informações relativas ao RREO; acrescentando /extratos_entregas podemos consultar um extrato contendo informações sobre relatórios homologados e retificados e matrizes entregues. Para os demais é o mesmo procedimento.
Para consultar dados do RGF a URL seria: "apidatalake.tesouro.gov.br/ords/siconfi/tt/rgf". Para sabermos as opções disponíveis precisamos consultar a documentação da API no link indicado.
De acordo com a informação desejada será necessário passar à consulta um conjunto de parâmetros específicos. Para a consulta ao RREO, o usuário precisará informar: o exercício financeiro, o bimestre desejado, o tipo de demonstrativo, o número do anexo e o código IBGE do Ente para o qual desejamos obter os dados.
Vamos exemplificar o uso da API com uma consulta ao Anexo 01 do RREO para o primeiro bimestre de 2019 para o município do Rio de Janeiro, cujo código IBGE é 3304557.
A consulta ao RREO exige as seguintes informações:
an_exercicio: o ano para o qual deseja realizar a consulta
nr_periodo: um número de 1 a 6 indicando o bimestre desejado
co_tipo_demonstrativo: o tipo do demonstrativo. Os valores possíveis são RREO e RREO Simplificado
no_anexo: o anexo de interesse. Os valores possíveis estão no formato RREO-Anexo dd. Para o Anexo 04 há uma pequena variação nesse formato
id_ente: o código IBGE do Ente
Essencialmente o processo de fazer consultas consiste em: (1) fazer uma requisição de dados à API e receber os resultado, (2) verificar se tudo correu bem, (3) fazer o parser dos dados retornados pela consulta e (4) converter o resultado para um data frame.
A seguir vamos ilustrar cada um desses passos.
Vamos, primeiro, carregar os pacotes que serão utilizados:
library(httr)
library(jsonlite)
library(stringr)
library(dplyr)
library(tidyr)Carregados os pacotes, já podemos fazer a submissão da consulta (passo 1):
Como já mencionado, vamos consultar o Anexo 01 do RREO para o primeiro bimestre de 2019 do município do Rio de Janeiro cujo código IBGE é 3304557.
base_url_rreo <- "apidatalake.tesouro.gov.br/ords/siconfi/tt/rreo?"
# parâmetros de consulata ao RREO
ano <- "2019"
bimestre <- "1"
tipo_relatorio <- "RREO"
num_anexo <- "RREO-Anexo+01"
ente <- "3304557"
# montar a chamada à API
chamada_api_rreo <- paste(base_url_rreo,
"an_exercicio=", ano, "&",
"nr_periodo=", bimestre, "&",
"co_tipo_demonstrativo=", tipo_relatorio, "&",
"no_anexo=", num_anexo, "&",
"id_ente=", ente, sep = "")Construída a chamada à API a partir dos dados fornecidos, podemos submeter a requisição de dados. Para isso vamos usar a função GET() do pacote httr.
rreo <- GET(chamada_api_rreo)O reultado retornado está agora no objeto rreo. Vamos verificar se ocorreu tudo bem com a requisição (passo 2). Isso pode ser feito com a função status_code() que nos dará o status da requisição.
status_code(rreo) [1] 200O status 200 nos indica que a requisição foi feita com sucesso.
Uma lista completa dos códigos de status pode ser obtida em https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
Para fazer a extração do conteúdo que nos interessa (passo 3) vamos utilizar a função content().
rreo_txt <- content(rreo, as="text", encoding="UTF-8")Feita a extração do conteúdo temos que converter estes dados para um data frame para que possamos utilizá-lo em análises posteriores.
rreo_json <- fromJSON(rreo_txt, flatten = FALSE) Feita a extração, vamos agora para o passo 4: converter os dados para um data frame.
rreo_df <- as.data.frame(rreo_json[["items"]]) Podemos agora inspecionar os dados obtidos:
knitr::kable(head(rreo_df))| exercicio | demonstrativo | periodo | periodicidade | instituicao | cod_ibge | uf | populacao | anexo | rotulo | coluna | cod_conta | conta | valor |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2019 | RREO | 1 | B | Prefeitura Municipal de Rio de Janeiro - RJ | 3304557 | RJ | 6688927 | RREO-Anexo 01 | Padrão | PREVISÃO INICIAL | ReceitasExcetoIntraOrcamentarias | RECEITAS (EXCETO INTRA-ORÇAMENTÁRIAS) (I) | 25285911173.00 |
| 2019 | RREO | 1 | B | Prefeitura Municipal de Rio de Janeiro - RJ | 3304557 | RJ | 6688927 | RREO-Anexo 01 | Padrão | PREVISÃO ATUALIZADA (a) | ReceitasExcetoIntraOrcamentarias | RECEITAS (EXCETO INTRA-ORÇAMENTÁRIAS) (I) | 25285911173.00 |
| 2019 | RREO | 1 | B | Prefeitura Municipal de Rio de Janeiro - RJ | 3304557 | RJ | 6688927 | RREO-Anexo 01 | Padrão | No Bimestre (b) | ReceitasExcetoIntraOrcamentarias | RECEITAS (EXCETO INTRA-ORÇAMENTÁRIAS) (I) | 5293738837.57 |
| 2019 | RREO | 1 | B | Prefeitura Municipal de Rio de Janeiro - RJ | 3304557 | RJ | 6688927 | RREO-Anexo 01 | Padrão | % (b/a) | ReceitasExcetoIntraOrcamentarias | RECEITAS (EXCETO INTRA-ORÇAMENTÁRIAS) (I) | 20.94 |
| 2019 | RREO | 1 | B | Prefeitura Municipal de Rio de Janeiro - RJ | 3304557 | RJ | 6688927 | RREO-Anexo 01 | Padrão | Até o Bimestre (c) | ReceitasExcetoIntraOrcamentarias | RECEITAS (EXCETO INTRA-ORÇAMENTÁRIAS) (I) | 5293738837.57 |
| 2019 | RREO | 1 | B | Prefeitura Municipal de Rio de Janeiro - RJ | 3304557 | RJ | 6688927 | RREO-Anexo 01 | Padrão | % (c/a) | ReceitasExcetoIntraOrcamentarias | RECEITAS (EXCETO INTRA-ORÇAMENTÁRIAS) (I) | 20.94 |
Os dados estão prontos para serem utilizados.
Como estamos trabalhando o demonstrativo de um único periodo e de um único Ente, podemos excluir algumas colunas.
rreo_df <- rreo_df %>% select(coluna:valor)Algumas pessoas poderão preferir trabalhar com os dados em outro formato, mais parecido com o formato em que são apresentados nos relatórios impressos. Podemos colocar os dados nesse formato da seguinte forma:
rreo_df <- rreo_df %>%
spread(key=coluna, value = valor) %>%
select(conta, cod_conta, `PREVISÃO INICIAL`, `PREVISÃO ATUALIZADA (a)`, `No Bimestre (b)`,
`% (b/a)`, `Até o Bimestre (c)`, `% (c/a)`, `SALDO (a-c)`, `DOTAÇÃO INICIAL (d)`,
`DOTAÇÃO ATUALIZADA (e)`, `DESPESAS EMPENHADAS NO BIMESTRE`, `DESPESAS EMPENHADAS ATÉ O BIMESTRE (f)`,
`SALDO (g) = (e-f)`, `DESPESAS LIQUIDADAS NO BIMESTRE`, `DESPESAS LIQUIDADAS ATÉ O BIMESTRE (h)`,
`SALDO (i) = (e-h)`, `DESPESAS PAGAS ATÉ O BIMESTRE (j)`)knitr::kable(head(rreo_df))| conta | cod_conta | PREVISÃO INICIAL | PREVISÃO ATUALIZADA (a) | No Bimestre (b) | % (b/a) | Até o Bimestre (c) | % (c/a) | SALDO (a-c) | DOTAÇÃO INICIAL (d) | DOTAÇÃO ATUALIZADA (e) | DESPESAS EMPENHADAS NO BIMESTRE | DESPESAS EMPENHADAS ATÉ O BIMESTRE (f) | SALDO (g) = (e-f) | DESPESAS LIQUIDADAS NO BIMESTRE | DESPESAS LIQUIDADAS ATÉ O BIMESTRE (h) | SALDO (i) = (e-h) | DESPESAS PAGAS ATÉ O BIMESTRE (j) |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ALIENAÇÃO DE BENS | AlienacaoDeBens | 15092003 | 15092003 | 3853402 | 25.53 | 3853402 | 25.53 | 11238601 | NA | NA | NA | NA | NA | NA | NA | NA | NA |
| Alienação de Bens Imóveis | AlienacaoDeBensImoveis | 7127000 | 7127000 | 3853402 | 54.07 | 3853402 | 54.07 | 3273598 | NA | NA | NA | NA | NA | NA | NA | NA | NA |
| Alienação de Bens Móveis | AlienacaoDeBensMoveis | 7965003 | 7965003 | NA | NA | NA | NA | 7965003 | NA | NA | NA | NA | NA | NA | NA | NA | NA |
| AMORTIZAÇÃO DA DÍVIDA | AmortizacaoDaDivida | NA | NA | NA | NA | NA | NA | NA | 784807393 | 784807393 | 784350726 | 784350726 | 456666.8 | 109153810 | 109153810 | 675653583 | 108556853 |
| AMORTIZAÇÃO DA DÍVIDA/REFINANCIAMENTO (XI) | AmortizacaoRefinanciamentoDaDivida | NA | NA | NA | NA | NA | NA | NA | 221902797 | 221902797 | 221064205 | 221064205 | 838591.7 | 27027267 | 27027267 | 194875530 | 27027267 |
| Amortização da Dívida Interna | AmortizacaoRefinanciamentoDaDividaInterna | NA | NA | NA | NA | NA | NA | NA | 221902797 | 221902797 | 221064205 | 221064205 | 838591.7 | 27027267 | 27027267 | 194875530 | 27027267 |
As contas estão em ordem alfabética, mas podem ser reorganizadas para ficarem na ordem em que aparecem no demonstrativo impresso.
Vamos agora mostrar como utilizar o pacote ckanr para acessar dados disponibilizados pela CVM.
Para realizar a importação de qualquer base de dados precisamos definir o site do qual iremos obtê-los. Para esse exemplo usaremos o site de dados abertos da CVM antes mencionado. A definição do site é feita com a função ckanr_setup().
library(ckanr)
ckanr_setup(url="http://dados.cvm.gov.br/")Definida a fonte de dados, podemos consultar a relação de dados disponíveis com a função package_list()
package_list(as="table") [1] "cia_aberta-cad" "cia_aberta-doc-dfp-bpa" "cia_aberta-doc-dfp-bpp" "cia_aberta-doc-dfp-dfc_md" "cia_aberta-doc-dfp-dfc_mi" "cia_aberta-doc-dfp-dmpl"
[7] "cia_aberta-doc-dfp-dre" "cia_aberta-doc-dfp-dva" "distrpubl" "emissores" "fi-cad" "fidc-doc-inf_mensal"
[13] "fi-doc-balancete" "fi-doc-cda" "fi-doc-eventual" "fi-doc-extrato" "fi-doc-inf_diario" "fie-cad"
[19] "fie-medidas" "intermediario-cad" group_list(as = 'table')[1] "cias-abertas" "fundos-de-investimento" "fundos-estruturados" "participantes-intermediarios"Os dados estão “agrupados”" conforme as categorias acima. Para identificarmos quantos “recursos” existem em um determinado grupo, usamos a função group_show().
group_show('fundos-de-investimento', as = 'table')[["packages"]][, c("num_resources", "name", "url", "id")] %>% knitr::kable()| num_resources | name | url | id |
|---|---|---|---|
| 14 | fi-doc-inf_diario | http://dados.cvm.gov.br/dataset/fi-doc-inf_diario | c54097de-1659-42d4-b550-1842b33091c8 |
| 2 | fie-cad | http://dados.cvm.gov.br/dataset/fie-cad | 4d868a41-b3e3-41c3-81e1-08a7957556d7 |
| 68 | fi-cad | http://dados.cvm.gov.br/dataset/fi-cad | 81820d8c-8e3a-4859-a572-de659f3a287d |
| 13 | fie-medidas | http://dados.cvm.gov.br/dataset/fie-medidas | ed50b021-1b64-4965-9096-a2e7689d6e9a |
| 13 | fidc-doc-inf_mensal | http://dados.cvm.gov.br/dataset/fidc-doc-inf_mensal | bfbb0044-359b-4084-89ca-f6ce8ac8d5a3 |
| 6 | fi-doc-extrato | http://dados.cvm.gov.br/dataset/fi-doc-extrato | 2cc8db2f-b69f-413e-8abb-da17a412245b |
| 7 | fi-doc-eventual | http://dados.cvm.gov.br/dataset/fi-doc-eventual | c4ef718e-6849-4829-847b-ba739d3c0ef2 |
| 13 | fi-doc-cda | http://dados.cvm.gov.br/dataset/fi-doc-cda | f01ae864-88ec-4331-b303-96ca31aa2f41 |
| 13 | fi-doc-balancete | http://dados.cvm.gov.br/dataset/fi-doc-balancete | ab8fb906-d049-4113-885d-de6279d1ee53 |
| 7 | emissores | http://dados.cvm.gov.br/dataset/emissores | e9e44d40-7ed4-43f1-b7b6-c3c115d54a41 |
O resultado acima nos traz as seguintes informações: o pacote fi-cad possui 68 recursos (conjuntos de dados e metadados) e o código de identicação do pacote é 81820d8c-8e3a-4859-a572-de659f3a287d.
Vamos mostrar os três primeiros e os três últimos registros do conteúdo existente na componente resources da lista retornada pela função package_show():
head(package_show('81820d8c-8e3a-4859-a572-de659f3a287d', as = 'table')[["resources"]][, c("url", "name")], 3) %>% knitr::kable()| url | name |
|---|---|
| http://dados.cvm.gov.br/dados/FI/CAD/META/meta_inf_cadastral_fi.txt | Dicionário de Dados |
| http://dados.cvm.gov.br/dados/FI/CAD/DADOS/inf_cadastral_fi_20190626.csv | Fundos de Investimento ICVM 555 (26/06/2019) |
| http://dados.cvm.gov.br/dados/FI/CAD/DADOS/inf_cadastral_fi_20190627.csv | Fundos de Investimento ICVM 555 (27/06/2019) |
tail(package_show('81820d8c-8e3a-4859-a572-de659f3a287d', as = 'table')[["resources"]][, c("url", "name")], 3) %>% knitr::kable()| url | name | |
|---|---|---|
| 66 | http://dados.cvm.gov.br/dados/FI/CAD/DADOS/inf_cadastral_fi_20190925.csv | Fundos de Investimento ICVM 555 (25/09/2019) |
| 67 | http://dados.cvm.gov.br/dados/FI/CAD/DADOS/inf_cadastral_fi_20190926.csv | Fundos de Investimento ICVM 555 (26/09/2019) |
| 68 | http://dados.cvm.gov.br/dados/FI/CAD/DADOS/inf_cadastral_fi_20190927.csv | Fundos de Investimento ICVM 555 (27/09/2019) |
O resultado nos fornece a URL do dicionário de dados bem como a url dos arquivos de dados e uma indição do seu conteúdo. Oberve que existe um arquivo para cada dia útil, e que o período abrangido parece ser de um quadrimestre.
Para importar o conteúdo relativo à base cadastral dos Fundos de Investimentos do dia 27/09/2019 (conjunto de dados mais recente à época da elaboração deste documento) podemos fazer da seguinte forma:
library(readr)
cadastro_fi <- package_show('81820d8c-8e3a-4859-a572-de659f3a287d', as = 'table')[["resources"]][["url"]] %>%
.[length(.)] %>%
read_csv2()Com o código acima vamos obter sempre a base de dados mais recente (última URL existente).
Vamos visualizar os dados importados:
As variáveis existentes no conjunto de dados são as seguintes:
names(cadastro_fi) [1] "CNPJ_FUNDO" "DENOM_SOCIAL" "DT_REG" "DT_CONST" "DT_CANCEL" "SIT" "DT_INI_SIT" "DT_INI_ATIV" "DT_INI_EXERC"
[10] "DT_FIM_EXERC" "CLASSE" "DT_INI_CLASSE" "RENTAB_FUNDO" "CONDOM" "FUNDO_COTAS" "FUNDO_EXCLUSIVO" "TRIB_LPRAZO" "INVEST_QUALIF"
[19] "TAXA_PERFM" "VL_PATRIM_LIQ" "DT_PATRIM_LIQ" "DIRETOR" "CNPJ_ADMIN" "ADMIN" "PF_PJ_GESTOR" "CPF_CNPJ_GESTOR" "GESTOR"
[28] "CNPJ_AUDITOR" "AUDITOR" # A função kable() não está funcionando...
head(cadastro_fi)# A tibble: 6 x 29
CNPJ_FUNDO DENOM_SOCIAL DT_REG DT_CONST DT_CANCEL SIT DT_INI_SIT DT_INI_ATIV DT_INI_EXERC DT_FIM_EXERC CLASSE DT_INI_CLASSE RENTAB_FUNDO CONDOM FUNDO_COTAS
<chr> <chr> <date> <date> <date> <chr> <date> <date> <date> <date> <chr> <date> <chr> <chr> <chr>
1 33.913.62~ "051 BRUCUT~ 2019-07-19 2019-06-04 NA EM F~ 2019-08-05 2019-08-05 2019-08-05 2020-05-31 Fundo~ 2019-06-04 DI de um dia Fecha~ N
2 31.964.01~ 051 CAPITAL~ 2018-11-29 2018-11-27 NA EM F~ 2018-12-10 2018-12-10 2019-07-01 2020-06-30 Fundo~ 2018-11-27 DI de um dia Fecha~ N
3 30.509.21~ "051 CARIBE~ 2019-06-11 2018-04-13 NA EM F~ 2019-06-25 2019-06-25 2019-06-25 2020-01-31 Fundo~ 2018-04-13 DI de um dia Fecha~ N
4 34.172.41~ 051 FIA LB ~ 2019-08-22 2019-08-20 NA EM F~ 2019-08-22 2019-08-22 2019-08-22 2020-06-30 "Fund~ 2019-08-20 <NA> Aberto N
5 33.150.56~ 051 HF FUND~ 2019-04-23 2019-04-23 NA EM F~ 2019-05-21 2019-05-21 2019-05-21 2019-09-30 Fundo~ 2019-04-23 <NA> Aberto S
6 33.146.17~ 051 MEGA FI~ 2019-05-17 2019-05-16 NA EM F~ 2019-07-03 2019-07-03 2019-07-03 2020-06-30 Fundo~ 2019-05-16 <NA> Fecha~ S
# ... with 14 more variables: FUNDO_EXCLUSIVO <chr>, TRIB_LPRAZO <chr>, INVEST_QUALIF <chr>, TAXA_PERFM <chr>, VL_PATRIM_LIQ <chr>, DT_PATRIM_LIQ <date>, DIRETOR <chr>,
# CNPJ_ADMIN <chr>, ADMIN <chr>, PF_PJ_GESTOR <chr>, CPF_CNPJ_GESTOR <chr>, GESTOR <chr>, CNPJ_AUDITOR <chr>, AUDITOR <chr>Os dados estão disponíveis para uso.