PluggyDocs

Criando um caso de uso do zero

Este artigo é um guia passo a passo para construir um aplicativo de exemplo simples que se integra com o Pluggy.

Propósito#

Este artigo é um guia passo a passo para construir um aplicativo de exemplo simples que se integra com o Pluggy. A ideia deste guia é reunir todos os conceitos importantes do Pluggy em um exemplo prático.

O que vamos construir#

Vamos construir uma aplicação PFM (gestão financeira pessoal) simples que mostra um relatório dos movimentos da sua conta bancária divididos por categorias.

Você pode conferir o código no repositório do projeto.

Passo 1: Criando uma conta Pluggy#

Primeiro, precisaremos de uma conta Pluggy para poder conectar contas bancárias com nosso aplicativo e recuperar dados bancários com a API Pluggy. Precisamos nos inscrever no dashboard.

Passo 2: Criando uma aplicação no dashboard#

Uma vez que temos nossa conta, precisaremos criar uma aplicação no dashboard. Uma aplicação tem um conjunto de credenciais (clientId e clientSecret) que nosso aplicativo usará para interagir com a API.

Passo 3: Testando a API#

Para verificar se estamos configurados corretamente, vamos obter uma chave de API para interagir com a API Pluggy. Isso é feito através do endpoint /auth. Você pode baixar a coleção do Postman e preencher o client id e o client secret da sua aplicação.

Com essa chave de API, podemos visualizar e gerenciar todos os dados do Pluggy para nossa aplicação (PluggyMyExpenses). Vamos testar nossa chave de API invocando o endpoint /connectors, incluindo a chave no cabeçalho X-API-KEY. Para saber mais sobre Autenticação com a API Pluggy, confira Autenticação.

Passo 4: Criando nosso projeto#

Neste aplicativo de exemplo, usaremos Next.js com Typescript, mas você pode usar qualquer tecnologia com a qual esteja mais familiarizado.

Passo 5: Conectando uma conta bancária#

Para permitir que os usuários conectem suas contas facilmente em nosso frontend, podemos usar o Pluggy Connect Widget e abri-lo com um botão em nossa página.

Antes de podermos instanciar o widget, precisaremos criar um endpoint de Backend que gera um token de Conexão para cada usuário que visita nossa página. Este token de conexão tem permissões e duração restritas por motivos de segurança. A lógica do nosso endpoint seria algo assim:

import { PluggyClient } from 'pluggy-sdk'
 
const PLUGGY_CLIENT_ID = process.env.PLUGGY_CLIENT_ID || ''
const PLUGGY_CLIENT_SECRET = process.env.PLUGGY_CLIENT_SECRET || ''
 
// ...
 
const client = new PluggyClient({
  clientId: PLUGGY_CLIENT_ID,
  clientSecret: PLUGGY_CLIENT_SECRET,
});
 
const connectToken = await client.createConnectToken()
 
// ...
res.status(200).json(connectToken)

Para criar tokens de conexão facilmente, usamos o Pluggy Node SDK.

Aviso de segurança

Não armazene clientId e clientSecret no frontend. Se essas informações forem visíveis no código da sua página, um atacante pode roubar todos os dados bancários dos seus usuários.

Agora que temos nosso endpoint de token de conexão, podemos obtê-lo em nosso frontend e instanciar o widget quando o usuário clicar em um botão, assim:

import { PluggyConnect } from 'react-pluggy-connect';
 
// Busque o token de conexão do backend e armazene-o em 'connectToken'...
 
{isWidgetOpen ? (
  <PluggyConnect
    connectToken={connectToken}
    includeSandbox={true}
    onClose={() => setIsWidgetOpen(false)}
    onSuccess={onSuccess}
  />
) : (
  <button
    className="btn btn-primary btn-lg"
    onClick={() => setIsWidgetOpen(true)}
  >
    Conecte sua conta
  </button>
)}

Aqui usamos o React Pluggy Connect SDK.

Uso no Next.js

Se você estiver tentando usar o widget a partir de uma página Next.js, precisará mudar um pouco como o Widget é carregado. Confira no código aqui.

Agora, quando nosso usuário clicar em Conectar minha conta, um token de Conexão é obtido e o Connect Widget é instanciado com esse token e abre um modal para o usuário inserir suas credenciais.

Uma vez que a conta bancária se conecta com sucesso, seus dados bancários estarão disponíveis na API Pluggy para recuperação com as credenciais da nossa aplicação.

Se você quiser experimentar e conectar uma conta de teste, pode usar os connectors de sandbox. Agora, vamos fazer algo interessante com esses dados!

Passo 6: Usando os dados bancários#

Uma vez que o usuário conecta sua conta, podemos obter seus dados da API. Todos os dados recuperados do usuário estão associados a um Item. Assim que o widget terminar, ele emite um evento onSuccess, com o id do Item recém-criado.

Não perca seu itemId!

Para qualquer ação que você queira realizar no futuro com os dados bancários conectados, você precisará do ID do Item (esse valor não pode ser recuperado depois). Certifique-se de armazená-lo ouvindo o evento onSuccess do widget.

Podemos ouvir esse evento e informar ao backend para buscar os dados do usuário e criar o relatório para nosso PFM:

const onSuccess = async (itemData: { item: any; }) => {
  const reportResponse = await fetch('/api/report?itemId=' + itemData.item.id)
  const {categoryBalances, startDate} = await reportResponse.json()
  setIsWidgetOpen(false) // Fecha o widget
  // ...
}
import { PluggyClient } from 'pluggy-sdk';
 
const PLUGGY_CLIENT_ID = process.env.PLUGGY_CLIENT_ID || '';
const PLUGGY_CLIENT_SECRET = process.env.PLUGGY_CLIENT_SECRET || '';
 
const client = new PluggyClient({
  clientId: PLUGGY_CLIENT_ID,
  clientSecret: PLUGGY_CLIENT_SECRET,
});
 
// ...
 
// Neste exemplo, colocamos todas as transações de todas as contas em uma lista
const accounts = await client.fetchAccounts(req.query.itemId as string);
const transactions = [];
for (const account of accounts.results) {
  const accountTransactions = await client.fetchAllTransactions(account.id);
  transactions.push(...accountTransactions);
}
 
// Então podemos fazer o que precisamos com os dados e retornar a resposta

A partir do relatório do backend, podemos criar uma tabela bonita e mostrar ao usuário seus movimentos por categoria.

Passo 7: Atualizando os dados bancários#

Na primeira vez que um usuário conecta sua conta usando o Widget, o Pluggy tentará recuperar dados bancários de até 1 ano atrás (ou o quanto a instituição permitir). Se quisermos atualizar os dados bancários do usuário sem recuperá-los tudo novamente, apenas recuperando novas informações, podemos simplesmente atualizar o Item. Podemos fazer isso facilmente instanciando o widget com a prop updateItem definida

<PluggyConnect
  connectToken={connectToken}
  includeSandbox={true}
  onClose={() => setIsWidgetOpen(false)}
  onSuccess={onSuccess}
  updateItem={itemIdToUpdate} // ID do Item que obtivemos ao criar a conexão
/>

Uma vez que o item foi atualizado, o widget emite o evento onSuccess e podemos criar nosso relatório novamente, com o item atualizado.

Passo 8: Armazenando dados bancários#

Se precisarmos analisar os dados bancários de todos os nossos usuários conectados (isso é ideal para aplicativos de pontuação de crédito), acelerar o carregamento e fazer backup dos dados bancários em caso de uma falha na API, provavelmente precisaremos configurar nosso próprio banco de dados. Você pode usar qualquer tecnologia e abordagem que seu negócio precisar. No nosso código de exemplo, usamos Supabase (PostgreSQL) e salvamos os dados do item toda vez que uma criação de Item é bem-sucedida. Se você estiver interessado em como fizemos isso, dê uma olhada no repositório do projeto.

Passo 9: Reagindo a eventos da API#

Até agora, reagimos ao onSuccess do widget para informar ao nosso backend que um Item foi criado. Mas e se o usuário sair da página antes que o Item seja criado? Ou e se quisermos manter nossos itens atualizados sem interação do usuário (para instituições que permitem)?

Se quisermos cobrir esses casos de uso, podemos usar os webhooks do Pluggy.

Dessa forma, podemos configurar um endpoint em nosso backend que o Pluggy chamará sempre que um item for criado ou atualizado. Receberemos um payload que se parece com isso:

{
  "event":"item/updated",
  "id":"a5c763cb-0952-457b-9936-630f79c5b016",
  "itemId":"a5c763cb-0952-457b-9936-630f79c5b016",
  "triggeredBy": "USER"
}

E podemos manipulá-lo a partir do nosso endpoint /items.

Então precisamos criar o webhook usando o endpoint POST /webhooks da API Pluggy.

{
  "event": "item/updated",
  "url": "https://{YOUR_APP_URL}/api/items"
}

Considerações finais#

Parabéns! Você agora está pronto para usar sua aplicação alimentada pelo Pluggy!