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.

Fluxos de autenticação​

  • Fluxo Authorization Code

studio

  • Fluxo Implicit

studio

  • Fluxo Client Credential

studio

  • Exemplos

studio

studio

Host Produção: https:/plataforma-oauth.betha.cloud/auth

Host Teste: https:/plataforma-oauth.test.betha.cloud/auth

  • 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 Produção: https://plataforma-autorizacoes.betha.cloud/

Host Teste: https://plataforma-autorizacoes.test.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 Produção: https://plataforma-licencas.betha.cloud/

Host Teste: https://plataforma-licencas.test.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 Produção: 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 Produção: https://plataforma-usuarios.betha.cloud/ Host Teste: https://plataforma-usuarios.test.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 Produção: https://plataforma-notificacoes.betha.cloud/notifications

Host Teste: https://plataforma-notificacoes.test.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
}'