Escopo do Projeto

BalanceSheet.API é uma solução web que ofere uma ampla cobertura de dados abertos bem como templates e geração de relatórios sobre dados de balanços patrimoniais de diversas companias listadas em bolsa

1.0 Objetivos

Dados do mercado financeiro são, de maneira geral, desorganizados e fora do padrão desejado pelo mercado.

Em geral, agentes financeiros como bancos, corretoras e investidores buscam fazer análises para tomadas de decisões através de análises verticais e análises horizontais sobre dados de balanços patrimoniais e dos indicadores fundamentalistas de diversas empresas.

O projeto tem como foco a padronização destes dados bem como a criação de templates dinâmicos que preparam os dados de maneira centralizada, confiável, performática e customizável em diversos formatos de arquivo: txt, csv, xls, etc.

BalanceSheet.API oferece endpoints através de protocolos http (Web API) onde clientes da BDS podem acessar esses dados da meneira que for necessária.

2.0 Linguagem Ubíqua

Linguagem Ubíqua ou Computação Ubíqua pode ser definida por:

Computação ubíqua tem como objetivo tornar a interação humano computador invisível, ou seja, integrar a informática com as ações e comportamentos naturais das pessoas. Não invisível como se não pudesse ver, mas, sim de uma forma que as pessoas nem percebam que estão dando comandos a um computador, mas como se tivessem conversando com alguém. Além disso, os computadores teriam sistemas inteligentes que estariam conectados ou procurando conexão o tempo todo, dessa forma tornando-se assim onipresente.

fonte : https://pt.wikipedia.org/wiki/Computa%C3%A7%C3%A3o_ub%C3%ADqua

Em outras a Linguagem Ubíqua permite que possamos manter a comunicação da equipe mais padronizada e que possamos nos "comunicar" da mesma forma via código, nomeação de campos e variáveis e por assim vai.

2.1 BalanceSheetDocument

Entidade que representa metadados de um balanço patriomonial. O id de um BalanceSheetDocument é composto de 3 chaves:

companyId: Cnpj da empresa;
balanceSheetTypeId: DFP ou ITR;
referenceDate: 2020Q4, 2019Q2...

Como são gerados(as)?

Cada BalanceSheetDocument é fruto de importação de arquivo corrido pelo processo de importação das functions através das filas do Azure Storage Account.

2.2 Account

Entidade que representa as contas como elas aparecem na fonte (CVM), com seu código e nome originais. Estes são os dados relacionados em BalanceSheetDocument para a atribuição de um valor para cada conta.

Como são gerados(as)?

Essas contas são criadas durante a importação dos arquivos da fonte. Seu id é gerado à partir do código sem pontos e das 3 primeiras e últimas letras do nome.

Ex.: 1.06.01 Imobilizado de Uso = 10601IMOUSO.

Além disso sua chave é composta com a informação do segmento da empresa (Financeiras, Seguradoras, Outras) e grupo DFP (consolidado ou individual).

Branches

As Branches são diferentes planos de contas que podem ser cadastrados contanto que possuam uma relação direta com o plano de contas da fonte (CVM). Existe um mecanismo de herança em que uma branch filha herda todas as definições de uma branch pai caso o cliente queira criar uma branch própria baseada em uma já existente, modificando apenas algumas das contas.

As contas BDS (Contas que definimos internamente como as mais importantes através de consultoria especializada) são definidas em accountDictionary, onde possuem a branch BDS (a padrão, definida internamente), um código padronizado, um segmento, grupo DFP, nome principal e uma lista de aliases.

Depois desse seeding as contas vindas das fontes de publicação serão importadas e comparadas com as importadas no seeding, essa comparação leva em conta uma lógica de match para com as contas BDS.

Como funciona o processo de importação das contas?

Os matchs das contas são registrados em chartOfAccount e classificados de acordo com dois parâmetros diferentes: LevelFit e NameFit.

O LevelFit só é falso caso o código da conta que está sendo importada for de um nível mais profundo do que as definições de seu respectivo galho no dicionário. O nível de um código pode ser facilmente identificado como o número de seções de um código (ex.: 1.01.02.03 é nível 4). Os exemplos a seguir demonstram o LevelFit:

Source Code	Dictionary Code	LevelFit	Explicação
1.01	1.01	true	Encontrado.
1.01.01	1.01.01	true	Encontrado.
1.01.02	---	true	O galho 1.01 vai até o nível 3, como visto na linha acima, logo 1.01.02 está dentro do nível.
1.02	1.02	true	Encontrado.
1.02.01	1.02.01	true	Encontrado.
1.02.01.01	---	false	O galho 1.02.01 vai apenas até o nível 3. e 1.02.01.01 é nível 4.
1.02.02	1.02.02	true	Encontrado.

Caso o código da conta que esta sendo importada não existir dentro do nível mais profundo de um determinado galho, ela será considerada "Out of Level", e seu status em chartOfAccount será "NoFit", ou "OnlyNameFit", dependendo do NameFit.

Para que o NameFit seja verdadeiro, é necessário que o nome da conta importada esteja em algum dos aliases definidos no dicionário do respectivo nível do galho. Este processo definirá o Branching Code, que será o código exibido normalmente, caso não seja encontrado um match, o código deve terminar com "00". Exemplos:

Dicionário

Dictionary Code	Dictionary Alias
1	Ativo
1.01	Ativo Circulante
1.01.01	Caixa
1.01.02	Outros
1.02	Ativo Não Circulante
1.02.01	Longo Prazo

Fonte + chartOfAccount

Source Code	Source Name	Branching Code	fitted	Explicação
1	Ativo	1	true	Busca em x. Encontrado 1.
1.01	Ativo Não Circulante	1.02	true	Busca em 1.xx. Encontrado 1.02.
1.01.01	Longo Prazo	1.02.01	true	Busca em 1.02.xx. Encontrado 1.02.01.
1.01.02	Outros	1.02.00	false	Busca em 1.02.xx. Não encontrado.
1.02	Ativo Circulante	1.01	true	Busca em 1.xx. Encontrado 1.01.
1.02.01	Caixa	1.01.01	true	Busca em 1.01.xx. Encontrado 1.01.01.
1.02.03	Aplicações Financeiras	1.01.00	false	Busca em 1.01.xx. Não encontrado.
1.02.03.01	Financeiras Diferentes	1.01.00.00	false	Busca em 1.01.00.xx. Se pai é .00, filho também é.
1.02.04	Outros	1.01.02	true	Busca em 1.01.xx. Encontrado 1.01.02.

Nota-se que a cada conta processada é necessário levar em conta seu match pai. O código original serve apenas para manter a estrutura e os níveis da árvore equivalentes. O LevelFit obedece às mesmas regras (o galho analisado para o maior nível é o match pai, não o pai original), porém foi simplificado no exemplo anterior para facilidade de demonstração.

Uma conta que não teve seu nome encontrado, é chamada de "No Match". O campo "fitted" na "chartOfAccount" será "false" e seu status será "NoFit" ou "OnlyLevelFit", dependendo do LevelFit.

A seguinte tabela demonstra a relação entre todos os possíveis status dos matches:

NameFit	LevelFit	Status	Fitted
false	false	NF - NoFit	false
false	true	OLF - OnlyLevelFit	false
true	false	ONF - OnlyNameFit	true
true	true	FF - FullFit	true

2.3 AccountType

Tipo da conta. Uma conta pode ter um dos 7 tipos abaixo:

Id	Nome	Ref
BPA	Balanço Patrimonial Ativo	https://pt.wikipedia.org/wiki/Ativo
BPP	Balanço Patrimonial Passivo	https://pt.wikipedia.org/wiki/Passivo_(contabilidade)
DFCMI	Demonstração de Fluxo de Caixa (Método Indireto)	https://pt.wikipedia.org/wiki/Fluxo_de_caixa
DMPL	Demonstração das Mutações do Patrimônio Líquido	https://pt.wikipedia.org/wiki/Demonstra%C3%A7%C3%A3o_das_muta%C3%A7%C3%B5es_do_patrim%C3%B4nio_l%C3%ADquido
DRA	Demonstrativo de Resultado Abrangentes	https://pt.wikipedia.org/wiki/Demonstra%C3%A7%C3%B5es_cont%C3%A1beis
DRE	Demonstração do Resultado do Exercício	https://pt.wikipedia.org/wiki/Demonstra%C3%A7%C3%A3o_do_resultado_do_exerc%C3%ADcio
DVA	Demonstração do Valor Adicionado	https://pt.wikipedia.org/wiki/Demonstra%C3%A7%C3%A3o_do_valor_adicionado

2.3 Formulas

As formulas são entidades que representam cálculos que seguem um padrão similar de processamento, através das Expressions. Suas definições sempre necessitam, além de um id, do Grupo DFP (consolidado, ou não) e de um Segment para que os elementos sejam corretamente discriminados e identificados. Seus resultados estarão sempre atrelados à um BalanceSheetDocument.

Atualmente existem 2 tipos de dados calculados:

2.3.1 Indicators

Entidade que representa os indicadores fundamentalistas. Um indicador, como outras Formulas, é definido no sistema sabendo-se: Seu id, se é consolidado ou não e a qual Segment ele pertence. Suas Expressions são utilizadas para calcular o valor numérico decimal dos BalanceSheetIndicators.

Cada Indicator deverá gerar um BalanceSheetIndicator para cada BalanceSheetDocument de uma empresa de mesmo Segment, utilizando a expression para calcular seu valor. Suas Expressions são utilizadas para calcular o valor numérico decimal dos BalanceSheetIndicators.

2.3.2 DataQuality

DQFormulas são as entidades que representam as definições de DataQuality, presentes em um banco de dados separado. Também são definidas com um id, Grupo DFP e um Segment. Suas Expressions são utilizadas para calcular o valor booleano dos BalanceSheetDataQualityResult.

2.3.3 Expression

Algumas notações são utilizadas nas expressões para sinalizar qual dado deve ser buscado, sua fonte, data ou o que ser feito caso não seja encontrado.

Operadores e Funções

Operadores aritiméticos:

Operador	Descrição
+	Adição
-	Subtração
*	Multiplicação
/	Divisão
%	Resto (Módulo)
**	Potenciação

Operadores lógicos:

Operador	Descrição
&&	AND
\|\|	OR
!	NOT
<	Menor
<=	Menor ou igual
==	Igual
>=	Maior ou igual
>	Maior
!=	Diferente

Funções condicionais:

Função	Exemplo
condição ? verdadeiro : falso	[2.01.01] != 0 ? [2.01.01] : [2.01]

Outras possibilidades podem ser encontradas na documentação da library utilizada para a efetuação dos cálculos, porém algumas foram modificadas ou desativadas: ExpressionEvaluator

Elementos de dado

Os elementos que deverão ser substituídos por dados sempre estarão sozinhos entre colchetes ou parênteses. Qualquer número que esteja sozinho entre parênteses, não é um número literal, e sim o código para procurar algum valor na base.

Exemplo	Descrição
*(1) - (2.05) [3.02.01] / (2.01 + 3)**	Nesse caso, os elementos são (1), (2.05) e [2.02.01]. Os números 2.01 e 3 são apenas literais
(2.01\|-2) [#lastPric.4#] >= 0**	Elementos: (2.01\|-2) e [#lastPric.4#]

Coringa

O caractere '*' pode ser utilizado em AccountIds em dados de BalanceSheetAccount. Um elemento com esse caractere será substituído por uma soma de todas as suas contas filhas.

Dados de exemplo:

AccountId	Value
1.01	109
1.01.01	1
1.01.02	4
1.01.03	8
1.01.03.01	16
1.01.04	32
1.01.00	64
1.01.00.00	128
1.02	256
1.02.01	512
1.02.02	1024

Exemplos:

Formula	Resultado
*(1.01.) == (1.01)**	true
*(1.02.)**	1553

NullHandle

Os parênteses e colchetes em volta dos elementos identificam o que deve ser feito caso aquele elemento não seja encontrado.

Tipo	Exemplo	Descrição
Skip	(1.03)	Elementos entre parênteses não encontrados deverão cancelar a operação e pular o cálculo em questão. Esse indicador não deve aparecer no resultado.
Zero	[3.03]	Elementos entre colchetes não encontrados deverão ser substituídos por 0 (zero) na expressão, e o cálculo deve continuar normalmente.

DateOffset

Em alguns elementos, será encontrado um pipeline ( | ) com um número inteiro à direita. Esse número representa um offset na data que será buscada referente ao período sendo calculado.

Caso o BalanceSheetDocument sendo calculado seja anual (DFP, Data yyyy), este número representa o período por ano ("2020", "|-5" significa "5 anos antes" e deverá ser buscado em "2015"), caso seja trimestral (TRI, Data yyyyQ[1-4]), este número representa o período por trimestre ("2020Q1", "|-2" significa "2 trimestres atrás" e deverá ser buscado em "2019Q3").

ReferenceDate	Element	Descrição
2019	[1.05\|+1]	O elemento deve ser buscado em 2020
2021Q3	(#maxPric.3F#\|-2\|)	O elemento deve ser buscado em 2021Q1 (Perceba a notação um pouco diferente que também é aceita por legacy)

Source

Existem 2 fontes possíveis para os dados em um indicador atualmente, e os identificadores são hashes (#) em volta do código do elemento em questão.

Fonte	Exemplos	Descrição
BalanceSheetAccount	(2.01) (1.06)	A consulta é feita na nossa própria base pela nossa API, utilizando o AccountId da tabela BalanceSheetAccount
SmartAPI	(#lastPric.4#) [#minPric.11#]	A consulta é feita pela SmartAPI, o valor antes do ponto é o field e o valor depois do ponto é uma identificação do symbol baseado no socemi. O valor utilizado é sempre o último dentro daquele período.

Symbols e Socemis

Cada company pode possuir diversos symbols/tickers utilizados na bolsa para identificar o tipo de ação. Como os fields são diferentes para cada tipo, é necessário diferenciá-los. Na base, o socemi está na tabela Company e eles são basicamente a raiz dos símbolos, única para cada companhia (ex.: PETR, CTCA). Na tabela Symbol estão presentes todos os tickers que existem naquela companhia (ex.: PETR4F, PETR3, CTCA4). A diferença entre o symbol e o socemi é o valor utilizado depois do ponto nos códigos da SmartApi. Existe também uma forma legacy de representação que é aceita (ex.: [#symbol4.lastPric#]).

2.4 BalanceSheetAccount

Contas de um determinado balanço

2.5 BalanceSheetIndicator

Indicadores de um determinado balanço, seu resultado é decimal.

2.6 Company

Todas as empresas das publicações da CVM

Cada uma dessas empresas podem ser dividias em três grupos:

Tipo	Descrição
Abertas	O capital é constituído por ações que podem ser negociadas na Bolsa de valores
Estrangeiras	Assemelha-se às empresas abertas, porém estrangeiras
Incentivadas	São empresas que recebem incentivos fiscais por estarem localizadas em regiões de interesse econômico

2.7 Socemi

Propriedade de uma empresa composta por 4 digitos (Que abrevia a razão social (nome) da empresa, por exemplo: Petrobras = PETR

2.8 Symbol

Propriedades de uma empresa, trata-se do seu código na bolsa de valores, é formada pelo Socemi + um número

2.9 MarketType

Entidade que representa os tipos de mercado da bolsa, por exemplo: Balcão Organizado, Balcão Não Organizado, Bolsa

2.10 Issuer

Entidade que representa a emissão do balanço, composto por uma situação, por exemplo “Fase Operacional” ou “Em liguidação Judicial” e pela respectiva data de emissão

2.11 Situation

Representa a situação de uma empresa

2.12 Sector

Representa o setor de atuação de uma empresa

2.13 Segment

Representa o segmento de atuação das empresas detentoras dos dados de balanços. Empresas de diferentes segmentos possuem diferentes métricas e análises fazendo com que sua contabilidade em geral seja afetada de modo que a interoperabilidade de documentos financeiros entre empresas de diferentes segmentos seja reduzida.

Por isso dizemos que empresas de diferentes segmentos possuirão diferenças nas contas, indicadores fundamentalistas e, por sua vez, relatórios

Existem três tipos de segmentos:

Financeiras
Seguradoras
Outras

2.14 Package

Representa um pacote de empresas

2.15 PackageList

Entidade que lista empresas de cada pacote