Já tenho a licença do Studio liberada?​

Não: Verificar com o comercial para realizar a liberação

Já tenho o meu projeto configurado no Studio?​

Não: Configurar projeto no Studio

O projeto é o ponto inicial e central para que os parceiros realizem todas as configurações e possam inserir as credenciais necessárias para integrar suas aplicações com nossos produtos.

Um projeto pode conter uma ou mais credenciais que permitem a interação de uma aplicação de terceiros com as APIs dos produtos Betha Cloud.

No Studio Aplicações, um novo projeto pode ser criado na tela inicial da aplicação, utilizando o botão +Projeto.

Já sei qual tipo de credencial preciso (Serviço / Browser)?​

Não: conhecer tipos de credencial

Aplicação no Browser: usada em aplicações onde login e senha são transmitidos. O fluxo ocorre da seguinte forma: a ferramenta Auth envia um usuário e senha e, em seguida, recebe um código que é enviado novamente para o Auth, que então retorna o token. É uma aplicação de front-end em nome de um usuário, ou seja, quando o parceiro desenvolve um produto que segue um fluxo de front-end.

Aplicação no Servidor: São APIs consumidas por aplicações back-end em nome de um usuários, com o token armazenado no servidor. Por exemplo, ao fazer login em um sistema, o acesso à API é realizado usando as credenciais do servidor. Essa credencial é associada a uma chave pública e uma chave privada, gerando um access-token.

Serviço: As API's são consumidas em nome da própria aplicação e o token não expira. Além disso, ao renovar o token, o anterior permanece válido. Ou seja, mesmo que um novo token seja gerado, o anterior continua funcionando normalmente. É importante lembrar que atualmente não há maneira de revogar um token gerado anteriormente e o campo Webhook é utilizado ao liberar uma aplicação em um sistema e envia um evento para o endpoint cadastrado, contendo o acesso do usuário que foi concedido. Esse tipo de integração é para consumo de API's direto, como: gerar Estado e BI.

Anônima: No caso de uma conexão anônima, o serviço se autentica com a Betha, porém não há um usuário individual vinculado a ele. Isso significa que certas áreas do sistema Betha possuem integrações com funcionalidades que não exigem autenticação. Por exemplo, é possível obter uma guia de IPTU com base no CPF.

Usuário e senha: são utilizados pelos aplicativos móveis, seguindo um fluxo semelhante ao da aplicação no navegador, porém mais simplificado: o aplicativo envia as credenciais de usuário e senha e, em troca, recebe o token de acesso.

Já tenho a credencial liberada no meu projeto?​

Não: [1º passo] Criar credencial

Para utilizar uma API dos produtos Betha Cloud é necessário que seu projeto, previamente criado, possua uma credencial cadastrada.

Todas as API´s disponíveis em nosso catálogo podem ser ativadas para utilização somente através de uma credencial. As API's possuem os escopos e endpoints disponíveis para consumo de dados.

A credencial fornece configurações adicionais e os tokens utilizados para consumir os dados disponíveis em uma API. Os tokens são:

Chave pública: A chave pública é usada para identificar a aplicação cliente em solicitações de autorização ao servidor. Ela é enviada em URLs de redirecionamento e outras comunicações que podem ser expostas ao público sem riscos significativos de segurança.

Chave privada: A chave privada é usada principalmente em fluxos de autenticação seguros, onde a confirmação de identidade é necessária, como no fluxo de authorization code do OAuth. Ela é incluída em solicitações ao servidor que não são expostas ao público, garantindo que apenas o cliente autorizado possa receber tokens de acesso e refresh tokens.

Token de acesso: é a chave utilizada para autenticar e autorizar as requisições realizadas nos endpoints das API´s ativadas na credencial. \

User-Access: é a chave que identifica o contexto dos dados específicos da entidade e sistema (tenancia).

Não: [2º passo] Liberar consumo de dados

Para habilitar uma credencial para consumir os dados de um sistema e entidade é necessário ter a aprovação nas duas pontas, uma por parte da Betha e outra por parte do cliente.

Através do link “Solicitar” no card do User-Access da credencial deve-se enviar uma solicitação de consumo de dados, selecionando a entidade e sistema desejado, e aguardar a aprovação da Betha. Depois da solicitação aprovada, deve-se encaminhar a chave pública para o cliente fazer a autorização da aplicação em sua entidade através do gerenciador de acessos do seu sistema, no menu “Aplicações”

Todos User-Access gerados pelos clientes podem ser consultados no card do User-Access da credencial no link “Ver detalhes”

Já tenho as APIs ativadas na minha credencial?​

Não: Adicionar APIs

Para habilitar o consumo de dados é necessário fazer a ativação da API para a credencial desejada.

As API´s possuem escopos e endpoints que possibilitam o acesso aos dados. Os escopos definem as operações possíveis (leitura, escrita, etc..) que podem ser realizadas pelos endpoints disponíveis na API.

Todas as API´s ficam disponíveis no catálogo de API´s do Betha Store e podem ser ativadas para utilização somente através de uma credencial.

Já renovei o token de acesso com os escopos necessários?​

Não: Renovar o token de acesso

Existem duas situações que necessitam a renovação do token de acesso, a ativação de novas API´s e a atualização dos escopos de uma API ativada na credencial.

As API´s possuem escopos e endpoints. Os escopos definem as operações possíveis (leitura, escrita, etc..) que podem ser realizadas através dos endpoints disponíveis na API.

Sempre que for atualizado a configuração dos escopos de uma API o token de acesso necessita ser renovado para habilitar as operações referentes a nova configuração de escopo. Para renovar e gerar um novo token, clique na funcionalidade [Renovar] do card do token de acesso.

Já fiz uma requisição?​

Não: Realizar uma requisição

Existem duas situações que necessitam a renovação do token de acesso, a ativação de novas API´s e a atualização dos escopos de uma API ativada na credencial.

Para realizar uma requisição é necessário ter:

1. Credencial liberada (item 4)

2. API ativada na credencial (item 5)

3. Endpoint: Os endpoints disponíveis da API se encontram na seção “Documentação”

4. User-Access: Chave da credencial que identifica o Sistema e a Entidade dos dados (tenancy)

5. Authorization: Token de acesso da credencial, precisa ser renovado sempre que for adicionado novas API´s ou novos escopos

Exemplo:

curl  -X GET \  
'https://educacao.suite.betha.cloud/dados/v1/enturmacao-situacao-item-educacional' \
--header 'Accept: application/json' \
--header 'User-Access: X-f9B_hDjfE1_DEZosPj7WlTNj8bDDjdx5iScRzO3O8=' \
--header 'Authorization: bearer 5830f4b9-b726-5bf3-81b7-2ee4eeb00b73'

A elaboração de relatórios demanda diferentes abordagens, dependendo das preferências para visualização e utilização. Geralmente, trabalhar com PDF é mais simples do que com Excel, pois requer tentativas e erros para obter resultados satisfatórios.

Quando se trata do Excel, é essencial assegurar um alinhamento adequado de todas as colunas, a fim de evitar discrepâncias de tamanho na planilha.

Ao exportar para o Excel, o objetivo principal é manter a organização e a clareza para que os dados estejam prontos para filtragem, divisão, classificação e agrupamento, até que alcancem o resultado desejado.

É aconselhável criar duas guias: uma para os dados e outra para notas de rodapé. Na guia de dados, reserve uma linha para o nome do relatório ou logotipo da empresa, seguida por outra linha para os cabeçalhos das colunas e, por fim, insira as linhas com os próprios dados.

No Jaspersoft Studio

A seção de "Cabeçalho da Coluna" insira a tabela de dados, pois ter os dados em uma tabela permite: visualizá-los em HTML, classificar, entre outras interações. A tabela de dados conta com uma linha para os cabeçalhos das colunas e outra para os próprios dados.

Na seção "Resumo", é importante apresentar todas as seleções de entrada, abreviações, cálculos e informações relevantes. Para garantir uma apresentação limpa no Excel, evite inserir o nome do relatório e o logotipo da empresa no cabeçalho da coluna ou no cabeçalho da página, a menos que o relatório também seja exportado em formato PDF. Nesse caso, uma solução eficaz é inserir um "Elemento de Quebra de Página" no topo da seção de Resumo, com as seguintes configurações: x: 0 px, y: 0 px, altura de 1 pixel e Tipo de Posição: Fixe em relação ao topo.

Isso garantirá que a quebra de página seja colocada no topo da seção de Resumo, isolando-a das demais informações. Além disso, certifique-se de que todos os outros elementos na página de resumo tenham uma posição Y igual ou abaixo de 1, para evitar sobreposições com a quebra de página. Dessa forma, o Resumo será apresentado de maneira organizada e legível no Excel.

Além disso, é recomendável incluir uma seção intitulada "Sem Dados" que seja uma replicação da página de Resumo. Nessa seção, adicione um aviso destacado que diga: "Não foram encontrados dados para as seleções feitas", juntamente com o nome do relatório e o logotipo da empresa. A presença desta seção "Sem Dados" é importante quando as seleções feitas pelo usuário não resultam em dados disponíveis. Ela serve como um lembrete amigável de que é possível revisar as seleções feitas. Às vezes, um relatório vazio pode ser interpretado como um indicativo de que o sistema ou o relatório não estão funcionando corretamente. Portanto, é crucial comunicar que as escolhas feitas pelo usuário os conduziram a essa situação. Para garantir que tudo funcione adequadamente, o Relatório Principal deve utilizar a mesma consulta de conjunto de dados que a tabela.

Nas Propriedades do Relatório Principal, na seção Formato de Página, o Formato de Página tem as seguintes propriedades:

Formato: Letter (Carta).

Largura: Um relatório que abrange PDF e Excel, a largura é de 792 pixels.

Altura: Um relatório que abrange PDF e Excel, a altura é de 612 pixels.

Observação: O Excel não se importa com as margens especificadas aqui. O PDF lida bem com elas.

Unidades: pixel (mais fácil trabalhar com elas do que com polegadas).

Orientação da Página: Paisagem.

Margens: 36 para todas as margens.

Além disso, nas Propriedades do Relatório, possuem as seguintes seleções:

Tipo Quando Não Há Dados: Seção Sem Dados.

Resumo em Uma Nova Página: marcado.

Resumo com Cabeçalho e Rodapé de Página: marcado (ao desmarcar essa opção na seção de Resumo, teria que adicionar o nome do relatório e o logotipo da empresa).

Ignorar Paginação: conclui-se que a opção não marcada é a melhor, caso contrário, ao gerar um relatório no formato PDF ou Excel, o PDF não é paginado corretamente e não pode ser recuperado.

Nas Propriedades Avançadas do Relatório Principal, adicione as seguintes configurações:

• O JavaScript coloca apenas quantas linhas de dados couberem em uma única guia, de acordo com a Altura da Página.

<property name = "net.sf.jasperreports.export.xls.one.page.per.sheet" value="true"/>

• Remove uma linha com altura de linha muito grande no final da guia de dados. É importante ressaltar que, ao fazer isso, pode ser difícil ter espaçamento entre linhas nas notas de rodapé.

<property name="net.sf.jasperreports.export.xls.remove.empty.space.between.rows" value="true"/>

• Elimina colunas vazias, como aquelas causadas por margens ou por um layout deficiente.

<property name="net.sf.jasperreports.export.xls.remove.empty.space.between.columns" value="true"/>

• Exibe as linhas de grade no Excel. Caso contrário, obterá uma superfície branca sólida, o que pode prejudicar a aparência do Excel, especialmente quando se trata de despejo de dados.

<property name="net.sf.jasperreports.export.xls.white.page.background" value="false"/>

• Instrui o Excel a tratar as datas como datas e os números como números, em vez de todos serem tratados como texto quando essa configuração é definida como "false" (valor padrão).

<property name="net.sf.jasperreports.export.xls.detect.cell.type" value="true"/>

• Instrui o Excel a não excluir o gráfico do logotipo da empresa. Quando definido como "true" (valor padrão), o Excel exclui os gráficos automaticamente.

<property name="net.sf.jasperreports.export.xls.ignore.graphics" value="false"/>

• Precisa ser digitado ou colado diretamente no XML de origem.

<property name="net.sf.jasperreports.page.break.no.pagination" value="apply"/>

• Instrui o Excel a nomear a primeira guia como "Dados" e a segunda guia como "Notas de Rodapé". Em vez de "Dados", é recomendado algo mais descritivo, como o nome do relatório.

<property name="net.sf.jasperreports.export.xls.sheet.names.all" value="Data/Footnotes"/>

• Instrui o Excel a congelar as duas primeiras linhas. Portanto, uma vez no Excel, a linha com o nome do relatório e o logotipo da empresa, bem como a linha com os cabeçalhos das colunas, ficarão fixas no topo da planilha. Isso permite que o usuário role por milhares de registros e ainda consiga visualizá-los. Sem essa configuração, o usuário teria que fazer isso manualmente.

<property name="net.sf.jasperreports.export.xls.freeze.row" value="3"/>

• Impede que o JavaScript trunque valores mais largos do que as larguras de coluna explicitamente definidas. No Excel, isso é visto como quebra de texto automática (wrapping).

<property name="net.sf.jasperreports.print.keep.full.text" value="true"/>

• Impede que o JavaScript reduza o tamanho da fonte em 1 ponto ao exportar para o Excel. Por exemplo: sem essa configuração, uma fonte Arial 10 no Studio, quando exportada para o Excel no servidor, acabaria como uma fonte Arial 9.

<property name="net.sf.jasperreports.exports.xls.font.size.fix.enabled" value="false"/>

Para visualizar o material original clique aqui.

O Studio Extensões é uma plataforma de desenvolvimento para expandir as funcionalidades do ERP Suite Betha Cloud, focada na gestão pública. Possuímos uma modalidade de licença básica, permitindo que clientes possuam os recursos da plataforma.

A Licença básica funciona da seguinte forma: para as extensões criadas ou personalizadas pela entidade nas ferramentas do Studio Extensões, os processos de execução de automações e geração de relatórios são colocados em uma fila de recursos compartilhados. Isso implica que essas tarefas podem enfrentar tempos de espera mais longos antes de serem processadas.

Quando o usuário possui uma licença básica do Studio Extensões, as execuções são indicadas por um ícone de raio na cor amarela. Ao passar o mouse sobre o ícone, uma mensagem informa que se trata de uma licença básica.

Controle de Quotas é um mecanismo de controle de uso de recursos, baseado em quotas atribuídas a usuários e entidades. Cada usuário e entidade tem uma quantidade predefinida de execuções que podem solicitar. Para uma operação ser efetuada, é necessário que tanto o usuário quanto a entidade possuam quotas disponíveis. Caso haja disponibilidade, a operação é realizada; caso contrário, ela aguarda até que uma execução já solicitada seja concluída. Esse mecanismo é essencial para evitar que um usuário ou entidade prejudique o processamento de outros.

Em termos práticos, suponhamos que um usuário tenha uma configuração para executar até 10 scripts, enquanto uma entidade pode realizar até 20. Se o usuário inicia a execução de 10 scripts em qualquer entidade, ao tentar solicitar ou executar o décimo primeiro, ele será impedido e entrará em espera até que uma das outras dez execuções seja concluída. A mesma regra é aplicada à entidade, considerando o contexto específico da mesma.