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. \
Sempre que for ativado novas API´s na credencial, o token de acesso necessita ser renovado para consumir os dados dos novos endpoints.
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.
O token anterior continuará válido e funcionando normalmente, porém respeitando as configurações anteriores.
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:
Credencial liberada (item 4)
API ativada na credencial (item 5)
Endpoint: Os endpoints disponíveis da API se encontram na seção “Documentação”
User-Access: Chave da credencial que identifica o Sistema e a Entidade dos dados (tenancy)
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'