Features

No ecossistema de gerenciamento de permissões e autenticação, o conceito de features desempenha um papel fundamental ao simplificar e estruturar a atribuição de permissões para diferentes funcionalidades dentro de um sistema.

O que são features

Uma feature pode ser compreendida como um pacote que contém todos os scopes requeridos para utilizar uma funcionalidade específica.

Imagine uma situação em que diferentes partes do seu aplicativo ou sistema requerem acesso a várias permissões para funcionar corretamente. Em vez de lidar com cada permissão individualmente, as features fornecem uma maneira conveniente de agrupar as permissões relacionadas, tornando o processo de atribuição de permissões mais coeso e compreensível.

Exemplo prático: Feature Bankslip Generate

Consideremos o exemplo hipotético de um sistema de pagamentos que oferece a funcionalidade de geração de boletos.

Essa funcionalidade requer duas permissões específicas: a capacidade de criar novos boletos e a capacidade de ler informações sobre os boletos existentes. Nesse contexto, a feature será usada para organizar e agrupar essas duas permissões relacionadas sob o nome bankslip_generate.

Dentro da feature bankslip_generate, agrupamos os escopos necessários para executar a funcionalidade de geração de boletos. Desse modo, os parceiros ou usuários que assinam a feature bankslip_generate recebem automaticamente as permissões relevantes para criar e ler boletos.

Esse grupamento simplifica o processo de autenticação e autorização, ao mesmo tempo em que melhora a compreensão geral das permissões disponíveis para essa funcionalidade específica.

📘

Nota

Lembre-se de que as features organizam e simplificam a gestão de permissões, mas as permissões reais ainda são concedidas com base nos escopos individuais. As features não substituem os escopos, mas os complementam para tornar a administração de permissões mais eficiente.

Gerenciamento de features

É importante notar que, em determinados momentos, pode ser necessário desabilitar temporariamente uma feature, por exemplo, devido a uma janela de manutenção ou a uma indisponibilidade planejada do serviço.

Quando uma feature é desabilitada, isso não implica automaticamente no bloqueio direto de funcionalidades, mas sim nos endpoints associados a ela. Ou seja, ao chamar o endpoint relacionado à feature desabilitada será retornado um erro informando a indisponibilidade.

📘

Nota

Em caso de indisponibilidade de uma feature , será retornado o erro: 503 - SERVICE_UNAVAILABLE - This service '{service}' is currently unavailable, please try again later.

Ao desabilitar uma feature , os parceiros que consomem nossa API têm a opção de adotar medidas apropriadas para controlar o acesso a funcionalidades específicas em seus próprios aplicativos ou sistemas. Um exemplo hipotético disso seria o parceiro desativar ou ocultar o botão de geração de boletos em seu aplicativo em resposta à desabilitação da feature bankslip_generate.

Essa abordagem permite que os parceiros forneçam uma experiência mais controlada e amigável para seus clientes finais, informando-os de maneira clara sobre a indisponibilidade da funcionalidade específica em seus aplicativos, em vez de apenas retornar um erro genérico como “tente novamente mais tarde“.

🚧

Importante

A habilitação e desabilitação de features é comunicada ao parceiro por meio dos eventos de Partner.

Lista de features

📘

Nota

Os asteriscos nos paths simbolizam que todos os endpoints que apresentam essa rota estão incluídos na feature e serão afetados em caso de habilitação e desabilitação. Se o path não apresentar asterisco, significa que somente o endpoint com a aquela rota é afetado.