# Guia de Suporte OAuth

## Visão Geral

Algumas instituições financeiras exigem um fluxo de autorização OAuth para conectar contas de usuários. Este guia explica como configurar corretamente o widget Pluggy Connect para lidar com redirecionamentos OAuth em diferentes plataformas e dispositivos.

Seguindo estas diretrizes, você pode garantir uma experiência de integração OAuth tranquila para seus usuários em várias plataformas e dispositivos.

### O que o OAuth muda para sua integração

OAuth é um padrão de delegação de acesso: em vez de digitar credenciais em seu
aplicativo, o usuário o autoriza dentro da própria interface da instituição e a
instituição emite um token. Duas coisas decorrem disso, e ambas são o motivo pelo qual esses
conectores precisam de configuração extra do seu lado:

- **O usuário sai do seu aplicativo** — ele se autentica na instituição e
  precisa ser trazido de volta. Essa viagem de retorno é para isso que serve o `oauthRedirectUri`.
- **A conexão é renovada sem pedir novamente.** Um token OAuth pode ser renovado,
  então a conexão permanece ativa sem enviar o usuário pelo login a cada
  vez — o que também é o motivo pelo qual essas conexões tendem a quebrar menos do que as baseadas em credenciais.

A única coisa que geralmente dá errado é a viagem de retorno. Alguns navegadores móveis não
permitem que a janela de autorização se feche sozinha, e sem um URI de redirecionamento, o usuário fica
encarando uma página de autorização finalizada sem caminho de volta para seu aplicativo.

## Configurando o URI de Redirecionamento OAuth

Para lidar com redirecionamentos após o processo OAuth, você precisa definir um `oauthRedirectUri`. Este URI é usado para redirecionar os usuários de volta ao seu aplicativo após terem concluído o processo OAuth com a instituição financeira.

### Requisitos

O `oauthRedirectUri` deve cumprir as seguintes regras:

- Deve ser **HTTPS** ou um **deep link**
- **Não pode** ser `localhost` ou `127.0.0.1`

### Criando um Connect Token com Redirecionamento OAuth

Ao criar um Connect Token, inclua o `oauthRedirectUri` nas opções:

```bash
curl --request POST \
  --url https://api.pluggy.ai/connect_token \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "options": {
      "clientUserId": "your-user-id",
      "oauthRedirectUri": "https://your-own-url.com"
    }
  }'
```

> **Nota**: Se você criar um item com um Connect Token e também especificar o `oauthRedirectUri` no momento da criação do item, o sistema priorizará o parâmetro `oauthRedirectUri` fornecido no nível do item.

### Exemplos de URIs de redirecionamento

| URI | Válido | Por quê |
|-----|-------|-----|
| `https://app.example.com/pluggy/callback` | Sim | Página HTTPS em seu aplicativo |
| `myapp://my-deep-link` | Sim | Deep link em um aplicativo nativo |
| `http://app.example.com/callback` | Não | HTTP simples é rejeitado |
| `http://localhost:3000/callback` | Não | `localhost` e `127.0.0.1` são rejeitados |

Testando localmente, use o esquema de deep link do seu aplicativo ou um túnel HTTPS para sua
máquina — um URI `localhost` é recusado quando o token é criado, não depois.

## Comportamento Específico do Navegador

O fluxo OAuth se comporta de maneira diferente dependendo da plataforma do usuário:

### Navegadores de Desktop

Para **navegadores de desktop**, a janela de autorização tentará **fechar automaticamente** após a conclusão do processo OAuth.

Se fechar a janela não for possível, o usuário será redirecionado para o `oauthRedirectUri` fornecido.

### Navegadores Móveis

Para **navegadores móveis**, os usuários serão **redirecionados para o `oauthRedirectUri`** após completar a autorização OAuth.

Alguns navegadores móveis não permitem fechar a janela de autorização OAuth após a conclusão. Para resolver isso, você deve fornecer um `oauthRedirectUri` na solicitação do Connect Token, que será usado para redirecionar os usuários de volta ao seu aplicativo.

## Lidando com o Redirecionamento

Seu aplicativo deve estar preparado para lidar com o redirecionamento de volta para o `oauthRedirectUri`. Quando o usuário for redirecionado, você deve:

1. Verificar o status da conexão
2. Retomar a experiência do usuário em seu aplicativo
3. Lidar com quaisquer erros que possam ter ocorrido durante o processo OAuth

## Considerações sobre a Plataforma

### Aplicativos Web

Para aplicativos web, o `oauthRedirectUri` deve ser um URL HTTPS válido que aponte para uma página em seu aplicativo que possa lidar com o redirecionamento e retomar o fluxo de conexão.

### Aplicativos Móveis (Nativos)

Para aplicativos móveis nativos, você pode usar um **deep link** como o `oauthRedirectUri`. Isso permite que o fluxo OAuth redirecione de volta para seu aplicativo nativo após a autorização ser concluída.

Certifique-se de que seu aplicativo esteja devidamente configurado para lidar com o esquema de deep link tanto no iOS quanto no Android.

### React Native / Flutter

Ao usar React Native ou Flutter com o Pluggy Connect SDK, configure o `oauthRedirectUri` para usar o esquema de deep link do seu aplicativo. O SDK lidará com o redirecionamento e retomará o fluxo de conexão dentro do widget.

## Integração Backend, sem o widget

Se você criar itens a partir do seu próprio backend em vez de através do widget, você não
precisa de um Connect Token: autentique-se com sua chave de API e passe
`oauthRedirectUri` para [items-create](/reference/items/items-create), exatamente como você
faria nas opções do token.

```bash
curl --request POST \
  --url https://api.pluggy.ai/items \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "connectorId": 600,
    "parameters": {
      "user": "user-ok",
      "password": "password-ok"
    },
    "oauthRedirectUri": "https://your-own-url.com"
  }'
```

A resposta traz a URL OAuth para enviar o usuário. Quando um valor é dado em ambos
os lugares — nas opções do Connect Token e na criação do item — o que está no item
vence, porque é o mais específico dos dois.

## Melhores Práticas

- Sempre forneça um `oauthRedirectUri` quando seus usuários puderem se conectar a instituições que usam OAuth
- Use URLs HTTPS para aplicativos web e deep links para aplicativos móveis nativos
- Teste o fluxo OAuth em navegadores de desktop e móveis para garantir uma experiência tranquila
- Lide com casos extremos onde a janela de autorização não pode ser fechada automaticamente
- O `connectToken` é válido por **30 minutos apenas** — o uso recomendado é um token por conexão