# Criando um caso de uso do zero

## Propósito

Este artigo é um guia passo a passo para construir um aplicativo de exemplo simples que integra com o Pluggy. A ideia deste guia é juntar 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.

![Aplicativo de demonstração PFM](/docs/images/use-case-pfm-demo.png)

Você pode conferir o código no [repositório do projeto](https://github.com/pluggyai/my-expenses).

## 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 Referência da API Pluggy. Precisamos nos inscrever no [dashboard](https://dashboard.pluggy.ai).

## 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 Referência da API Pluggy. Isso é feito através do endpoint [`/auth`](/reference/auth-create). Você pode baixar a [coleção do Postman](/docs/run-in-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`](/reference/connectors-list), incluindo a chave no cabeçalho `X-API-KEY`. Para saber mais sobre Autenticação com a Referência da API Pluggy, confira [Autenticação](/docs/authentication).

## Passo 4: Criando nosso projeto

Neste aplicativo de exemplo, usaremos [Next.js com Typescript](https://nextjs.org/docs/basic-features/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](/docs/pluggy-connect-introduction) 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 Connect token para cada usuário que visita nossa página. Este connect token tem permissões e duração restritas por motivos de segurança. A lógica do nosso endpoint seria algo assim:

```typescript
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 connect tokens facilmente, usamos o [Pluggy Node SDK](https://github.com/pluggyai/pluggy-node/).

<Callout variant="info" title="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.
</Callout>

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

```typescript
import { PluggyConnect } from 'react-pluggy-connect';

// Buscar connect token do backend e armazená-lo 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](https://www.npmjs.com/package/react-pluggy-connect).

<Callout variant="info" title="Uso no Next.js">
Se você estiver tentando usar o widget de uma página Next.js, precisará mudar um pouco como o Widget carrega. Confira no código [aqui](https://github.com/pluggyai/my-expenses/blob/5a1b314d07052d3ac43fae17ab2ac44760de6eb4/pages/index.tsx#L6).
</Callout>

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

![Pluggy Connect Widget](/docs/images/use-case-connect-widget.png)

Uma vez que a conta bancária se conecta com sucesso, seus dados bancários estarão disponíveis na Referência da 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](/docs/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](/docs/item). Assim que o widget terminar, ele emite um evento onSuccess, com o id do Item recém-criado.

<Callout variant="info" title="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.
</Callout>

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

```typescript
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
  // ...
}
```

```typescript
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
```

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

![Tabela de transações por categoria](/docs/images/use-case-transactions.png)

## 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

```typescript
<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 a criação de um Item é bem-sucedida. Se você estiver interessado em como fizemos isso, dê uma olhada no [repositório do projeto](https://github.com/pluggyai/my-expenses).

## 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 isso)?

Se quisermos cobrir esses casos de uso, podemos usar os [webhooks](/docs/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:

```json
{
  "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](/reference/webhooks-create) da Referência da API Pluggy.

```json
{
  "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!