Pular para o conteúdo principal

Principais API’s de plataforma

Na sessão abaixo, serão documentadas as principais requisições das API’s mais utilizadas disponibilizadas pelo time de plataforma: OAuth, autorizações, licenciamento, login, usuários e notificações.

OAuth​

As API's do oauth oferecem diversos serviços para geração, consulta e configurações de tokens de acesso.

Host OAuth: https:/plataforma-oauth.betha.cloud/auth

Fluxo de Client Credentials​

Fluxo a ser utilizado pela credencial de serviço

image-20241210112031236

  1. Troca Application Credentials pelo token

    curl --location 'https://plataforma-oauth.betha.cloud/auth/oauth2/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data-urlencode 'scopes=escopo1,escopo2' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'client_id=SEU_CLIENT_ID' \
    --data-urlencode 'client_secret=SEU_CLIENT_SECRET'

  2. OAuth valida os Application Credentials

  3. Caso válido, é retornado um access token para as credenciais informadas

    Exemplo de resposta

    {
      "expires": 0,
      "scope": "sistema_interno",
      "user": "ba1ae9e0-1da8-496d-8455-7ab17806cdc8",
      "expired": false,
      "access_token": "86635cc9-be50-4076-afd9-57e23809e689",
      "token_type": "bearer",
      "expires_in": 0
    }

  4. Aplicação utiliza o accessToken

  5. Recebe resposta

Fluxo de Authorization Code​

Fluxo a ser utilizado pela credencial de servidor

image-20241203193326757

  1. Usuário inicia processo de login

  2. Redirect para o OAuth no endpoint /authorize (opcionalmente também é pode ser passado um parâmetro state que caso enviado será repassado quando o usuário for redirecionado, recomendado para previnir ataques de CSRF)

curl --location 'https://plataforma-oauth.betha.cloud/auth/oauth2/authorize?response_type=code&client_id=SEU_CLIENT_ID&redirect_uri=SUA_REDIRECT_URI_CONFIGURADA_NO_STUDIO'

  1. Usuário é redirecionado para o login

  2. Usuário insere credenciais e loga

  3. OAuth redireciona usuário para a aplicação com o authorization code (Utilizando o redirect_uri)

  4. Client-side APP inicia troca client_credentials (client_id e client_secret) e o authorization code pelo token no endpoint /oauth2/token

    curl --location 'https://plataforma-oauth.betha.cloud/auth/oauth2/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=authorization_code' \
    --data-urlencode 'client_id=SEU_CLIENT_ID' \
    --data-urlencode 'client_secret=SEU_CLIENT_SECRET' \
    --data-urlencode 'code=SEU_AUTHORIZATION_CODE' \
    --data-urlencode 'redirect_uri=SEU_REDIRECT_URI'

  5. OAuth verifica o authorization code e as credenciais.

  6. OAuth responde com o AccessToken (E refresh token caso habilitado)

  7. Aplicação utiliza o accessToken

  8. Recebe resposta

Fluxo Implicit​

Fluxo originalmente utilizado pela credencial de browser e anônima, atualmente recomendado o fluxo de Authorization Code com PKCE.

No caso da credencial anônima não passa pela etapa de autenticação, dado a não existir um usuário nesse caso.

image-20241203171218432

  1. O usuário inicia processo de login

  2. /authorize é chamado conforme o exemplo abaixo (opcionalmente também é pode ser passado um parâmetro state que caso enviado será repassado quando o usuário for redirecionado, recomendado para previnir ataques de CSRF)

     curl --request GET \
       --url "https://plataforma-oauth.betha.cloud/auth/oauth2/authorize?client_id=SEU_CLIENT_ID&response_type=token&redirect_uri=SEU_REDIRECT_URI&scopes=escopo1,escopo2"

  3. Usuário é redirecionado para a página de login

  4. O usuário se autentica

  5. A API OAuth redireciona o usuário para o APP com o access_token

Fluxo de Authorization Code com PKCE (Recomendado)​

Utilize para aplicações client-side que não podem salvar um client secret de forma segura, recomendado principalmente para a credencial de browser e anônima.

No caso da credencial anônima não passa pela etapa de autenticação, dado a não existir um usuário nesse caso.

image-20241203193223074

  1. O usuário inicia processo de login

  2. Deve criar um: code_verifier (exemplo um UUID v4 sustenido para 32 caracteres e encodado em base64) e utiliza-lo para gerar um code challenge (Um hash do code_verifier utilizando SHA256 e encodando novamente em base64)

    Exemplos de geração de code verifier​

    java

    import java.util.Base64;
    import java.util.UUID;

    String codeVerifier = Base64.getUrlEncoder().withoutPadding().encodeToString(UUID.randomUUID().toString().substring(0, 32).getBytes());

    javascript no nodejs

    Buffer.from(crypto.randomUUID().substring(0, 32)).toString("base64url")
    Exemplos de geração de code challenge​

    java

     import java.nio.charset.StandardCharsets;
     import java.security.MessageDigest;
     import java.security.NoSuchAlgorithmException;
     import java.util.Base64;

     try {
         String codeVerifier = "ZGRlYmExYzMtZGU2YS00ZjBhLTgyNzgtZTFkN2NlOGM";

         byte[] hash = MessageDigest.getInstance("SHA-256")
                 .digest(codeVerifier.getBytes(StandardCharsets.UTF_8));

         String codeChallenge = Base64.getUrlEncoder().encodeToString(hash);

         System.out.println(codeChallenge);
     } catch (NoSuchAlgorithmException e) {
         throw new RuntimeException(e);
     }

    javascript no nodejs

    import crypto from 'crypto';

    const codeVerifier = 'ZGRlYmExYzMtZGU2YS00ZjBhLTgyNzgtZTFkN2NlOGM';

    const hash = crypto.createHash('sha256')
        .update(codeVerifier)
        .digest();

    const codeChallenge = Buffer.from(hash)
        .toString('base64url');

    console.log(codeChallenge);

  3. Client-side App chama OAuth passando o code_challenge (opcionalmente também é pode ser passado um parâmetro state que caso enviado será repassado quando o usuário for redirecionado, recomendado para previnir ataques de CSRF)

    curl --location 'https://plataforma-oauth.betha.cloud/auth/oauth2/authorize?audience=SEU_AUDIENCE&scope=ESCOPO_DO_TOKEN&response_type=code&client_id=SEU_CLIENT_ID&redirect_id=SEU_REDIRECT_URI&code_challenge_method=S256&code_challenge=SEU_CODE_CHALLENGE'

  4. OAuth redireciona para o login

  5. Usuário insere as credenciais e loga

  6. OAuth redireciona para a aplicação (redirect_uri) propagando o authorization code

  7. Client-side App chama OAuth passando o code_verifier para o /oauth2/token

    curl --location --globoff 'https://plataforma-oauth.betha.cloud/auth/oauth2/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=authorization_code' \
    --data-urlencode 'client_id=SEU_CLIENT_ID' \
    --data-urlencode 'code_verifier=SEU_CODE_VERIFIER' \
    --data-urlencode 'code=SEU_AUTHORIZATION_CODE' \
    --data-urlencode 'redirect_uri=SEU_REDIRECT_URI'

  8. OAuth verifica o code_verifier e code_challenge

  9. OAuth responde com o AccessToken (E refresh token caso habilitado)

  10. Aplicação utiliza o accessToken

  11. Recebe resposta

Fluxo de Resource Owner Password (Reservado para uso interno da Betha Sistemas)​

Fluxo utilizado pela credencial de Usuário e Senha

image-20241210142734806

  1. O usuário inicia o processo de login

  2. Usuário e senha enviados para o /oauth2/token

curl --location 'https://plataforma-oauth.betha.cloud/auth/oauth2/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=SEU_USERNAME' \
--data-urlencode 'password=SEU_PASSWORD' \
--data-urlencode 'scope=escopo1,escopo2' \
--data-urlencode 'client_id=SEU_CLIENT_ID'

  1. OAuth valida usuário e senha e retorna Access Token

  2. Aplicação utiliza o accessToken

  3. Recebe resposta

Token Info​

O endpoint de Tokeninfo retorna as informações relacionadas a criação e configuração de um token, tais como escopos, cliente, usuário e validade. O token desejado deve ser informado através do parâmetro "access_token".

Endpoint: auth2/tokeninfo

curl --request GET \
  --url 'https://oauth.cloud.betha.com.br/auth/oauth2/tokeninfo?access_token={TOKEN}' \

Autorizações​

As API's do autorizações fornecem meios para conceder e remover acessos e permissões para usuários em um contexto específico, e consultar os acessos vinculados a usuários dos sistemas.

Host Autorizações: https://plataforma-autorizacoes.betha.cloud/

Verifica acessos do usuário atual​

Informa todos os acessos vinculados ao usuário atual, independente do contexto.

Endpoint: user-accounts/v0.1/api/suite/users/@me/access Escopo: user-accounts.suite

curl --request GET \
  --url https://plataforma-autorizacoes.betha.cloud/user-accounts/v0.1/api/suite/users/@me/access \
  --header 'authorization: bearer 2bfee386-23b5-4a92-b624-6e2bd9e75ef1'

Lista acessos de um contexto​

Realiza a listagem de todos os acessos cadastrados para o contexto atual, informando últimas atividades, usuário que concedeu o acesso, entre outras informações. Apenas usuários administradores ou técnicos possuem permissão para acessar o recurso.

Endpoint: user-accounts/v0.1/api/management/access Escopo: user-accounts.suite

curl --request GET \
  --url 'https://plataforma-autorizacoes.betha.cloud/user-accounts/v0.1/api/management/access?limit=20&offset=0' \
  --header 'Authorization: Bearer {TOKEN}' \
  --header 'User-Access: {USER_ACCESS}'

Conceder acesso para um usuário​

A requisição abaixo faz a liberação de acesso para um usuário em um determinado sistema, passando no corpo da requisição do contexto do acesso, e informando se o mesmo terá ou não privilégios de administrador. Apenas usuários administradores ou técnicos possuem permissão para acessar o recurso.

Endpoint: user-accounts/v0.1/api/management/access Escopo: user-accounts.suite

curl --request POST \
  --url https://plataforma-autorizacoes.betha.cloud/user-accounts/v0.1/api/management/access \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {TOKEN}' \
  --header 'user-access: {USER_ACCESS}' \
  --data '{
    "user": {ID_USUARIO}
    "admin": true,
    "context": {
        "entity": {ID_ENTIDADE},
        "database": {ID_DATABASE}
    }
}'

Remover acesso para um usuário​

Essa requisição faz a exclusão de um acesso existente no contexto. Como parâmetro, é necessário informar o id do acesso, que pode ser obtido tanto no ato da criação, como consultado através da api de listagem descrita no tópico. Apenas usuários administradores ou técnicos possuem permissão para acessar o recurso.

Endpoint: user-accounts/v0.1/api/management/access/{ID_ACESSO} Escopo: user-accounts.suite

curl --request DELETE \
--url https://plataforma-autorizacoes.betha.cloud/user-accounts/v0.1/api/management/access/{ID_ACESSO} \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {TOKEN}' \
  --header 'user-access: {USER_ACCESS}'

Lista solicitações de acesso​

Essa requisição busca as solicitações de acesso existentes no contexto informado. Apenas usuários administradores ou técnicos possuem permissão para acessar o recurso.

Endpoint: user-accounts/v0.1/api/management/request Escopo: user-accounts.suite

curl --request GET \
  --url 'https://plataforma-autorizacoes.betha.cloud/user-accounts/v0.1/api/management/request?limit=20&offset=0&order=name%20asc' \
  --header 'authorization: Bearer {TOKEN}' \
  --header 'user-access: {USER_ACCESS}'

Aprova solicitação de acesso​

Essa requisição faz a aprovação de uma solicitação existente no contexto. Como parâmetro, é necessário informar o id da solicitação, que pode ser obtido através da api de listagem. Apenas usuários administradores possuem permissão para acessar o recurso.

Endpoint: user-accounts/v0.1/api/management/request Escopo: user-accounts.suite

curl --request POST \
  --url 'https://plataforma-autorizacoes.betha.cloud/user-accounts/v0.1/api/management/request/{id}/allow' \
  --header 'authorization: Bearer {TOKEN}' \
  --header 'user-access: {USER_ACCESS}'

Rejeita solicitação de acesso​

Essa requisição rejeita a solicitação existente no contexto. Como parâmetro, é necessário informar o id da solicitação, que pode ser obtido através da api de listagem. Apenas usuários administradores possuem permissão para acessar o recurso.

Endpoint: user-accounts/v0.1/api/management/request Escopo: user-accounts.suite

curl --request POST \
  --url 'https://plataforma-autorizacoes.betha.cloud/user-accounts/v0.1/api/management/request/{id}/deny' \
  --header 'authorization: Bearer {TOKEN}' \
  --header 'user-access: {USER_ACCESS}'

Licenciamento (dados de uma entidade)​

Os serviços de licenciamento fornecem meios de interagir com o cadastro de licenças dos clientes finais. Através deles conseguimos realizar a consulta de dados de entidades, databases, revendas e licenças. Para fazer uso das API's de licenciamento, é necessário a utilização de um token que possua o escopo 'licenses.suite'.

Host Licenças: https://plataforma-licencas.betha.cloud/

Consulta dados da entidade atual​

Esse endpoint é a principal fonte de consulta para retornar os dados relacionados com a entidade vinculada ao token/user-access utilizados na requisição. Ele retorna todos os dados disponíveis para a entidade em questão.

Endpoint: licenses/v0.1/api/entidades/atual/

curl --request GET \
  --url 'https://plataforma-licencas.betha.cloud/licenses/v0.1/api/entidades/atual/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {TOKEN}' \
  --header 'User-Access: {USER_ACCESS}'

Consulta dados das entidades do escopo​

Endpoint: licenses/v0.1/api/entidades/atual/entidades

curl --request GET \
 --url 'https://plataforma-licencas.betha.cloud/licenses/v0.1/api/entidades/atual/entidades?limit=20&offset=0&sort=nome%20asc&=' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {TOKEN}' \ 
  --header 'User-Access: {USER_ACCESS}'

Para essa requisição, é possível adicionar o parâmetro opcional 'filter', que realiza uma busca aplicando um filtro nos campos disponíveis no retorno da requisição.

Verifica o database vinculado a uma determinada entidade​

Essa consulta retorna qual o database vinculado à entidade na liberação da licença para o sistema do contexto.

Endpoint: licenses/v0.1/api/databases

curl --request GET \
  --url 'https://plataforma-licencas.betha.cloud/licenses/v0.1/api/databases?entity={ID_ENTIDADE}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {TOKEN}' \ 
  --header 'User-Access: {USER_ACCESS}'

Verifica o nome de uma entidade a partir do ID​

Endpoint: api/entities

curl --request GET \
 --url 'https://plataforma-licencas.betha.cloud/licenses/v0.1/api/entidades/atual/entidades?limit=20&offset=0&sort=nome%20asc&=' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {TOKEN}' \ 
  --header 'User-Access: {USER_ACCESS}'

Fonte de dados para consulta de dados de entidades​

Endpoint: licenses/dados/v0.1/api/entidades

curl --request GET \
  --url 'https://plataforma-licencas-dados.betha.cloud/licenses/dados/v0.1/api/entidades?fields=esfera' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {TOKEN}' \ 
  --header 'User-Access: {USER_ACCESS}'

Consulta a última licença a partir da entidade, database e sistema​

Endpoint: api/licensing

curl --request GET \
 --url 'https://plataforma-licencas.betha.cloud/licenses/v0.1/api/licensing?database={ID_DATABASE}&entity={ID_ENTIDADE}&system={ID_SISTEMA}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {TOKEN}'

Verifica se a licença está ativa a partir da entidade, database e sistema​

Essa consulta retorna o código de status 200 caso a licença esteja ativa para o contexto informado. Caso contrário, o código de status 403 é retornado.

Endpoint: api/licensing/validate

curl --request GET \
 --url 'https://plataforma-licencas.betha.cloud/licenses/v0.1/api/licensing/validate?database={ID_DATABASE}&entity={ID_ENTIDADE}&system={ID_SISTEMA} \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {TOKEN}'
IMPORTANTE!

Para a consulta na API de dados, é necessário que o token utilizado possua além do escopo 'licenses.suite', o escopo 'suite.services'.

Login​

A API de login disponibiliza recursos para a realização se sessões de login/logout a partir de credenciais de usuário previamente cadastradas aqui.

Host Login: https://login.betha.cloud/

Logout​

Esse endpoint faz o encerramento de uma sessão previamente iniciada para um determinado usuário, recebendo uma URI de callback informando para qual página o usuário deverá ser redirecionado.

Endpoint: /servicelogin/logout

curl --request GET \
--url 'https://login.test.betha.cloud/servicelogin/logout?continue=https://plataforma-oauth.test.betha.cloud/auth/oauth2/authorize?client_id=app_default%26response_type=token%26redirect_uri=https://suite.test.bethacloud.com.br/auth/callback.html%26scope=sistema_interno,notifications.suite,user-accounts.suite%26bth_ignore_origin=true'

Usuários​

A API de usuário disponibiliza recursos para realizar consultas referente a usuários cadastrados na central de usuários Betha, como informações do cadastro, imagem de perfil, entre outras.

Host Usuários: https://plataforma-usuarios.betha.cloud/

Consultar usuários​

Esse recurso retorna a lista de usuários cadastrados no sistema, com a possibilidade de inserir o parâmetro opcional 'filter', que permite adicionar critérios no retorno dos dados desejados.

Endpoint: usuarios/v0.1/api/usuarios

curl --request GET \
--url 'https://plataforma-usuarios.betha.cloud/usuarios/v0.1/api/usuarios/?filter=id%3D'\''kaio.stricker'\''' \
--header 'authorization: Bearer {TOKEN}' \

Consultar usuários por id​

De forma semelhante a requisição anterior, esse endpoint permite a consulta dos dados de um usuário específico, especificando qual o id do usuário diretamente no path da requisição

Endpoint: usuarios/v0.1/api/usuarios/{ID_USUARIO}

curl --request GET \
--url https://plataforma-usuarios.betha.cloud/usuarios/v0.1/api/usuarios/{ID_USUARIO} \
--header 'authorization: Bearer {TOKEN}'

Consultar imagem vinculada ao usuário​

Esse recurso retorna um content type em formato de imagem, contendo qual a foto cadastrada para o usuário na central de usuários Betha.

Endpoint: usuarios/v0.1/api/usuarios/{ID_USUARIO}/photo

curl --request GET \
--url https://plataforma-usuarios.betha.cloud/usuarios/v0.1/api/usuarios/{ID_USUARIO}/photo \
--header 'authorization: Bearer {TOKEN}'

Notificações​

A API de notificações permite realizar o envio e a leitura de notificações para usuários do logados no sistema, e que podem ser consultadas através da sessão de notificações no menu principal dos sistemas Betha Cloud.

Host Notificações: https://plataforma-notificacoes.betha.cloud/notifications

Consultar notificações​

Esse endpoint retornará as notificações vinculadas com o contexto do token, apresentando informações sobre o tipo da mensagem, texto, horário, entre outras.

Endpoint: api/messages

curl --request GET \
  --url https://plataforma-notificacoes.betha.cloud/notifications/api/messages \
  --header 'authorization: bearer {TOKEN}' \

Consultar notificações não lidas​

Semelhante a requisição do item "Consultar notificações", porém irá retornar apenas a listagem de mensagens ainda não lidas pelo usuário.

Endpoint: api/messages/unreads

curl --request GET \
  --url https://plataforma-notificacoes.betha.cloud/notifications/api/messages/unreads \
  --header 'authorization: bearer {TOKEN}'

Consultar notificações lidas​

Semelhante a requisição do item "Consultar notificações", porém irá retornar apenas a listagem de mensagens ainda já lidas pelo usuário.

Endpoint: api/messages/reads

curl --request GET \
  --url https://plataforma-notificacoes.betha.cloud/notifications/api/messages/reads \
  --header 'authorization: bearer {TOKEN}'

Gerar nova mensagem​

Essa requisição consiste na criação/envio de uma nova mensagem, podendo ou não ser destinada para um usuário específico.

Endpoint: api/messages

curl --request POST \
  --url https://plataforma-notificacoes.betha.cloud/notifications/api/messages \
  --header 'Authorization: bearer {TOKEN}' \
  --header 'Content-Type: application/json' \
  --header 'User-Access: {USER_ACCESS}' \
  --data '{
  "systemId":{ID_SISTEMA},
  "text": "Sua mensagem",
  "link": null,
  "source": "system@script",
  "user": "{ID_USUARIO}",
  "priority": 3,
  "read": false,
  "process": false,
  "progress": false,
  "cancellationLink": null,
  "trackingLink": null,
  "status": "CLOSED",
  "percentage": null,
  "destination": "USER",
  "aggregationMessageId": null,
  "context": null,
  "type": "SCRIPT_EXECUTADO",
  "icon": null,
  "closed": true,
  "contextDestined": false,
  "userDestined": true
}'