IframePasso 2 de 2

Configure o backend

Receba no seu servidor os dados bancários normalizados e confirme corretamente o callback.

Complete primeiro a checklist de frontend. O widget não envia os dados bancários via postMessage: envia-os aqui, num POST.

Checklist de integração

0 de 4

Criar o URL de callback
Associar domínio, callback e api_key
Testar o fluxo com um utilizador de teste
Guardar operation_id, token e statistics.code

1. Criar o URL de callback

Exponha no seu servidor um endpoint HTTPS que aceite POST com um corpo JSON.

Depois de processar o necessário, responda HTTP 200 com o seguinte JSON:

{
    "status": "ok"
}

Se devolver outro código de estado ou um JSON diferente, o widget não notificará o frontend de que o fluxo terminou corretamente.

Trate o operation_id como idempotente: uma entrega repetida não deve criar duas operações no seu sistema.

2. O que chega no POST

O corpo é o mesmo JSON que POST /entities/ na referência OpenAPI. Campos necessários para cruzar a operação:

Campo	Utilização
`success`	`true` se a leitura terminou com sucesso.
`payload`	Dados normalizados (contas, carteiras, cartões, …).
`statistics.operation_id`	O `operation_id` que o seu frontend gerou.
`statistics.token`	Credencial custodiada para atualizações posteriores (se a tokenização estiver ativa).
`statistics.code`	Código da instituição (`bbva`, `caixabank`, …).
`statistics.SESSION`	Id de sessão, útil num ticket de suporte.
`statistics.warnings`	Avisos que não invalidam a leitura (por exemplo, um produto vazio).

Exemplo abreviado:

{
    "success": true,
    "payload": {
        "user_information": {
            "ID": "12345678Z",
            "name": "LUIS GARCIA BAQUERO"
        },
        "accounts": [
            {
                "uuid": "8076932f04f73e27fe608fee4d12fca8708dec8c",
                "subtype": "checking",
                "code": "ES4914651234561234567890",
                "name": "Cuenta NOMINA",
                "currency": "EUR",
                "balances": {
                    "available": 14302.07,
                    "current": 14302.07
                },
                "transactions": []
            }
        ]
    },
    "statistics": {
        "SESSION": "A1B2C3D4E5F67890",
        "execution_time": 12.4,
        "warnings": [],
        "operation_id": "8f1c2a6e-4b0d-4c3a-9e21-0d5b7a91c4e2",
        "token": "FRJ0mHlaqZwLzu",
        "code": "bbva"
    }
}

O esquema completo de payload está na OpenAPI. Não presuma que todas as chaves estão sempre presentes: depende de product_types e do que o utilizador tem na instituição.

3. Associar domínio, callback e chave de API

Na área de clientes associe:

o domínio a partir do qual o widget é carregado (a origem do seu frontend);
o URL de callback que acabou de criar;
a sua api_key.

Enquanto o domínio não estiver registado, o widget não funciona.

4. Testar o fluxo

Abra a página que carrega o widget e inicie sessão:

Utilizador	Palavra-passe	Resultado
`MOCKDATA`	qualquer	Leitura bem-sucedida com dados de exemplo anonimizados. O callback recebe JSON com `success: true`.
`MOCKOTP`	qualquer	Recria um desafio de autenticação de dois fatores.
`MOCKLOGINKO`	qualquer	Recria um erro de início de sessão. O callback não é chamado.

Se não tiver o e-mail de boas-vindas, peça-o a support@wealthreader.com.

Se quiser inspecionar o POST antes de o seu endpoint existir, crie um URL temporário num serviço como https://pipedream.com/ e defina-o como callback.

5. Atualizar dados (opcional)

Neste ponto tem uma integração one-shot: uma leitura de cada vez que o utilizador abre o widget.

Se precisar de um lote noturno ou de um botão «Atualizar», volte a chamar a API com o token e o code que guardou do callback. Não peça de novo o utilizador e a palavra-passe.

curl --location 'https://api.wealthreader.com/entities/' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'api_key=YOUR_API_KEY' \
  --data-urlencode 'code=bbva' \
  --data-urlencode 'token=TOKEN_FROM_CALLBACK' \
  --data-urlencode 'product_types=accounts,portfolios'

Preste atenção aos códigos de erro: não volte a tentar uma palavra-passe inválida; pode voltar a tentar quando a instituição estiver em manutenção.

Se o token deixar de funcionar (alteração de palavra-passe ou novo 2FA), volte a abrir o widget passando esse valor em wr_conf.token para o utilizador se voltar a autenticar.

Última atualização 2026-08-15