Fluxo de conexão

Este guia descreve o fluxo completo para conectar uma instituição financeira (banco, cartão, investimentos) à sua aplicação usando a API. Seguindo esta ordem, você evita dúvidas comuns e integra de forma correta.

Prefere não construir as telas de conexão? Use o Connect: sua aplicação cria uma sessão via POST /v1/connect-sessions e envia o usuário para uma interface pronta, hospedada por nós, que cuida da escolha da instituição, credenciais e OAuth — sem que os dados de acesso passem pela sua aplicação. Este guia cobre a integração direta via API, na qual você constrói a experiência.

Visão geral do fluxo

1. Cadastrar um webhook (recomendado antes de criar itens) — para receber notificações quando a conexão mudar de status.
2. Listar conectores — descobrir o ID da instituição (ex.: Itaú, Nubank).
3. Criar um item — iniciar a conexão com connectorId e parâmetros (ex.: CPF).
4. Consultar o item — acompanhar o status; se precisar de OAuth, usar auth.authUrl ou auth.userAction.
5. Opcional: ressincronizar — quando o item estiver synced, usar os endpoints de contas/transações; se precisar atualizar dados, usar ressincronização.

Todos os endpoints da API utilizam o prefixo /v1 e exigem autenticação via Bearer token (API Key).

---

Passo 1: Cadastrar um webhook (recomendado primeiro)

Antes de criar itens, cadastre pelo menos um webhook para receber notificações em tempo real quando o status da conexão mudar (por exemplo, de pending para waiting_user_input ou synced).

• Endpoint: POST /v1/webhooks
• Body: url (HTTPS obrigatório) e secret (chave que você define; será enviada no header Authorization nas requisições que fizermos ao seu endpoint)

Assim, quando o usuário concluir o OAuth ou a conexão for sincronizada, você recebe um evento no seu servidor em vez de depender só de polling em Buscar Item.

Detalhes: Gerenciar webhooks e Como receber webhooks.

---

Passo 2: Listar conectores

Para criar uma conexão, você precisa do ID do conector da instituição.

• Endpoint: GET /v1/connectors
• Query opcional: q=nome — busca parcial por nome (ex.: ?q=itau)

Na resposta, use o campo id (UUID v7) do conector desejado. O campo rules indica quais parâmetros são obrigatórios na criação do item (ex.: cpf, cnpj).

Ver: Listar conectores e Buscar conector.

---

Passo 3: Criar um item

Com o connectorId e os parâmetros exigidos pelas rules do conector:

• Endpoint: POST /v1/items
• Body (JSON):
  • connectorId (obrigatório): UUID v7 do conector
  • parameters (obrigatório): objeto com os campos exigidos (ex.: { "cpf": "123.456.789-01" })

A API retorna o id do item criado. O item nasce com status pending e pode evoluir para syncing, synced, waiting_user_input, auth_error, etc.

Ver: Criar Item.

---

Passo 4: Acompanhar o status do item

Use o id do item retornado no passo anterior:

• Endpoint: GET /v1/items/:id

Na resposta, verifique:

• data.status — estado atual da conexão (veja Itens - Status do Item).
• data.auth — quando não for null, a conexão pode exigir ação do usuário:
  • authUrl: redirecione o usuário para essa URL para concluir OAuth.
  • userAction: em alguns fluxos, as instruções vêm aqui (ex.: abrir app do banco, autorizar no celular). Use instructions e type para orientar o usuário.

Recomendações:

• Faça polling periódico em GET /v1/items/:id até o status ser estável (synced ou auth_error), ou
• Confie nos webhooks cadastrados no passo 1 (eventos como ITEM_UPDATED, ITEM_LOGIN_SUCCEEDED) e consulte o item quando receber o evento.

Quando status for synced, você pode usar os endpoints de contas e transações, além de investimentos e cartões, conforme o conector.

Ver: Buscar Item e Fluxo de Autenticação OAuth.

---

Passo 5: Quando pedir nova autenticação (OAuth / userAction)

1. Sua aplicação chama POST /v1/items e recebe o id do item.
2. Você consulta GET /v1/items/:id e recebe status: "waiting_user_input" e auth preenchido.
3. Redirecione o usuário para auth.authUrl (se existir) ou oriente-o conforme auth.userAction (ex.: “Abra o app do banco e autorize”).
4. O usuário conclui a ação na instituição.
5. A instituição e nossa API atualizam o item; você pode ser notificado por webhook (ITEM_UPDATED / ITEM_LOGIN_SUCCEEDED) ou descobrir consultando novamente GET /v1/items/:id (status synced).

Não é necessário criar outro item para o mesmo vínculo; use sempre o mesmo id do item.

---

Passo 6: Consentimentos e múltiplos titulares

Algumas contas exigem autorização de mais de um titular. O campo warnings em GET /v1/items/:id pode indicar que outro titular precisa autorizar no app do banco. Nesse caso:

• O usuário que iniciou a conexão não precisa autorizar de novo.
• Os demais titulares autorizam nos seus próprios aplicativos.
• Você não precisa criar um novo item; acompanhe o mesmo item até o status ficar synced.

Ver: Itens - Consentimentos.

---

Passo 7: Depois que o item está conectado

• Contas: GET /v1/items/:itemId/accounts — lista contas bancárias.
• Transações: use o endpoint de transações por conta (ver Listar transações).
• Ressincronizar: POST /v1/items/:id/resync — força atualização dos dados quando o item já está synced.

---

Resumo rápido

Alternativa aos passos 2–4: criar uma sessão do Connect (POST /v1/connect-sessions) e deixar o widget conduzir o usuário pela escolha da instituição, credenciais e OAuth.

Para testar os endpoints sem integrar direto na sua aplicação, use a Collection do Postman que disponibilizamos.