Consentimento no Open Finance: o que muda no seu código

Quase todo bug de Open Finance que aparece meses depois do lançamento tem a mesma origem: o código tratou o consentimento como algo que se pede uma vez e se esquece.

Na demo funciona. Em produção, com milhares de conexões, uma parte delas vai expirar, outra vai ser revogada pelo cliente no app do banco, e o seu produto vai começar a mostrar extrato vazio sem nenhum erro aparente.

Este texto é para quem já decidiu integrar e está escrevendo o código. O que a norma diz, o que a API devolve e como desenhar o fluxo para que renovação seja rotina, não incidente.

A regra mudou, e muita fonte ainda traz a antiga

Se você pesquisar "prazo do consentimento Open Finance", vai encontrar em muito lugar a resposta "12 meses". Ela está desatualizada.

O teto fixo de 12 meses caiu. Pela redação dada pela Resolução Conjunta nº 7, de 26 de outubro de 2023, o consentimento passa a ter prazo de validade compatível com as finalidades que foram declaradas ao cliente. Não existe mais um número único que vale para todo mundo.

O que confunde é que a Resolução Conjunta nº 1/2020 também fala em 12 meses, mas em outro ponto: a janela de histórico de transações que pode ser compartilhada. Prazo do consentimento e profundidade do histórico são duas coisas diferentes, e muito conteúdo mistura as duas.

Na prática, para o seu código: não assuma prazo nenhum. Leia a data de expiração que vem em cada conexão e trate o valor nulo como "sem expiração".

As três etapas obrigatórias

Todo compartilhamento no Open Finance passa pelas mesmas três etapas, nessa ordem.

1. 1Consentimento. No seu produto, o cliente vê quais dados serão compartilhados, para qual finalidade e por quanto tempo, e concorda.
2. 2Autenticação. O cliente é levado para o ambiente da instituição de origem e se autentica lá, com as credenciais e o segundo fator do próprio banco. Você nunca vê a senha.
3. 3Confirmação. Ainda no banco, ele confirma o compartilhamento e volta para o seu produto.

O que isso muda no código: a etapa 2 acontece fora do seu domínio. O seu fluxo precisa sobreviver a redirecionamento, a cliente que fecha a aba no meio e a cliente que demora. Se você usa um widget de conexão, essa parte já vem tratada.

Prazo de validade: o que chega na sua mão

Na Pluggy, a primeira vez que uma conexão (o Item) é criada, nasce um consentimento com os produtos autorizados e uma data de expiração. Você consulta isso pela API de Consentimentos, e o Item também expõe a data no campo consentExpiresAt.

Dois detalhes que valem ouro:

• Por padrão, a Pluggy pede consentimento sem expiração. O cliente pode reajustar isso no fluxo, e nesse caso a data vem preenchida.
• Alguns conectores têm expiração padrão própria. O Inter PJ, por exemplo, vem com um ano.

Ou seja, numa base real você vai ter conexões sem data e conexões com datas diferentes convivendo. O código que funciona é o que lê o campo de cada uma, não o que assume uma regra global.

O que acontece quando expira ou é revogado

Aqui está a armadilha. Quando um consentimento expira, ou quando o cliente revoga pelo app do banco, os endpoints de dados não dão erro: eles voltam vazios. Contas, transações e o resto passam a retornar listas sem nada.

Se o seu código interpreta "lista vazia" como "o cliente não movimentou nada", você acabou de criar um bug silencioso. O painel do usuário mostra saldo parado, a conciliação para de bater, e ninguém recebe alerta.

O sinal certo é outro. A próxima atualização da conexão falha, o Item passa para LOGIN_ERROR e o webhook item/error é disparado com o código do motivo. Para Open Finance, os que importam aqui são:

O terceiro é o que mais gera retrabalho: ele também chega como item/error, mas não é falha. Tratar como quebrado faz você pedir reconexão para uma conexão que estava prestes a dar certo.

Revogação: o que você precisa tratar

Revogar é direito do cliente, a qualquer momento, pelo app do banco. Você não é avisado antes e não pode impedir.

O que fica com você:

• Parar de exibir dado novo como se fosse atual. A partir da revogação, o que você tem é foto do passado. Mostre a data da última atualização.
• Decidir o que fazer com o que já foi coletado. O consentimento do Open Finance autoriza o compartilhamento. O que você guarda e por quanto tempo segue a sua base legal na LGPD, e isso é decisão sua, não da API. Tratamos disso em o que um software pode guardar de dado bancário.
• Não reutilizar a conexão revogada. Pela documentação, o caminho depois de uma revogação é um novo consentimento, que gera uma nova conexão.

Renovação como parte do fluxo normal

Expiração não é exceção. É o ciclo de vida esperado de uma parte da sua base, e o fluxo deveria ser desenhado assim desde o primeiro dia.

A boa notícia: para renovar um consentimento expirado, você não cria uma conexão nova. Você atualiza o Item existente, o cliente passa de novo pelo fluxo de consentimento, e o Item volta para SUCCESS com uma nova data em consentExpiresAt. O histórico e o identificador continuam os mesmos.

No widget, isso é um Connect Token criado com o itemId e o parâmetro updateItem apontando para a conexão. O passo a passo está em atualizando um Item.

Sobre a experiência: o cliente não deveria descobrir que expirou porque o painel ficou vazio. Avise antes, com a data na mão e uma frase que soe como manutenção, não como erro. "Sua conexão com o banco vence em 10 dias. Renove em um clique para continuar vendo seu extrato" funciona melhor do que "Erro de autorização".

Leitura e pagamento são consentimentos diferentes

Sim, são. Compartilhar dados e iniciar um pagamento são autorizações separadas no Open Finance, com fluxos e ciclos de vida próprios. Ter o consentimento de leitura de um cliente não autoriza você a iniciar pagamento em nome dele, e o contrário também vale.

No código, isso significa não amarrar os dois estados num booleano só de "cliente conectado".

Padrão de implementação recomendado

Para uma base com milhares de conexões, o desenho que aguenta é este:

1. 1Guarde o itemId desde o primeiro callback. Ele chega no onSuccess do widget e no webhook item/created. Sem ele, você não consegue renovar nada.
2. 2Guarde a data de expiração de cada conexão e trate nulo como "não expira".
3. 3Rode um job diário que lista as conexões que vencem nos próximos dias e dispara o aviso de renovação.
4. 4Escute item/error e roteie pelo código: revogação pede novo consentimento, pendência espera, instabilidade do banco tenta de novo depois.
5. 5Nunca leia lista vazia como verdade sem conferir o status da conexão antes.
6. 6Responda o webhook em até 10 segundos e processe de forma assíncrona. Handler lento conta como falha e o evento é reenviado.

O detalhe de cada código está em detectando falhas de autenticação e o modelo de dados do consentimento em consentimentos e expiração.

E a Pluggy nisso tudo?

O Pluggy Connect cuida das três etapas obrigatórias e do redirecionamento para o banco, e também da renovação: o mesmo widget que cria a conexão atualiza a existente.

Do lado da API, você tem o consentimento consultável por conexão, a data de expiração no Item e o webhook com o motivo de cada falha. O que fica com você é a regra de negócio: quando avisar, o que mostrar e o que guardar.

Para o panorama regulatório completo, veja a regulação do Open Finance. Para o que muda do lado de segurança e responsabilidade, segurança no Open Finance. E o produto em si está em Open Finance.

Perguntas frequentes

Quanto tempo dura o consentimento no Open Finance?

Não existe mais um prazo único de 12 meses. Desde a Resolução Conjunta nº 7/2023, o prazo deve ser compatível com a finalidade declarada. Na Pluggy, o padrão é pedir consentimento sem expiração, e o cliente pode ajustar.

Como sei que vai expirar antes de quebrar?

Pela data de expiração de cada conexão, que vem no campo consentExpiresAt do Item. Um job diário que olha essa data resolve.

O que acontece com os dados quando o cliente revoga?

Dali para frente, os endpoints voltam vazios. O que você já coletou segue a sua base legal na LGPD.

Preciso criar uma conexão nova para renovar?

Para expiração, não: você atualiza a conexão existente. Para revogação, o caminho documentado é um novo consentimento.

Consentimento de leitura serve para pagamento?

Não. São autorizações separadas.

Conclusão

Consentimento não é um passo do onboarding. É um estado que muda ao longo da vida da conexão, e o código que trata isso desde o começo evita o bug mais comum do Open Finance em produção: o extrato vazio que ninguém percebe.

Se você está desenhando esse fluxo agora, crie uma conta e veja na prática o que chega no consentimento de uma conexão de teste.

Fontes

• Resolução Conjunta nº 1, de 4 de maio de 2020 (Banco Central e CMN), que define consentimento e a janela de histórico compartilhável.
• Resolução Conjunta nº 7, de 26 de outubro de 2023, que substituiu o teto fixo de 12 meses pelo prazo compatível com a finalidade.
• Portal Open Finance Brasil, sobre as etapas de consentimento, autenticação e confirmação.
• Documentação da Pluggy: consentimentos e expiração, erros e validações e atualizando um Item.