Console Application
1 Configuração
O BalanceSheet.CMD é configurado à partir de um arquivo appsettings.json presente na pasta raiz do pacote. A release contém um arquivo chamado appsettings.example.json contendo os campos necessários.
{
"ModelApiRoute": "https://bdscloudapi.azurewebsites.net",
"ModelApiContingencyStatus": "https://bdsstatus.azurewebsites.net/Contingency/azure",
"ModelApiContingencyRoute": "https://bdscloudapi-contingency.azurewebsites.net",
"ModelApiUser": "",
"ModelApiPassword": "",
"BalanceSheetApiUrl": "https://app.bds.dev.br/api/balancesheet",
"BalanceSheetApiVersion": 1,
"BdsGuardianUrl": "https://app.bds.dev.br/auth",
"BdsGuardianClientRealm": "Hmg",
"BdsGuardianClientId": "balancesheet",
"BdsGuardianClientSecret": "",
"LogDir": "Logs",
"ExportTimeOut": 300
}
1.1 Model API
A Model API é utilizada para se conectar ao BDS, atualmente no comando ExportToBds. São necessárias 3 urls e um usuário e senha para autenticação.
Url
| Setting | Descrição | Tipo | Criptografia |
|---|---|---|---|
| ModelApiRoute | Url da Model API apontando para o ambiente desejado. | string | --- |
| ModelApiContingencyStatus | Url que retorna se a url de contingência está sendo utilizada. | string | --- |
| ModelApiContingencyRoute | Url da Model API que será utilizada caso esteja em contingência. | string | --- |
Autenticação
| Setting | Descrição | Tipo | Criptografia |
|---|---|---|---|
| ModelApiRoute | Url da Model API apontando para o ambiente desejado. | string | DH |
| ModelApiContingencyStatus | Url que retorna se a url de contingência está sendo utilizada. | string | DH |
1.2 BalanceSheet API
A BalanceSheet API é utilizada para se comunicar com o banco de BalanceSheets, atualmente no comando ExportToBds. É necessária uma url e a versão da api, junto com informações do BDS Guardian para autenticação.
Url
| Setting | Descrição | Tipo | Criptografia |
|---|---|---|---|
| BalanceSheetApiUrl | Url da BalanceSheet API apontando para o ambiente desejado. | string | --- |
| BalanceSheetApiVersion | Versão da API sendo utilizada, geralmente 1. | int | --- |
Autenticação
| Setting | Descrição | Tipo | Criptografia |
|---|---|---|---|
| BdsGuardianUrl | Url do BDS Guardian. | string | --- |
| BdsGuardianClientRealm | Realm que será apontado. | string | --- |
| BdsGuardianClientId | Id do cliente. | string | --- |
| BdsGuardianClientSecret | Segredo do cliente. | string | DH |
1.3 Outros
| Setting | Descrição | Tipo | Default |
|---|---|---|---|
| LogDir | Diretório onde será salvo o arquivo log. | string | "Logs" |
| ExportTimeOut | Timeout para chamadas de api em segundos. | int | 300 |
2 ExportToBds
O comando "ExportToBds" é responsável por exportar os dados de balanço para a base BDS de acordo com o AnalysisReport passado. As famílias, séries e atributos devem estar criados e devidamente associados na base apontada pela Model API.
Exemplo:
BalanceSheet.CMD.exe ExportToBds -idExport:2 -segmentId:3 -isConsolidated:true -referenceDate:2020 -companyGroup:100 -companyId:33000167000101,00000000000191
2.1 Parâmetros
| Parâmetro | Descrição | Tipo | Default | Exemplo |
|---|---|---|---|---|
| idExport | Id do AnalysisReport escolhido. | int | Req | 2 |
| segmentId | Segmento das empresas que deseja exportar. | byte | Req | 3 |
| isConsolidated | Grupo DFP das empresas que deseja exportar. | bool | Req | true |
| referenceDate | Data de referência no formato yyyy ou yyyyQ[1-4]. | string | Req | 2020 |
| companyGroup | Número de empresas que serão inseridas na base simultaneamente. Opcional. | int | 100 | 50 |
| companyId | Lista com o id (CNPJ) de empresas específicas para exportar. Opcional. | string[] | [] | 33000167000101, 00000000000191 |
2.2 AnalysisReport
As exportações são baseadas nas definições da tabela AnalysisReport e relacionadas:
Representação de um analysis report de exportação em json para facilitar a visualização (apenas partes principais, tabelas n-1 foram integradas no objeto n):
{
"id": 2,
"name": "Exportacao BDS",
"type": "Relatório BDS",
"reportItems": [
{
"title": "Exportação BDS",
"type": "BDS Valorfam",
"segments": [
{"segmentId": 3, "isConsolidated": true}
],
"bdsCodFam": 9101,
"bdsInterval": 4,
"attributes": [
{
"id": "a1.04",
"source": "BalanceSheet.API",
"type": "Account",
"isSerial": true,
"targetId": "a9020",
"targetType": "BDS Value"
},
{
"id": "i18",
"source": "BalanceSheet.API",
"type": "Indicator",
"isSerial": true,
"targetId": "a9021",
"targetType": "BDS Value"
},
{
"id": "socialname",
"source": "BalanceSheet.API",
"type": "Company",
"isSerial": false,
"targetId": "codser",
"targetType": "BDS Series"
},
{
"id": "cvmregisterid",
"source": "BalanceSheet.API",
"type": "Company",
"isSerial": false,
"targetId": "c9043",
"targetType": "BDS Cadaster4 (datetime)"
}
]
}
]
}
Para fins de explicação, toda coluna será citada no seguinte formato: nomeTabela.nomeColuna (nomeJson).
Para a ExportToBds, o analysisReport.analysisReportTypeId (type) sempre deve ser 2 ("Relatório BDS"). Assim como todo reportItem deve ter reportItem.reportItemType (reportItems[*].type) como 6 ("BDS Valorfam").
As colunas reportItemSegment.segmentId (reportItems[*].segments[*].segmentId) e reportItemSegment.isConsolidated (reportItems[*].segments[*].isConsolidated) são os mesmos valores especificados nos parâmetros segmentId e isConsolidado da command line respectivamente.
As colunas reportItem.bdsCodFam (reportItems[*].bdsCodFam) e reportItem.bdsInterval (reportItems[*].bdsInterval) representam a família (que já deve estar criada) e o intervalo em que os dados desse report item serão inseridos. Deve ser feito outro ReportItem caso seja necessário inserir dados em outro intervalo.
2.2.1 Attribute
A tabela attribute possui as definições de atributos de BalanceSheet sem conectá-los a reportItems ou atributos BDS. As colunas mais importantes são:
attribute.id (reportItems[*].attributes[*].id)attribute.attributeSourceId (reportItems[*].attributes[*].source)attribute.attributeTypeId (reportItems[*].attributes[*].type)
A coluna attribute.attributeSourceId (reportItems[*].attributes[*].source) representa a origem do dado que esse atributo deve coletar. Atualmente existem 2 possibilidades:
| Id | Name |
|---|---|
| 1 | BalanceSheet.API |
| 2 | SmartAPI |
Para este comando apenas dados de BalanceSheets serão usados, todos os outros serão ignorados caso existam em um ReportItem.
A coluna attribute.attributeTypeId (reportItems[*].attributes[*].type) representa o tipo do dado que esse atributo deve coletar, bem como a origem dentro de BalanceSheets e sua serialidade (se é um dado temporal ou fixo). Atualmente existem 4 possibilidades:
| Id | Name | IsSerial | Descrição |
|---|---|---|---|
| 1 | Account | true | Dados de BalanceSheet vindos da tabela balanceSheetAccount. |
| 2 | Indicator | true | Dados de BalanceSheet vindos da tabela balanceSheetIndicator. |
| 3 | Price | true | Dados da SmartAPI. |
| 4 | Company | false | Dados de BalanceSheet vindos da tabela company. |
A coluna attribute.id (reportItems[*].attributes[*].id) representa o id do atributo que deverá ser localizado, nesse caso, na própria base do BalanceSheets. O formato desse id vai depender de seu tipo, a convenção atual é de utilizar o prefixo "a" para Account (Ex.: a1.01.01) e "i" para Indicator (Ex.: i12). Os prefixos foram definidos para que não exista ambiguidade entre contas de nível 1 e indicators (Ex.: A conta "1" e o indicador "1").
2.2.2 ReportItemAttribute
É na tabela reportItemAttribute que os ReportItems são conectados à seus atributos, além de conter informações de como eles devem ser exibidos nesse item específico. Para ExportToBds, além do relacionamento, as colunas importantes dessa tabela são:
-reportItemAttribute.targetId (reportItems[*].attributes[*].targetId)
-reportItemAttribute.targetTypeId (reportItems[*].attributes[*].targetType)
Existem 6 target types, que definem onde os dados devem ser inseridos na BDS.
| Id | Name | Descrição |
|---|---|---|
| 1 | BDS Value | Dado inserido na valorfam. |
| 2 | BDS Series | Dado utilizado para identificar a série, atualmente apenas codser funciona. Apenas o primeiro valor desse tipo será considerado. |
| 3 | BDS Cadaster1 (float) | Dado cadastral na coluna 1. |
| 4 | BDS Cadaster2 (int) | Dado cadastral na coluna 2. |
| 5 | BDS Cadaster4 (datetime) | Dado cadastral na coluna 4. |
| 6 | BDS Cadaster5 (varchar) | Dado cadastral na coluna 5. |
Os TargetIds identificam especificamente o id em que o atributo será inserido. Para BDS Value os valores devem ter prefixo "a" (Ex.: a9020), para BDS Cadaster os valores devem ter prefixo "c" (Ex.: c9041). Nenhum prefixo é necessário para BDS Series.
Atualmente cada companhia é uma série identificada por um atributo BDS Series apontando para seu codser. Caso esse atributo não exista, a companhia será ignorada.
3 ExportApi
O comando "ExportApi" é responsável por exportar os dados de retorno de uma API para um arquivo local no formato especificado. Neste projeto ele é utilizado em conjunto com a rota de exportação da BalanceSheets API.
Exemplo (senha fictícia):
BalanceSheet.CMD.exe ExportApi -urlApi:"https://app.bds.dev.br/api/balancesheet/v1/BalanceSheet/export?isFlatten=true&isConsolidated=true&balanceSheetTypes=DFP&balanceTypes=BPA,BPP&referenceDates=2020" -outputPath:"D:\BDS\Novas Estruturas de Dados\Export2020.csv" -type:CSV -formatPath:"FormatExamples\FlattenFormat1.json" -authType:"BdsGuardian" -realm:"Hmg" -username:"balancesheet" -password:"faoAIIfa564adA5fa4wWWDaEGAagj68WR6EGjEGH48684sdg6AA"
3.1 Parâmetros
| Parâmetro | Descrição | Tipo | Default | Exemplo |
|---|---|---|---|---|
| urlApi | Url que será utilisada para a requisição. | string | Req | "https://app.bds.dev.br/api/..." |
| outputPath | Nome e caminho do arquivo de resultado. | string | Req | "Result\Export.csv" |
| type | Tipo do arquivo de resultado. | string | Req | XML |
| node | Nome da raiz em caso de XML. | string | null | Balances |
| separator | Separador de dados em caso de CSV. | string | ; | , |
| formatPath | Caminho do arquivo de formatação. | string | null | "Formats\NestedXml.json" |
| authType | Tipo de autenticação. | string | null | "Basic" |
| token | Token em caso de autenticação "Bearer Token". | string | null | "uguyg4G6Aa..." |
| username | Username em caso de autenticação "Basic" ou clientId para "BdsGuardian". Criptografado em DH. | string | null | username |
| password | Password em caso de autenticação "Basic" ou clientSecret para "BdsGuardian". Criptografado em DH. | string | null | "faoAIIfa56a..." |
| realm | Realm em caso de autenticação "BdsGuardian". | string | null | "Prod" |
3.2 Tipos de Arquivo
Os tipos de arquivo aceitos no parâmetro "type" são:
| Tipo | Descrição |
|---|---|
| CSV | Apenas para APIs com resultados não aninhados, JSONs com apenas um nível de profundidade. O caractere separador pode ser indicado através do parâmetro "separator". |
| TXT | Idêntico ao CSV. |
| JSON | Resultado igual ao da API, possívelmente com a formatação customizada. |
| XML | O nó de raiz pode ser informado no parâmetro "node". |
3.3 Autenticação
Atualmente existem 3 tipos possíveis de autenticação:
Basic
O tipo Basic manda um simples usuário e senha no header de autenticação do request. A senha deve estar criptografada com o método DH. Os parâmetros utilizados são "username" e "password".
Authorization: Basic username:password
Bearer Token
O tipo Bearer Token manda um token no header de autenticação do request. Ele pode ser passado pelo parâmetro "token" e deve estar criptografado com o método DH.
Authorization: Bearer Token adi1OI5A56J5W6adoija...
BdsGuardian
O tipo BdsGuardian utiliza a url configurada no appsettings.json porém com as credenciais passadas nos parâmetros.
É feito um request para o BdsGuardian utilizando as seguintes informações:
- realm = realm
- username = clientId
- password = clientSecret
Onde "password" deve ser criptografado com o método DH.
Em seguida é utilizado o token resultante no request principal da mesma forma que em Bearer Token.
3.4 Formatação
É possível passar, no parâmetro "formatPath", um arquivo para a formatação do resultado. Este arquivo consiste em um JSON com o seguinte formato:
{
"default_culture": "",
"fields": [
{"source":"companyCnpj", "name":"CNPJ", "type":"custom", "preset":"cnpj"},
{"source":"companyName", "name":"Name", "type":"text", "preset":"uppercase", "culture":"pt-BR"}
],
"custom_presets": [
{"name":"cnpj", "type":"replace", "regex":"^(\\d{2})(\\d{3})(\\d{3})(\\d{4})(\\d{2})", "replace":"$1.$2.$3/$4-$5", "culture":"pt-BR"}
]
}
3.4.1 Culture
A cultura desejada pode ser passada em quaisquer dos objetos aninhados do JSON, assim como em um campo principal chamado "default_culture".
A seguinte prioridade é utilizada para definir a cultura: "fields" > "custom_presets" > "default_culture"
A cultura é utilizada principalmente na formatação de valores numéricos. Uma documentação à respeito dos possíveis valores pode ser encontrada na coluna "Language tag" na lista de idiomas/regiões suportadas pelo Windows. Caso nada seja passado, será utilizada a "InvariantCulture".
Mais informações sobre culture podem ser encontradas aqui.
3.4.2 Fields
Os fields representam as propriedades do JSON retornado da API e a formatação que será aplicada à ele. Qualquer propriedade não presente aqui será formatada com as configurações padrões (um simples "ToString" com a "default_culture".)
Source
O campo Source contém informação sobre como encontrar a propriedade a ser formatada no JSON de resposta. Em um JSON não aninhado, isso é simplesmente o nome da propriedade, já para JSONs aninhados é necessário utilizar a "dot-notation".
Exemplo de resposta:
[
{
"companyName": "Petrobrás",
"balances":[
{"id": "1.01", "value": "2151651.54"},
{"id": "1.02", "value": "1651651.9"}
]
}
]
Exemplo de sources para cada propriedade:
{
"fields":[
{"source":"companyName"},
{"source":"balances[*].id"},
{"source":"balances[*].value"},
{"source":"balances"},
]
}
Name
O campo Name representa o nome desejado para a propriedade no arquivo de output. É possível trocar o nome de qualquer propriedade da resposta, tomando cuidado para renomear nodes apenas após trabalhar com os objetos aninhados nele, pois a formatação acontece na ordem em que os fields aparecem no arquivo de formatação.
Exemplo de resposta:
[
{
"companyName": "Petrobrás",
"balances":[
{"id": "1.01", "value": "2151651.54"},
{"id": "1.02", "value": "1651651.9"}
]
}
]
Exemplo de formatação:
{
"fields":[
{"source":"companyName", "name":"Empresa"},
{"source":"balances[*].id", "name":"Código"},
{"source":"balances[*].value", "name":"Valor"},
{"source":"balances", "name":"Balanços"},
]
}
Resultado esperado:
[
{
"Empresa": "Petrobrás",
"Balanços":[
{"Código": "1.01", "Valor": "2151651.54"},
{"Código": "1.02", "Valor": "1651651.9"}
]
}
]
Type
O tipo de formatação que será aplicada. No momento existem 2 tipos possíveis:
| Tipo | Descrição |
|---|---|
| text | Contém presets para manipulação de case. |
| custom | Utiliza os presets definidos no campo "custom_presets". |
Preset
Este campo define a formatação do valor da propriedade da resposta. Este campo pode ser qualquer preset definido em "custom_presets" ou algum dos "presets" definidos em outros tipos.
Os presets possíveis são:
Text
| Preset | Original | Formatado |
|---|---|---|
| uppercase | Petrobras | PETROBRAS |
| lowercase | Petrobras | petrobras |
| title_case | PETRÓLEO BRASILEIRO | Petróleo Brasileiro |
3.4.3 Custom Presets
Os custom presets são onde as formatações mais complexas acontecem. Os campos possíveis dependem do tipo de preset sendo criado, os únicos campos presentes em todos são: "name", "type" e "culture".
| Campo | Descrição |
|---|---|
| name | Nome utilizado no campo "preset" dos fields. |
| type | Tipo do preset. Define os campos extras para configurar a formatação. |
| culture | Campo presente em todos os objetos. Define a cultura utilizada na formatação. |
Replace
Utiliza regex para aplicar uma formatação.
| Campo | Descrição |
|---|---|
| regex | Regex para dar match na informação. |
| replace | Expressão de replace para aplicar nos matches. |
Outros
Os outros tipos utilizam "ToString" com certas configurações para formatar os resultados.
Tipos:
Todos esses tipos possuem o campo format, que utiliza as notações específicas de cada tipo no C# para aplicar as formatações. Mais informações podem serem encontradas clicando em cada um dos tipos acima.
DateTime
DateTime possui um campo extra chamado "exact". Diferente dos outros campos de formatação, esse campo é utilizado para definir o formato esperado da informação da API, útil para indicar se uma data deve ser esperada em formato 'dd/MM/yyyy' ou 'MM/dd/yyyy', por exemplo. Mais informações em "Remarks" na documentação oficial.