Primeiros passos

Fluxo de integração

Percurso de sucesso de uma integração iframe. O callback é enviado antes de o frontend ser notificado.

sequenceDiagram
participant Utilizador
participant Web
participant Widget as Wealth Reader Widget
participant API as Wealth Reader API
participant Banco as Instituição financeira
Utilizador->>Web: Abre a aplicação
Web->>Widget: Carrega o iframe com operation_id
Utilizador->>Widget: Escolhe uma instituição e dá o consentimento
Widget->>API: Pede os dados com operation_id
API->>Banco: Consulta
Banco-->>API: Responde
API-->>Widget: Devolve os dados normalizados
Widget->>Web: POST para o callback (operation_id + token + payload)
Web-->>Widget: HTTP 200 e status ok
Widget-->>Web: postMessage flow completed
Web-->>Utilizador: Mostra a conclusão com sucesso

Quem faz o quê

Ator	Responsabilidade
O seu frontend	Gera um `operation_id` único, carrega o widget e escuta `postMessage`.
O widget	Mostra bancos, início de sessão, 2FA e erros ao utilizador.
A API do Wealth Reader	Comunica com a instituição e normaliza a resposta.
O seu backend	Expõe o URL de callback, responde `{"status":"ok"}` e guarda `operation_id`, `token` e payload.

Se algo falhar

Palavra-passe errada, 2FA ou erro da instituição: o widget trata disso com o utilizador. O seu frontend pode receber um JSON de erro via postMessage; o callback não é chamado até a leitura terminar com sucesso.
O seu callback não devolve 200 + {"status":"ok"}: o utilizador não vê o sucesso e o frontend não recebe flow completed.
Um token deixa de funcionar (alteração de palavra-passe, novo 2FA): volte a abrir o widget passando esse token para o utilizador se voltar a autenticar.

O detalhe das mensagens e do corpo do callback está nas páginas iframe.

Passo seguinte

Se integrar via iframe, continue com frontend e depois backend. Se não puder incorporar um iframe, vá a OAuth.

Última atualização 2026-08-15