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 informando se o mesmo terá ou não privilégios de administrador, permissões, se o usuário é técnico e também a data de expiração do acesso. 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,
  "permissions": {PERMISSIOES},
  "technical": false,
  "expiresIn": {DATA_EXPIRACAO_ACESSO}
  }'

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}'

Filtro por subcontexto​

Este filtro permite que desenvolvedores de Scripts e Relatórios criem buscas de acessos de usuários de forma muito mais granular, filtrando por unidades organizacionais específicas de cada sistema (ex: unidades de saúde, estabelecimentos contábeis, etc.). Como a alteração foi feita na fonte de dados, o novo filtro está disponível e funciona da mesma forma tanto no editor de Scripts quanto no de Relatórios.

Foi adicionado o campo de filtro Subcontexto diretamente na fonte de dados Autorizações. A principal característica deste filtro é sua natureza genérica. Ele se adapta automaticamente à terminologia de subcontexto utilizada pelo sistema em questão.

  • No sistema Saúde: o filtro permitirá buscar por Unidade de Saúde.
  • No sistema Contábil: o filtro permitirá buscar por Estabelecimento Contábil.
  • Em outros sistemas: o filtro se adapta à entidade correspondente (filial, departamento, etc.).

Esta implementação centralizada garante que qualquer ambiente que consome esta fonte de dados (Scripts, Relatórios, etc.) receba automaticamente a nova capacidade de filtragem.

julho

Como configurar

  1. Ao criar ou editar um Script ou Relatório, adicione a fonte de dados de busca de acessos (Autorizações).
  2. Na área de configuração dos parâmetros da fonte de dados, o novo campo Subcontexto estará disponível.
  3. Informe neste campo o identificador (código ou nome) da unidade, estabelecimento ou subcontexto desejado para refinar a busca.
  4. Execute o script/relatório. O resultado conterá apenas os acessos de usuários que pertencem ao subcontexto especificado.

Exemplos de uso do filtro

  • Filtrar por uma única unidade: Para buscar acessos relacionados especificamente à unidade de saúde com o ID 3327, o valor a ser preenchido no campo Subcontexto é: subcontext = "unidade:3327"

  • Filtrar por um único estabelecimento: Para buscar acessos relacionados ao estabelecimento contábil com o ID 5343, utilize: subcontext = "estabelecimento:5343"

  • Combinando filtros: É possível combinar múltiplos subcontextos para refinar ainda mais a busca. Para encontrar acessos que pertençam simultaneamente à unidade 3327 e ao estabelecimento 5343, utilize o operador and para unir as condições: subcontext = "unidade:3327" and subcontext = "estabelecimento:5343"

:::Info NOTA A chave do filtro (unidade, estabelecimento, etc.) deve corresponder à nomenclatura do subcontexto no sistema alvo da consulta. :::

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 utilizar um token válido, observando os escopos exigidos por cada endpoint.

Nesta seção foram mantidos apenas endpoints que, no código da API de Licenças, não dependem exclusivamente do escopo interno suite.services.

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/

Escopos aceitos na API Licenças: licenses.suite ou suite.services.

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

Escopos aceitos na API Licenças: licenses.suite ou suite.services.

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

Escopos aceitos na API Licenças: licenses.suite ou suite.services.

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: licenses/v0.1/api/entidades/by-id

Escopos aceitos na API Licenças: licenses.suite ou suite.services.

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

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/v1/licensing/validate

Escopos aceitos na API Licenças: licencas.suite.betha.cloud/auth/dados/licencas.leitura ou suite.services.

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

Para consumo externo via gateway, utilize o escopo licencas.suite.betha.cloud/auth/dados/licencas.leitura.

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
}'