Criando seu próprio servidor

Banco de dados

O projeto requer um banco de dados PostgreSQL ou MongoDB e os comandos que requerem banco de dados aceitam --database-uri (ou -u) como argumento com a URI de acesso ao banco de dados (o padrão é o valor da variável de ambiente DATABASE_URL).

Caso deseje usar o Docker Compose do projeto para subir uma instância do banco de dados:

$ docker compose up -d postgres
$ docker compose up -d mongo

Usando PostgreSQL, a URI será postgres://minhareceita:minhareceita@localhost:5432/minhareceita?sslmode=disable.

Usando MongoDB, a URI será mongodb://minhareceita:minhareceita@localhost:27017/minhareceita?authSource=admin.

Download dos dados

O comando download baixa dados da Receita Federal, mais um arquivo do Tesouro Nacional com o código dos municípios do IBGE. O servidor da Receita Federal pode ser lento e instável, então todo os arquivos são baixados em pequenas fatias.

O comando aceita um opção --directory (ou -d) com um diretório onde serão salvos os arquivos originais da Receita Federal. O padrão é data/.

Caso o download falhe, é recomendado variar as configurações explicadas no --help, por exemplo:

• número de downloads paralelos com o --parallel (ou -p)
• números de tentativas de download de cada fatia de cada arquivo com --retries (ou -r)
• tempo limite para cada fatia com --timeout (ou -t)
• rodar o comando de download sucessivas vezes com a opção --skip (ou -x) para baixar apenas os arquivos que estão faltando

Em último caso, é possível listar as URLs para download dos arquivos com comando urls; e, então, tentar fazer o download de outra forma (manualmente, com alguma ferramenta que permite recomeçar downloads interrompidos, etc.). Caso essa seja uma opção crie um arquivo updated_at.txt no mesmo diretório com a data de extração dos dados no formato YYYY-MM-DD.

Exemplos de uso

Sem Docker:

$ minha-receita download
$ minha-receita download --timeout 1h42m12s
$ minha-receita urls

Com Docker:

$ docker compose run --rm minha-receita download --directory /mnt/data/

Verificação dos downloads

O servidor da Receita Federal, além de lento e instável, não oferece uma opção de soma de verificação. Com isso, pode acontecer de os arquivos baixados estarem corrompidos. O comando check verifica a integridade dos arquivos .zip baixados. A opção --delete exclui os arquivos que falharem na verificação.

Tratamento dos dados

O comando transform transforma os arquivos para o formato JSON, consolidando as informações de todos os arquivos CSV. Esse JSON é armazenado diretamente no banco de dados. Para tanto, é preciso criar a tabela no banco de dados com o comando create (o comando drop pode ser utilizado para excluir essa mesma tabela).

Para especificar onde ficam os arquivos originais da Receita Federal e do Tesouro Nacional, o comando aceita como argumento --directory (ou -d), sendo o padrão data/.

Exemplos de uso

Sem Docker, com a variável de ambiente DATABASE_URL configurada:

$ minha-receita drop  # caso necessário
$ minha-receita create
$ minha-receita transform

Com Docker:

$ docker compose run --rm minha-receita drop  # caso necessário
$ docker compose run --rm minha-receita create
$ docker compose run --rm minha-receita transform -d /mnt/data/

Questões de privacidade

Assim como o socios-brasil removemos alguns dados para evitar exposição de dados sensíveis de pessoas físicas, bem como SPAM. A opção --no-privacy do comando transform remove essa precaução de privacidade.

Iniciando a API web

A API web é uma aplicação super simples que, por padrão, ficará disponível em localhost:8000.

Exemplos de uso

Sem Docker, com a variável de ambiente DATABASE_URL configurada:

$ minha-receita api

Com Docker:

$ docker compose up