# Ambientes e Configurações

Obtenha sua aplicação web rapidamente e sem problemas integrada à nossa plataforma usando nosso Connect Widget!

## Ambientes

O Connect Widget funciona em um único ambiente de **Produção**, disponível em:

```
https://connect.pluggy.ai
```

Usando o ambiente de produção, você pode acessar tanto os conectores `Live` quanto os conectores `Sandbox` — não há uma URL de sandbox separada.

### Testes no Sandbox

Para fins de teste, você pode experimentar sua integração usando nossos conectores do **Pluggy Bank** Sandbox. O Pluggy Bank fornece transações atualizadas diariamente e permite que você teste todos os fluxos de login e cenários que você encontraria ao usar qualquer um dos conectores Live disponíveis.

Para exibir conectores Sandbox na etapa de seleção de Conector, defina a propriedade `includeSandbox` como `true` (não destinado ao uso em produção):

```javascript
const pluggyConnect = new PluggyConnect({
  connectToken: 'your-connect-token',
  includeSandbox: true,
  onSuccess: (itemData) => {
    console.log('Success!', itemData);
  },
});
```

#### Credenciais de teste do Pluggy Bank

Para uma conexão bem-sucedida com o conector Pluggy Bank, use:

| Campo                       | Valor          |
| :-------------------------- | :------------- |
| Usuário                    | `user-ok`      |
| Senha                      | `password-ok`  |
| Token MFA (quando solicitado)  | `123456`       |

Qualquer outro nome de usuário resultará em um erro `INVALID_CREDENTIALS`. Para a lista completa de usuários de teste cobrindo cenários de erro (conta bloqueada, site não disponível, fluxos de MFA, Open Finance e mais), consulte o [guia do Sandbox](/docs/guides/sandbox).

## SDKs disponíveis

O Connect Widget está atualmente disponível para os seguintes ambientes:

| Plataforma                | Pacote / Exemplo                                                                                     |
| :---------------------- | :---------------------------------------------------------------------------------------------------- |
| React                   | [react-pluggy-connect](https://www.npmjs.com/package/react-pluggy-connect)                            |
| React Native            | [react-native-pluggy-connect](https://www.npmjs.com/package/react-native-pluggy-connect)              |
| Flutter                 | [flutter_pluggy_connect](https://pub.dev/packages/flutter_pluggy_connect)                             |
| JavaScript Vanilla      | [pluggy-connect-sdk](https://www.npmjs.com/package/pluggy-connect-sdk)                                |
| Next.js                 | [Exemplo de Quickstart](https://github.com/pluggyai/quickstart/tree/master/frontend/nextjs)              |
| JavaScript Simples (HTML) | [Exemplo de Quickstart](https://github.com/pluggyai/quickstart/blob/master/frontend/html/index.html)     |

Navegue até cada projeto para encontrar informações de uso mais detalhadas em cada README. Você também pode conferir nosso repositório de [Quickstarts](https://github.com/pluggyai/quickstart) para ajudá-lo a começar com sua própria integração.

> **Interessado em contribuir?**
>
> Deixe-nos saber se você precisa, ou está interessado em contribuir, com uma biblioteca para uma linguagem não representada aqui! Escreva para nós em [hello@pluggy.ai](mailto:hello@pluggy.ai)

## Configurações disponíveis

**Nota:** todos os parâmetros são opcionais, exceto pelo `connectToken`.

| Propriedade | Descrição | Tipo |
| :------- | :---------- | :--- |
| `connectToken` | Seu token Pluggy Connect, que será usado para acessar a API. | `string` |
| `includeSandbox` | Se deve exibir conectores Sandbox na etapa de seleção de Conector (não destinado ao uso em produção). | `boolean` |
| `allowConnectInBackground` | Se `true`, o Connect pode ser minimizado pelo usuário para continuar a conexão com o componente oculto. | `boolean` |
| `allowFullscreen` | Se definido como `false`, o Connect não será exibido em tela cheia em telas pequenas/móveis; será exibido como um modal. O padrão é `true`. | `boolean` |
| `updateItem` | ID do Item a ser atualizado. Se especificado, o widget exibirá diretamente o formulário de credenciais do Item a ser atualizado. | `string` |
| `selectedConnectorId` | Se especificado, e o Conector estiver disponível, após aceitar os termos, o widget navegará diretamente para o formulário de login deste Conector, pulando a etapa de seleção de conector. | `number` |
| `connectorTypes` | Lista de Tipos de Conector. Se definido, apenas Conectores dos tipos de conector especificados (`PERSONAL_BANK`, `BUSINESS_BANK`, etc.) serão listados. Útil para casos de diferentes fluxos para usuários PF ou PJ. | `ConnectorType[]` |
| `connectorIds` | Lista de IDs de Conector. Se definido, apenas Conectores com os IDs de conector especificados serão listados. | `number[]` |
| `countries` | Lista de códigos de países (formato ISO-3166-1 alpha-2). Se definido, apenas Conectores dos países especificados serão listados. | `CountryCode[]` |
| `products` | Se definido, apenas os produtos especificados neste array serão executados na criação do Item (para serem executados, você deve tê-los habilitados na assinatura da sua equipe). **Importante**: os tipos de produtos devem ser especificados em letras maiúsculas (`ACCOUNTS`, `CREDIT_CARDS`, `TRANSACTIONS`, etc.). | `ProductType[]` |
| `language` | String ISO de idioma usada para exibir o widget. Se não especificado, ou se o idioma selecionado não for suportado, o idioma padrão `'pt'` será usado. | `string` |
| `theme` | Tema a ser usado para exibir a interface. Pode ser `'light'` ou `'dark'`. O padrão é `'light'`. | `'light' \| 'dark'` |
| `openFinanceParameters` | Objeto com CPF e CNPJ apenas para conectores Open Finance; o formulário será pré-preenchido com esses valores. Contém campos de string opcionais `cpf` e `cnpj`. | `{ cpf?: string; cnpj?: string }` |
| `forceOauthInBrowser` | Se definido como `true`, as URLs de OAuth sempre abrirão no navegador do sistema em vez de em uma webview. Isso ajuda a evitar problemas relacionados à webview. Esta propriedade tem precedência sobre o valor de configuração da API. | `boolean` |
| `forceAskForCredentials` | Se definido como `true`, o widget sempre solicitará credenciais ao atualizar um Item, mesmo que o sistema normalmente tentasse atualizar automaticamente. | `boolean` |
| `onSuccess` | Função a ser executada quando um Item foi criado/atualizado com sucesso. | `(data: { item: Item }) => void \| Promise<void>` |
| `onError` | Função a ser executada em um erro geral ao carregar o widget, ou quando o status de criação/atualização de um Item não foi bem-sucedido. Para validar qual erro ocorreu, verifique `item.executionStatus`. | `(error: { message: string; data?: { item: Item } }) => void \| Promise<void>` |
| `onOpen` | Função a ser executada quando o modal do widget foi aberto. | `() => void \| Promise<void>` |
| `onClose` | Função a ser executada quando o modal do widget foi fechado. | `() => void \| Promise<void>` |
| `onHide` | Função a ser executada quando o modal do widget foi ocultado. Será chamada apenas se a propriedade `allowConnectInBackground` estiver definida como `true`. | `() => void \| Promise<void>` |
| `onEvent` | Função a ser executada para lidar com eventos de interação do usuário personalizados. Veja [onEvent](#onevent) abaixo para mais informações. | **Desde v2.0.0:**<br />`(payload: ConnectEventPayload) => void \| Promise<void>`<br />**Até v1.x:**<br />`(event: string, metadata: { timestamp: number }) => void` |

## onEvent

Use este callback para lidar com eventos específicos de interação do usuário.

A propriedade `event` dentro do `payload` de `onEvent` é o evento atual acionado. Os eventos disponíveis que podem ser tratados por meio deste método são:

| Nome do evento               | Descrição                                                                                                                                                               |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `'SUBMITTED_CONSENT'`    | O usuário confirmou os termos e o consentimento de privacidade na primeira tela de Boas-vindas.                                                                                                   |
| `'SELECTED_INSTITUTION'` | O usuário selecionou uma instituição para se conectar.                                                                                                                           |
| `'SUBMITTED_LOGIN'`      | O usuário enviou credenciais para criar o Item de conexão.                                                                                                             |
| `'SUBMITTED_MFA'`        | O usuário enviou um parâmetro extra que foi solicitado pela instituição para se conectar.                                                                              |
| `'LOGIN_SUCCESS'`        | O usuário enviou credenciais para criar o Item de conexão **com sucesso**.                                                                                            |
| `'LOGIN_MFA_SUCCESS'`    | O usuário enviou um parâmetro extra que foi solicitado pela instituição para se conectar **com sucesso**.                                                             |
| `'LOGIN_STEP_COMPLETED'` | Conclusão bem-sucedida do login. O usuário efetivamente fez login na instituição.                                                                                        |
| `'ITEM_RESPONSE'`        | Chamado toda vez que o objeto Item é recuperado da API Pluggy, seja quando criado, atualizado ou cada vez que é recuperado para verificar seu status de conexão/executação. |

O objeto `payload` tem uma propriedade `timestamp`, e alguns eventos incluem dados extras:

- `'SELECTED_INSTITUTION'` inclui a propriedade `connector`, que é o conector selecionado pelo usuário.
- `'LOGIN_SUCCESS'`, `'LOGIN_MFA_SUCCESS'`, `'LOGIN_STEP_COMPLETED'` e `'ITEM_RESPONSE'` incluem a propriedade `item`, que é os dados do Item relacionados à conexão atual.

> **Mudança de assinatura v2.0.0**
>
> Desde a versão 2.0.0 do widget, `onEvent` recebe um único objeto de payload: `(payload: ConnectEventPayload) => void`.
> Nas versões 1.x, recebia dois argumentos: `(event: string, metadata: { timestamp: number }) => void`.

## Webhooks e callbacks

Após um usuário fazer uma conexão com o Pluggy Connect Widget, existem duas maneiras de obter o ID do Item recém-criado.

### Callbacks do Connect Widget

No frontend da sua aplicação (site, aplicativo, etc.), quando você está usando o Connect Widget, você tem acesso a [callbacks](#available-configurations). Dessa forma, você pode passar uma função para o widget que será executada quando um evento acontecer (por exemplo, uma conta conectada com sucesso ou com erro). O que é importante você saber aqui é que os callbacks são usados para melhorar a experiência do usuário, como redirecionar usuários para uma página de sucesso ou mostrar uma mensagem de erro.

```jsx
<PluggyConnect
  ...
  onSuccess={({ item }) => console.log(item.id)}
  onError={({ message, data: { item } }) => showErrorPage(message)}
/>
```

Essa abordagem é ótima para lidar com a lógica do frontend, mas é inconsistente por natureza: você não pode contar com ela para sua lógica de negócios ou integridade do banco de dados. Por exemplo, um usuário pode fechar o aplicativo antes que a conexão termine com sucesso, e você nunca perceberá que a conexão foi finalizada. Para ser consistente, use webhooks.

> **onSuccess não será chamado sempre!**
>
> A Caixa Econômica Federal (PF & PJ) tem fluxos de autorização que exigem que o usuário autorize o Pluggy como um dispositivo confiável, e o processo tem um atraso de cerca de 30 minutos.
> Nesse cenário, você receberá um `onError` com o status `USER_AUTHORIZATION_PENDING`, e o evento de SUCESSO será comunicado via webhooks.

### Webhooks

Um webhook (também conhecido como callback web) é um método simples que facilita para um aplicativo ou sistema fornecer informações em tempo real sempre que um evento acontece — ou seja, é uma maneira de receber dados passivamente entre dois sistemas através de um `HTTP POST`.

Os webhooks enviarão uma notificação para sua API / backend quando eventos relacionados a conexões acontecerem. Por exemplo, você pode ser notificado quando um Item é criado ou atualizado (leia mais na [referência de Webhooks](/docs/developer-tools/webhooks-ref)).

Você precisará criar um endpoint para ouvir os eventos de webhook do Pluggy e, em seguida, criar um webhook apontando para esse endpoint. Mais detalhes podem ser encontrados na [referência de Webhooks](/docs/developer-tools/webhooks-ref), mas o que é importante entender aqui é que os webhooks são a maneira de obter o ID do Item de uma conexão para você trabalhar. Embora você também possa recuperar o ID do Item com callbacks no frontend, lidar com a lógica de negócios com eles é uma má prática: por exemplo, um usuário fechando o site enquanto faz a conexão resultará na perda do ID do Item dessa conexão, significando que você nunca poderá recuperar os dados do Item.

### Resumo

|                              | Callbacks                          | Webhooks                                                                 |
| :--------------------------- | :--------------------------------- | :------------------------------------------------------------------------ |
| Onde usá-los                 | Frontend                           | Backend                                                                  |
| Como a informação é entregue | Chamadas de função de callback JavaScript | Requisições HTTP POST                                                       |
| Propósito                    | Melhorar a experiência do usuário  | Entregar notificações ao seu backend quando eventos relacionados ao Pluggy acontecerem  |