Criar sessão de conexão

Cria uma sessão temporária do Connect e retorna a URL do widget para onde você deve enviar o usuário final. A chamada deve ser feita do seu backend, autenticada com sua API Key.

Endpoint

Método e URL:

POST /v1/connect-sessions

Content-Type: application/json

Parâmetros do Body

Todos os campos são opcionais — um body vazio ({}) cria uma sessão com os valores padrão.

• redirectUrl (string, opcional): URL para onde o widget redireciona o usuário quando a conexão chega a um status final. Recebe itemId e status (success ou error) como parâmetros de query. Se omitido, o widget apenas exibe o resultado e orienta o usuário a fechar a janela.
• expiresInMinutes (number, opcional): validade da sessão em minutos, entre 1 e 60. Padrão: 30.

Campos da Resposta

• status: Status da operação ("success")
• data: Dados da sessão criada
  • key: Chave da sessão (prefixo of_connect_). Já vem embutida na connectUrl — você normalmente não precisa usá-la diretamente.
  • connectUrl: URL do widget para enviar ao usuário (redirecionamento ou nova aba).
  • expiresAt: Data/hora de expiração da sessão (ISO 8601).

Exemplo de Uso

Requisição:

POST /v1/connect-sessions
Content-Type: application/json

{
  "redirectUrl": "https://app.suaempresa.com.br/callback",
  "expiresInMinutes": 30
}

Resposta

Resposta de sucesso (201):

{
  "status": "success",
  "data": {
    "key": "of_connect_AbC123dEf456GhI789jKl012MnO345pQr678",
    "connectUrl": "https://of-connect.openi.com.br/?key=of_connect_AbC123dEf456GhI789jKl012MnO345pQr678",
    "expiresAt": "2026-07-03T15:30:00.000Z"
  }
}

Resposta de erro (400):

{
  "status": "error",
  "message": "Invalid url"
}

Fluxo após a criação

1. Envie o usuário para a connectUrl — redirecionamento ou nova aba.
2. O usuário conecta a conta no widget (instituição, dados de acesso, OAuth se necessário).
3. O usuário retorna ao seu redirectUrl com itemId e status na query string.
4. Use o itemId em Buscar Item e nos endpoints de dados (contas, transações, investimentos).

Notas Importantes

• Crie a sessão sempre no backend — nunca exponha sua API Key no frontend. Ao usuário, entregue somente a connectUrl.
• A sessão fica vinculada a uma conexão: depois que o item chega a syncing/synced, ela não permite criar outra. Para conectar outra instituição, crie uma nova sessão.
• Crie a sessão no momento em que o usuário for iniciar a conexão (e não com antecedência), para não desperdiçar a janela de validade.
• Após 5 tentativas com dados inválidos a sessão é bloqueada; crie uma nova sessão para o usuário tentar de novo.
• Cadastre webhooks para acompanhar a conexão pelo backend — os eventos de item são enviados normalmente para conexões criadas pelo Connect.