Índice | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
Consentimento
No compartilhamento de dados cadastrais e transacionais, o "consentimento" denota a autorização concedida por um cliente de uma instituição participante do Open Finance para que outra instituição possa acessar informações sobre os produtos (recursos) detidos pelo cliente. Essa autorização é dada de forma explícita e detalhada.
O cliente, que é o principal interessado no compartilhamento de suas informações, detém o poder de determinar quais produtos a instituição terá acesso. Além disso, dependendo do tipo de produto, ele pode especificar a origem precisa dos dados. Por exemplo, no caso de produtos do tipo "conta", o cliente tem a capacidade de escolher quais contas específicas terão seus dados compartilhados. Para outras categorias de produtos, como operações de crédito, o cliente pode indicar as modalidades de compartilhamento. Isso inclui autorizar a consulta de dados relativos a produtos que estejam atualmente contratados, bem como produtos que possam ser adquiridos no futuro, durante o período de validade do consentimento.
...
A receptora de dados deve enviar as permissões desejadas em grupo mínimo de permissões definidos para cada tipo de produto;
A receptora de dados pode solicitar mais de um grupo de permissões ao mesmo tempo, respeitando a intenção do cliente durante a criação do consentimento;
Para produtos com seleção por agrupamento de recursos ou agrupamento de produtos, a detentora deve manter as permissões do agrupamento solicitado,
mesmo quando não os comercialize;Para produtos que exigem a seleção individual de recurso na aprovação do consentimento, caso a detentora não ofereça o produto, deve remover as permissões do agrupamento solicitado, criando o consentimento com as demais permissões solicitadas;
Se após a remoção de um agrupamento de produtos não restarem permissões funcionais, a transmissora deve rejeitar o pedido de criação do consentimento dando um retorno HTTP Status Code 422, com a mensagem "NOSEM_FUNCTIONALPERMISSOES_PERMISSIONSFUNCIONAIS_LEFTRESTANTES";
Nas situações abaixo, a transmissora deve rejeitar o pedido de criação de consentimento, dando retorno HTTP Status Code 422 com as mensagens especificadas abaixo:
Caso o cliente PF escolha uma marca PJ na
a. Caso, no pedido da criação do consentimento
...
, a transmissora
...
valide a ausência de parâmetros PJ e presença de permissions CUSTOMERS BUSINESS deve retornar HTTP Status Code 422 com a mensagem
...
“INFORMACOES_PJ_NAO_INFORMADAS”;
b. Caso, no pedido da criação do consentimento, a transmissora valide a presença de parâmetros PJ e presença de permissions CUSTOMERS PERSONAL deve retornar HTTP Status Code 422 com a mensagem “PERMISSOES_PJ_INCORRETAS”;
c. Caso recebam uma solicitação de consentimento com permissões de dados cadastrais PF e PJ em conjunto, retornar HTTP Status Code 422 com a mensagem
...
“PERMISSAO_
...
PF_
...
PJ_
...
EM_
...
CONJUNTO”;
d. Caso a Instituição Receptora envie permissões divergentes ao agrupamento especificado na tabela abaixo, retornar HTTP Status Code 422 com a mensagem
...
“COMBINACAO_
...
PERMISSOES_
...
INCORRETA”.
A tabela abaixo indica, para cada produto, os agrupamentos de permissões válidos e como é realizado a seleção de recursos, por identificador ou por modalidade. Produtos cuja seleção de recurso seja por identificador devem ter o agrupamento de permissões removidos quando a instituição transmissora não oferecer o produto. Já produtos cuja seleção de recurso seja por agrupamento de recurso ou agrupamento de produtos deve ter as permissões mantidas mesmo quando a instituição transmissora não comercializar o produto solicitado.
...
CATEGORIA DE DADOS
...
AGRUPAMENTO
...
PERMISSIONS
...
SELEÇÃO DE RECURSO
...
Cadastro
...
Dados Cadastrais PF
...
CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ
...
Por recurso
...
RESOURCES_READ
...
Cadastro
...
Informações complementares PF
...
CUSTOMERS_PERSONAL_ADITTIONALINFO_READ
...
Por recurso
...
RESOURCES_READ
...
Cadastro
...
Dados Cadastrais PJ
...
e. Caso a Instituição Receptora envie data de expiração maior que um ano ou uma data referente ao passado, deve-se retornar HTTP Status Code 422.
Caso seja identificado um cliente PJ na jornada de criação de consentimento, deve-se exibir apenas marcas que suportem públicos PJ ou ambos (PF e PJ) para escolha. As marcas que contemplam público PJ podem ser selecionadas no diretório nos casos em que a flag de seleção de público está preenchida com a opção “Suporta Contas PJ”;
Caso seja identificado um cliente PF na jornada de criação de consentimento, deve-se exibir apenas marcas que suportem públicos PF ou ambos (PF e PJ) para escolha. As marcas que contemplam público PF podem ser selecionadas no diretório nos casos em que a flag de seleção de público está preenchida com a opção “Suporta Contas PF”.
A tabela abaixo indica, para cada produto, os agrupamentos de permissões válidos e como é realizado a seleção de recursos, por identificador ou por modalidade. Produtos cuja seleção de recurso seja por identificador devem ter o agrupamento de permissões removidos quando a instituição transmissora não oferecer o produto. Já produtos cuja seleção de recurso seja por agrupamento de recurso ou agrupamento de produtos deve ter as permissões mantidas mesmo quando a instituição transmissora não comercializar o produto solicitado.
CATEGORIA DE DADOS | AGRUPAMENTO | PERMISSIONS | SELEÇÃO DE RECURSO |
---|---|---|---|
Cadastro | Dados Cadastrais PF | CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ | Por recurso |
RESOURCES_READ | |||
Cadastro | Informações complementares PF | CUSTOMERS_PERSONAL_ADITTIONALINFO_READ | Por recurso |
RESOURCES_READ | |||
Cadastro | Dados Cadastrais PJ | CUSTOMERS_BUSINESS_IDENTIFICATIONS_READ | Por recurso |
RESOURCES_READ | |||
Cadastro | Informações complementares PJ | CUSTOMERS_BUSINESS_ADITTIONALINFO_READ | Por recurso |
RESOURCES_READ | |||
Contas | Saldos | ACCOUNTS_READ | Por recurso |
ACCOUNTS_BALANCES_READ | |||
RESOURCES_READ | |||
Contas | Limites | ACCOUNTS_READ | Por recurso |
ACCOUNTS_OVERDRAFT_LIMITS_READ | |||
RESOURCES_READ | |||
Contas | Extratos | ACCOUNTS_READ | Por recurso |
ACCOUNTS_TRANSACTIONS_READ | |||
RESOURCES_READ | |||
Cartão de Crédito | Limites | CREDIT_CARDS_ACCOUNTS_READ | Por recurso |
CREDIT_CARDS_ACCOUNTS_LIMITS_READ | |||
RESOURCES_READ | |||
Cartão de Crédito | Transações | CREDIT_CARDS_ACCOUNTS_READ | Por recurso |
CREDIT_CARDS_ACCOUNTS_TRANSACTIONS_READ | |||
RESOURCES_READ | |||
Cartão de Crédito | Faturas | CREDIT_CARDS_ACCOUNTS_READ | Por recurso |
CREDIT_CARDS_ACCOUNTS_BILLS_READ | |||
CREDIT_CARDS_ACCOUNTS_BILLS_TRANSACTIONS_READ | |||
RESOURCES_READ | |||
Operações de Crédito | Dados do Contrato | LOANS_READ | Por agrupamento de produtos |
LOANS_WARRANTIES_READ | |||
LOANS_SCHEDULED_INSTALMENTS_READ | |||
LOANS_PAYMENTS_READ | |||
FINANCINGS_READ | |||
FINANCINGS_WARRANTIES_READ | |||
FINANCINGS_SCHEDULED_INSTALMENTS_READ | |||
FINANCINGS_PAYMENTS_READ | |||
UNARRANGED_ACCOUNTS_OVERDRAFT_READ | |||
UNARRANGED_ACCOUNTS_OVERDRAFT_WARRANTIES_READ | |||
UNARRANGED_ACCOUNTS_OVERDRAFT_SCHEDULED_INSTALMENTS_RE | |||
UNARRANGED_ACCOUNTS_OVERDRAFT_PAYMENTS_READ | |||
INVOICE_FINANCINGS_READ | |||
INVOICE_FINANCINGS_WARRANTIES_READ | |||
INVOICE_FINANCINGS_SCHEDULED_INSTALMENTS_READ | |||
INVOICE_FINANCINGS_PAYMENTS_READ | |||
RESOURCES_READ | |||
Investimento | Dados da Operação | BANK_FIXED_INCOMES_READ | Por agrupamento de produtos |
CREDIT_FIXED_INCOMES_READ | |||
FUNDS_READ | |||
VARIABLE_INCOMES_READ | |||
TREASURE_TITLES_READ | |||
RESOURCES_READ | |||
Câmbio | Listar | EXCHANGES_READ | Por agrupamento de recursos |
RESOURCES_READ | |||
Detalhes da Operação | EXCHANGES_READ | ||
RESOURCES_READ | |||
Eventos | EXCHANGES_READ | ||
RESOURCES_READ |
Cenários de caso de erro
Foram mapeados alguns erros esperados durante o fluxo do usuário no ecossistema. Existem orientações específicas já tratadas no Guia de Experiência do Usuário. Aqui, trataremos a visão mais técnica do que pode ser feito em caso de erro:
...
A transmissora deve validar documento fornecido (`loggedUser`; `businessEntity` quando aplicável) e token de acesso para executar a renovação de consentimento. Caso a transmissora detecte que se trata de acesso inválido por questões de segurança, é esperado status de erro 401 ou 403. Tipicamente, erros de segurança tem precedência, pois são avaliados primeiro, ao invés de erros de negócio. Por exemplo, status de erro 401 ocorrerá, mesmo que exista algum outro erro funcional (status 422) na requisição;
Na tentativa de renovação de consentimentos no status REJECTED a transmissora deve retornar status de erro 422 (`ESTADO_CONSENTIMENTO_INVALIDO`);
Na tentativa de renovação de consentimentos que exijam aprovações por múltiplas alçadas a transmissora deve retornar status de erro 422 (`DEPENDE_MULTIPLA_ALCADA`) ;
A transmissora deve retornar status de erro 422 (`DATA_EXPIRACAO_INVALIDA`) na tentativa de renovação de consentimentos em que o novo expirationDateTime seja:
Menor que a data de requisição (currentDateTime ) do pedido de renovação, ou menor ou igual que a data de expiração atual;
Diferente de prazo indeterminado e maior que 12 meses da data de requisição (currentDateTime);
...
Mudanças para as transmissoras de dados somente para produtos cuja seleção é agrupada por produtos (Operações de Crédito e Investimentos) ou por recursos (Câmbio)
Regra | Como é | Como fica |
---|---|---|
URL de well-know | Deve incluir apenas os escopos dos produtos trabalha | Deve incluir todos os escopos válidos do Open Finance |
Criação do Consentimento | Deve remover as permissões correspondentes aos produtos que não trabalha | Deve manter todas as permissões dos agrupamentos solicitados, mesmo dos produtos que não trabalha |
Criação do access-token | Deve remover os escopos dos produtos que não trabalha | Deve manter os escopos solicitados, mesmo dos produtos que não trabalha |
APIs e endpoints | Deve implementar apenas as APIs e endpoints dos produtos que trabalha¹ | Deve implementar apenas as APIs e endpoints dos produtos que trabalha¹ |
Comunicação | Deixar claro que novos recursos serão compartilhados quando contratados | Deixar claro que novos recursos e produtos poderão serão compartilhados quando contratados |
1 Válido para todos os produtos, e não somente Operações de Crédito, Investimentos e Câmbio.
Mudanças para as receptoras de dados somente para produtos cuja seleção é agrupada por produtos (Operações de Crédito e Investimentos) ou por recursos (Câmbio)
Regra | Como é | Como fica |
---|---|---|
Comunicação | Deixar claro que novos recursos serão compartilhados quando contratados | Deixar claro que novos recursos e produtos poderão serão compartilhados quando contratados |
Consumo de APIs e Endpoints | Pode se basear nas permissões do consentimento para saber quais endpoints consumir | Deve se basear na API Recursos |
Impactos e regras de transição
...
Para adequada convivência entre versões da API Consents de Dados do Cliente é preciso que o prazo de expiração indeterminado seja reconhecido de duas formas:
v2.2.0: preenchimento de dummy (`2300-01-01T00:00:00Z´) no campo expirationDateTime
v3.0.0: campo expirationDateTime não é enviado na requisição
Dessa forma, as instituições precisam tratar ambas as representações na experiência do usuário e exibir prazo indeterminado, de acordo com Guia UX, quando aplicável.
Dados do Cliente é preciso que o prazo de expiração indeterminado seja reconhecido de duas formas:
v2.2.0: preenchimento de dummy (`2300-01-01T00:00:00Z´) no campo expirationDateTime
v3.0.0: campo expirationDateTime não é enviado na requisição
Dessa forma, as instituições precisam tratar ambas as representações na experiência do usuário e exibir prazo indeterminado, de acordo com Guia UX, quando aplicável.
Mapeamento de mensagens retornadas pela API Consentimento
Endpoint | Método | HTTP Status | Cenário | Código de Mensagem |
---|---|---|---|---|
/consents | POST | 201 | Criação do consentimento efetuada com sucesso (payload de retorno conforme a especificação) |
|
422 | Se após a remoção de um agrupamento de produtos não restarem permissões funcionais | SEM_PERMISSOES_FUNCIONAIS_RESTANTES | ||
A transmissora valide a ausência de parâmetros PJ e presença de permissions CUSTOMERS BUSSINESS | INFORMACOES_PJ_NAO_INFORMADAS | |||
A transmissora valide a presença de parâmetros PJ e presença de permissions CUSTOMERS PERSONAL | PERMISSOES_PJ_INCORRETAS | |||
Solicitação de consentimento com permissões de dados cadastrais PF e PJ em conjunto | PERMISSAO_PF_PJ_EM_CONJUNTO | |||
Instituição Receptora envie permissões divergentes ao agrupamento de especificado na tabela | COMBINACAO_PERMISSOES_INCORRETA | |||
DELETE | 422 | Consentimento já se encontra no status REJECTED | CONSENTIMENTO_EM_STATUS_REJEITADO | |
/consents/{consentID}/extends | POST | 201 | Renovação do consentimento finalizada com sucesso (payload de retorno conforme a especificação) |
|
422 | Necessário a aprovação de múltipla alçada | DEPENDE_MULTIPLA_ALCADA | ||
Estado inválido do consentimento | ESTADO_CONSENTIMENTO_INVALIDO | |||
Nova data para expiração de consentimento é inválida | DATA_EXPIRACAO_INVALIDA |