Connect (Widget)

Interface pronta e hospedada para o usuário final conectar a conta dele sem que sua aplicação manipule credenciais.

O Connect é uma interface web pronta, hospedada por nós, que conduz o usuário final por todo o fluxo de conexão: escolher a instituição, informar os dados de acesso, concluir o OAuth no banco e acompanhar a sincronização.

Em vez de construir suas próprias telas e chamar Criar Item diretamente, sua aplicação cria uma sessão de conexão (connect session) via API, recebe uma URL e envia o usuário para ela — por redirecionamento ou nova aba. Ao final, o usuário volta para sua aplicação com o itemId criado.

Por que usar o Connect

Sem manipular credenciais: os dados de acesso do usuário (CPF, senha etc.) são informados diretamente no widget — nunca passam pelo seu backend ou frontend.
Fluxo completo pronto: lista de instituições com busca, formulário com os campos exigidos pelo conector, redirecionamento OAuth e tela de progresso da sincronização.
Link temporário e seguro: a sessão expira automaticamente (30 minutos por padrão) e a chave da sessão não dá acesso aos dados da conta — apenas ao fluxo de conexão.

Se você prefere controle total da experiência, o fluxo direto via API continua disponível: veja o Fluxo de conexão.

Como funciona

Sua aplicação cria uma sessão: POST /v1/connect-sessions (autenticado com sua API Key), opcionalmente informando um redirectUrl.
Você envia o usuário para a connectUrl retornada — redirecionamento ou window.open.
O usuário conclui a conexão no widget: escolhe a instituição, informa os dados e, se necessário, autoriza no site/app do banco (OAuth).
O widget acompanha a sincronização e, ao chegar em um status final, redireciona o usuário para o seu redirectUrl com itemId e status na query string.
Sua aplicação usa o itemId normalmente nos endpoints de itens, contas, transações e investimentos.

Sua aplicação                    API                        Connect (widget)
     │  POST /v1/connect-sessions │                              │
     ├───────────────────────────>│                              │
     │  { key, connectUrl, ... }  │                              │
     │<───────────────────────────┤                              │
     │                                                           │
     │  redireciona o usuário para connectUrl                    │
     ├──────────────────────────────────────────────────────────>│
     │                                usuário conecta a conta    │
     │                                                           │
     │  redirect: {redirectUrl}?itemId=...&status=success        │
     │<──────────────────────────────────────────────────────────┤

Retorno para sua aplicação

Se você informou redirectUrl ao criar a sessão, o widget redireciona o usuário quando a conexão chega a um status final, acrescentando dois parâmetros de query:

itemId: o ID do item criado — use-o nos demais endpoints da API.
status: success (conexão estabelecida, dados sincronizando ou sincronizados) ou error (falha de autenticação ou erro).

Exemplo: https://app.suaempresa.com.br/callback?itemId=01985c42-1234-7890-abcd-ef1234567890&status=success

Sem redirectUrl, o widget apenas exibe o resultado e orienta o usuário a fechar a janela. Nesse caso, acompanhe a conexão pelos webhooks (recomendado de qualquer forma): eventos como ITEM_CREATED, ITEM_UPDATED e ITEM_LOGIN_SUCCEEDED são enviados normalmente para itens criados pelo Connect.

Ciclo de vida da sessão

Expiração: por padrão a sessão vale por 30 minutos (configurável de 1 a 60 via expiresInMinutes). Após expirar, o link mostra uma mensagem de expiração — crie uma nova sessão.
Uma conexão por sessão: a sessão fica vinculada ao item criado. Enquanto a conexão não é concluída, o usuário pode tentar novamente (ex.: após erro de autenticação); depois que o item chega a syncing/synced, a sessão não permite criar outra conexão.
Limite de tentativas: após 5 tentativas com dados inválidos, a sessão é bloqueada e o usuário precisa de um novo link.
Retomada: se o usuário reabrir a connectUrl com uma conexão em andamento, o widget retoma o acompanhamento do mesmo item.

Segurança

A key da sessão (prefixo of_connect_) é feita para o navegador do usuário final: é temporária, serve só para o fluxo de conexão e não expõe dados de contas ou transações.
Nunca envie sua API Key ao frontend. Crie a sessão sempre no seu backend e entregue apenas a connectUrl ao usuário.

Próximos passos

Criar sessão de conexão — referência do endpoint POST /v1/connect-sessions.
Como receber webhooks — para ser notificado quando a conexão mudar de status.
Buscar Item — consultar o item criado pelo widget.