); } export default App; // Hook function useScript(src) { useEffect( () => { // Criar script const node = document.createElement('script'); node.src = src; node.type = 'text/javascript'; node.async = true; node.onload = createWidget // Adicionar script ao corpo do documento document.body.appendChild(node); }, [src] // Reexecutar o efeito apenas se o src do script mudar ) } ``` ```html ``` > 🚧 Certifique-se de incluir a **referência** para `https://cdn.belvo.io/belvo-widget-1-stable.js`. Caso contrário, o widget não será carregado em seu app! # Gerar um `access_token` > 👍 Personalizando o `access_token` Quando você solicita seu `access_token`, pode passar parâmetros adicionais para personalizar a aparência do seu widget. Para mais informações, consulte nosso Guia de branding e personalização. > ❗️ Solicitação do lado do servidor A solicitação do `access_token` **deve** ser feita do lado do servidor para proteger suas chaves de API (secretId e secretPassword). Portanto, se você estiver usando um framework como Vue ou React, certifique-se de que a solicitação seja gerada do lado do servidor. Para que o widget apareça para seus usuários finais, você precisa gerar um `access_token` no seu lado do servidor e enviá-lo para a Belvo. Assim que recebermos a solicitação, você receberá um objeto com dois elementos: `access` e `refresh`. Passe o valor do elemento `access` para o seu lado do cliente, e você poderá iniciar o widget. Os valores retornados são válidos por **10** minutos e podem ser enviados para o seu frontend para iniciar o Connect Widget. Invalidamos o token assim que seu usuário conecta sua conta com sucesso. Para gerar um `access_token`, basta fazer uma chamada do seu lado do servidor para a Belvo (veja o exemplo abaixo): ```shell curl -X POST \ https://sandbox.belvo.com/api/token/ \ -H 'Content-Type: application/json' \ -H 'Host: sandbox.belvo.com' \ -d 'Veja o exemplo de payload abaixo' ``` ```json { "id": "SECRET_ID", "password": "SECRET_PASSWORD", "scopes": "read_institutions,write_links", "fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS"], "credentials_storage": "store", "stale_in": "300d" } ``` > 📘 Escopos Lembre-se de passar o parâmetro `scopes` ao gerar seu access token, caso contrário, o widget não iniciará corretamente. Esses escopos são necessários para dar as permissões corretas ao token para que o widget funcione. `"scopes": "read_institutions,write_links"` Após fazer sua chamada, a Belvo retorna um objeto do qual você precisará do valor da chave `access`. Você enviará esse valor para o seu lado do cliente para que o widget possa realmente iniciar. ```json { "access": "{access_token_for_widget}", // Você precisará deste valor para enviar para o seu lado do cliente "refresh": "{refresh_token}" } ``` ✳️ OK! Agora que você pode gerar `access_token`, você pode iniciar o widget! # Iniciar o hosted widget Usando este `access_token` você pode agora iniciar o hosted widget: ```javascript // Código a ser incluído dentro da sua tag ``` ## Retorno de chamada de evento Quando os usuários encontram certos eventos no widget, enviaremos alguns dados para explicar o que está acontecendo. O objeto de dados conterá um `eventName`, `request_id` e um objeto `meta_data`. ```json { "data": [ { "eventName": "ERROR", "request_id": "UUID", "meta_data": { "error_code": "login_error", "error_message": "Invalid credentials provided to login to the institution", "institution_name": "bancoazteca_mx_retail", "timestamp": "2020-04-27T19:09:23.918Z" } } ] } ``` ```json { "data": [ { "eventName": "WARNING", "request_id": "UUID", "meta_data": { "warning_code": "institution_disabled", "warning_message": "The institution is temporarily unavailable.", "institution_name": "bancoazteca_mx_retail", "timestamp": "2020-04-27T19:09:23.918Z" } } ] } ``` ```json { "data": [ { "eventName": "PAGE_LOAD", "meta_data": { "page": "/institutions", // Página para a qual o usuário é direcionado "from": "/consent", // Página onde o usuário estava anteriormente "institution_name": "" // Nota: Este campo só aparece DEPOIS que eles selecionaram uma instituição } } ] } ``` **event_name** Uma string que representa o nome do evento que acabou de ocorrer no widget. | Tipo de evento | Descrição | | --- | --- | | `ERROR` | Quando um erro recuperável ocorreu no widget, veja o `error_code` e `error_message` no `meta_data`. | | `WARNING` | Quando um usuário tenta se conectar a uma instituição que está atualmente indisponível. Veja o `warning_code` e `warning_message` no `meta_data` para mais informações. | | `PAGE_LOAD` | Quando um usuário avança para a próxima tela no widget. | **request_id** Uma string usada para identificar exclusivamente o erro. > 🚧 Armazene o request_id Ao implementar sua integração Belvo, certifique-se de considerar o armazenamento do request_id quando você receber um erro. Desta forma, quando você fornecer o ID aos nossos engenheiros, eles poderão solucionar o problema rapidamente e fazer com que você volte a funcionar. **meta_data** Um objeto contendo mais informações sobre o evento que acabou de ocorrer no widget. O objeto `meta_data` pode ter as seguintes propriedades: | Parâmetro | Descrição | | --- | --- | | `error_code` | O código de erro que o usuário encontrou. Veja o retorno de chamada de saída para a lista de possíveis códigos de erro. | | `error_message` | A mensagem de erro que o usuário encontrou. Veja o retorno de chamada de saída para a lista de possíveis mensagens de erro. | | `institution_name` | A instituição selecionada | | `timestamp` | Um timestamp de quando o evento ocorreu | ```html ``` ## Callback de saída Quando os usuários decidirem fechar o widget, enviaremos alguns dados para explicar o que está acontecendo. O objeto de dados conterá um objeto `last_encountered_error` e um objeto `meta_data`. > 👍 Caso de uso no mundo real Monitorar o callback de saída é útil, pois com base no evento, você pode redirecionar seu usuário para uma tela específica após eles fecharem o widget. ```json { "data": [ { "last_encountered_error": { "message": "Invalid credentials provided to login to the institution", "code": "login_error" }, "meta_data": { "institution_name": "erebor_mx_retail", "step": "abandon-survey" } } ] } ``` **last_encountered_error** O objeto `last_encountered_error` é enviado apenas se ocorrer um erro. Veja a tabela abaixo para uma lista de possíveis códigos de erro e suas mensagens. | Código de erro | Mensagem de erro | | --- | --- | | `institution_down` | A instituição financeira está fora do ar, tente novamente mais tarde | | `login_error` | As possíveis mensagens de erro para um login_error são: - Credenciais inválidas fornecidas para login na instituição A conta do usuário está bloqueada, o usuário precisa contatar a instituição para desbloqueá-la O acesso à conta do usuário foi proibido pela instituição Impossível fazer login, algo inesperado aconteceu ao fazer login na instituição. Tente novamente mais tarde. Um token MFA é necessário pela instituição, mas ainda não é suportado pela Belvo. Login não tentado devido a credenciais inválidas Credenciais ausentes para login na instituição | | `too_many_sessions` | Impossível fazer login, uma sessão já está aberta com a instituição para essas credenciais | | `unexpected_error` | A Belvo não consegue processar a solicitação devido a um problema interno do sistema ou a uma resposta não suportada de uma instituição | **meta_data** O objeto `meta_data` é enviado sempre que um usuário sai do widget. Veja a tabela abaixo para uma lista de possíveis valores. | Parâmetro | Descrição | | --- | --- | | `step` | Enviado quando o usuário sai do widget na tela inicial. O valor do parâmetro é sempre `abandon-survey`. | | `institution_name` | Enviado quando o usuário sai do widget após selecionar uma instituição. O valor será o código da instituição da Belvo, por exemplo, `banamex_mx_retail`. | Aqui está um exemplo de uso do onExit: ```html ``` # Use o `link_id` para obter dados Uma vez que seu usuário conecta com sucesso sua conta bancária, você receberá o `link_id` no evento de sucesso. A Belvo então enviará webhooks informando quando a informação estiver pronta para o link. Para mais informações, veja: - Workflows Assíncronos (Links Únicos) - Workflows Assíncronos (Links Recorrentes) br # Modo de atualização do widget Connect O widget Connect pode ser configurado no “modo de atualização” para restaurar um link que parou de funcionar temporariamente porque: - a senha conectada com o Link foi alterada pelo usuário - um novo token MFA é necessário Para mais informações, consulte nosso guia para Atualizar um link usando o widget Connect.