API de Page Mapping

Visão Geral

As APIs de Page Mapping permitem registrar e consultar a configuração de permissões do seu sistema. Para utilizar essas APIs, você precisa de um token com os escopos apropriados.

Host Autorizações: https://autorizacoes.suite.betha.cloud/dados/v1

API na Betha Store

A API está disponível publicamente na Betha Store do Studio Aplicações com o nome "Autorizações Dados". Acesse a Store, pesquise por "Autorizações Dados" e ative a API para suas credenciais.

Registrar Page Mapping

Registra ou atualiza o Page Mapping do sistema atual.

Endpoint: PUT /dados/v1/page-mapping

Escopo: autorizacoes.plataforma.betha.cloud/parceiro.escrita

curl --location --request PUT 'https://autorizacoes.suite.betha.cloud/dados/v1/page-mapping'\
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN}' \
--data '[
  {
    "contexts": ["database", "entity"],
    "constraints": [
      {
        "id": "CadastroPessoasPage",
        "description": "Cadastro de Pessoas",
        "resources": [
          {
            "accessControll": null,
            "urlPattern": "/api/pessoas/.*",
            "methods": ["GET"]
          },
          {
            "accessControll": "create",
            "urlPattern": "/api/pessoas",
            "methods": ["POST"]
          }
        ],
        "accessControll": [
          { "id": "create", "description": "Criar" }
        ]
      }
    ],
    "resources": [],
    "groups": [
      {
        "id": "cadastros",
        "description": "Cadastros",
        "constraints": ["CadastroPessoasPage"]
      }
    ]
  }
]'

Resposta de sucesso (200 OK):

{
  "message": "Page mapping atualizado com sucesso"
}

Registrar Page Mapping com Versão

Permite registrar o Page Mapping com uma versão específica para controle de atualizações.

Endpoint: PUT /page-mapping/{fileVersion}

Escopo: autorizacoes.plataforma.betha.cloud/parceiro.escrita

curl --location --request PUT 'https://autorizacoes.suite.betha.cloud/dados/v1/page-mapping/latest' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN}' \
--data '[...]'

Consultar Page Mapping

Retorna o Page Mapping atual do sistema.

Endpoint: GET /dados/v1/page-mapping

Escopo: autorizacoes.plataforma.betha.cloud/parceiro.leitura

curl --location 'https://autorizacoes.suite.betha.cloud/dados/v1/page-mapping' \
--header 'Authorization: Bearer {TOKEN}'

Resposta:

[
  {
    "contexts": ["database", "entity"],
    "constraints": [...],
    "resources": [...],
    "groups": [...],
  }
]

Consultar Page Mapping por Versão

Endpoint: GET /dados/v1/page-mapping/{fileVersion}

curl --location 'https://autorizacoes.suite.betha.cloud/dados/v1/page-mapping/latest' \
--header 'Authorization: Bearer {TOKEN}'

Fluxo de Validação de Permissões

Quando um usuário tenta acessar um recurso protegido, o sistema executa o seguinte fluxo:

┌─────────────────────────────────────────────────────────────────┐
│                    REQUISIÇÃO DO USUÁRIO                        │
│                   GET /api/pessoas/123                          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              1. VALIDAÇÃO DO ACCESS TOKEN                       │
│    - Token válido e não expirado?                               │
│    - Token pertence ao sistema correto?                         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              2. VALIDAÇÃO DA LICENÇA                            │
│    - Usuário possui licença ativa no contexto?                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              3. VALIDAÇÃO DE RESTRIÇÕES                         │
│    - Restrição de IP/período/MFA permite o acesso?              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              4. CONSULTA AO PAGE MAPPING                        │
│    - URL + método HTTP requer qual permissão?                   │
│    - Qual accessControll é necessário?                          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              5. VALIDAÇÃO DA PERMISSÃO                          │
│    - Usuário possui a constraint necessária?                    │
│    - Usuário possui o accessControll requerido?                 │
└─────────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    │                   │
                    ▼                   ▼
            ┌───────────┐       ┌───────────────┐
            │  PERMITIR │       │     NEGAR     │
            │   ACESSO  │       │    ACESSO     │
            │  HTTP 200 │       │   HTTP 403    │
            └───────────┘       └───────────────┘

Endpoint de Validação

Você pode consultar se um usuário tem permissão para acessar um recurso específico:

Endpoint: GET /resources/{url}/methods/{method}/constraints

curl --location 'https://autorizacoes.suite.betha.cloud/dados/v1/resources/%2Fapi%2Fpessoas%2F123/methods/GET/constraints' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'User-Access: {USER_ACCESS}'

URL Encoding

A URL do recurso deve ser URL-encoded. Por exemplo: /api/pessoas/123 deve ser passado como %2Fapi%2Fpessoas%2F123.

Automação do Registro

Para garantir que o Page Mapping esteja sempre atualizado, recomendamos:

1. CI/CD: registre o Page Mapping automaticamente no deploy
2. Versionamento: use o parâmetro fileVersion para controlar versões
3. Ambiente de teste: valide alterações em homologação antes de produção

Exemplo de script para CI/CD:

#!/bin/bash
# deploy-page-mapping.sh

TOKEN=$(curl -s --location 'https://plataforma-oauth.betha.cloud/auth/oauth2/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_id=${CLIENT_ID}" \
  --data-urlencode "client_secret=${CLIENT_SECRET}" \
  | jq -r '.access_token')

curl --location --request PUT "https://autorizacoes.suite.betha.cloud/dados/v1/page-mapping/${VERSION}" \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${TOKEN}" \
  --data @page-mapping.json

Troubleshooting

Erro: "Acesso negado" mesmo com permissão

Possíveis causas:

1. AccessControll incorreto na configuração
2. Contexto errado (database/entity)
3. URL não coberta pelo Page Mapping
4. Cache desatualizado

Solução: Use o endpoint de validação para debugar.

Erro: "Constraint não encontrada"

Possíveis causas:

1. Page Mapping não registrado
2. ID da constraint não existe
3. Contexto não incluído na configuração

Solução: Consulte o Page Mapping atual e verifique a estrutura.

Permissões não aparecem no Gerenciador de Acessos

Possíveis causas:

1. Page Mapping não foi registrado
2. Token sem escopo adequado
3. Sistema não configurado corretamente no Studio

Solução: Verifique se o Page Mapping foi registrado com sucesso e se o sistema está configurado no Studio Aplicações.