# Visão Geral do Hosted Widget (OFDA) ## Introdução Para aplicativos nativos (mobile) e também web-based, criamos uma versão **hosted** do nosso **widget** que simplifica significativamente o seu processo de desenvolvimento e integração. Tudo o que é necessário é que você crie uma **webview** em seu aplicativo e tenha algum conhecimento sobre como lidar com redirecionamentos de **deeplink**. Esta página fornece documentação de referência sobre quais informações passar ao iniciar seu hosted widget, bem como os possíveis eventos que você pode receber do widget. Este guia orienta você em: 1. Gerar um token de acesso 2. Iniciar o hosted widget 3. Lidar com eventos de callback 4. Recuperar dados Para aplicativos com foco em dispositivos móveis, desenvolvemos um fluxo App2App especializado que melhora a experiência do usuário ao conectar sua conta dentro do seu aplicativo. Para mais detalhes, confira nosso Fluxo App2App do Hosted Widget para OFDA. ## Gerar um token de acesso Para exibir o widget para seus usuários finais, gere um token de `access` no seu servidor e envie-o para a Belvo. Assim que recebermos a solicitação, você receberá um objeto com duas chaves: `access` e `refresh`. Passe o valor da chave `access` ao iniciar o hosted widget. Os valores retornados são válidos por 10 minutos e invalidamos o token assim que um usuário conecta sua conta com sucesso. Para gerar um token de `access`, basta fazer uma chamada do seu lado do servidor para a Belvo: ```shell curl -X POST \ https://sandbox.belvo.com/api/token/ \ -H 'Content-Type: application/json' \ -H 'Host: sandbox.belvo.com' \ -d 'veja exemplos de payloads abaixo' ``` Individual (OFDA) ```json { "id": "YOUR_SECRET_ID", "password": "YOUR_SECRET_PASSWORD", "scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents", "stale_in": "300d", "fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS"], "widget": { "purpose": "Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito.", "openfinance_feature": "consent_link_creation", "callback_urls": { "success": "your_deeplink_here://success", "exit": "your_deeplink_here://exit", "event": "your_deeplink_here://event" }, "consent": { "terms_and_conditions_url": "https://www.your_terms_and_conditions.com", "permissions": ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"], "identification_info": [ { "type": "CPF", "number": "76109277673", "name": "Ralph Bragg" } ] } } } ``` Business (OFDA) ```json { "id": "YOUR_SECRET_ID", "password": "YOUR_SECRET_PASSWORD", "scopes": "read_institutions,write_links,read_consents,write_consents,write_consent_callback,delete_consents", "stale_in": "300d", "fetch_resources": ["ACCOUNTS", "TRANSACTIONS", "OWNERS"], "widget": { "purpose": "Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito.", "openfinance_feature": "consent_link_creation", "callback_urls": { "success": "your_deeplink_here://success", "exit": "your_deeplink_here://exit", "event": "your_deeplink_here://event" }, "consent": { "terms_and_conditions_url": "https://www.belvo.com", "permissions": ["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"], "identification_info": [ { "type": "CPF", "number": "76109277673", "name": "Ralph Bragg" }, { "type": "CNPJ", "number": "50685362006773", "name": "Belvo OF test" } ] } } } ``` ```json Exemplo de Resposta do Token de Acesso { "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjMzNDY1MDY5MiwiaWF0IjoxNzEyNTcwNjkyLCJqdGkiOiIxMDAxMTg4NDU4Y2M0ZTlhOThmMDA4MmU3MDU...", "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEyNTcxODkyLCJpYXQiOjE3MTI1NzA2OTIsImp0aSI6ImFiNjRmYjkyZmY1ZjQ0MTU4N2IwM2Y2MDJhMzhh..." // [!code highlight] } ``` ### Parâmetros configuráveis Além dos parâmetros configuráveis abaixo, você também pode adicionar personalização e branding adicionais ao seu widget ao gerar seu token de `access`. Para mais informações, consulte nosso guia dedicado de Branding e personalização (OFDA). #### stale_in Você pode indicar por quanto tempo qualquer dado deve ser armazenado no banco de dados da Belvo para o link (tanto único quanto recorrente). Por exemplo, se você enviar `90d`, a Belvo removerá qualquer dado de seu banco de dados relacionado ao usuário após 90 dias (ou seja, 90 dias após a última vez que a informação foi recuperada para o usuário). Por padrão, a Belvo armazena dados do usuário por 365 dias, a menos que o link seja excluído. #### fetch_resources Para usar `fetch_resources` para links únicos ou recorrentes, você deve ter habilitado uma URL de webhook no dashboard. Para links únicos e recorrentes, você pode definir quais recursos a Belvo irá recuperar informações históricas de forma assíncrona usando o parâmetro `fetch_resources`. Para mais informações, veja nossa documentação Fluxo de trabalho de dados históricos assíncronos (links únicos). | Recurso | Tipo de Instituição | | --- | --- | | `ACCOUNTS` | Banking Brazil | | `OWNERS` | Banking Brazil | | `TRANSACTIONS` | Banking Brazil | | `BILLS` | Banking Brazil | | `INVESTMENTS` | Banking Brazil | | `INVESTMENT_TRANSACTIONS` | Banking Brazil | #### purpose No objeto `consent`, você pode personalizar a mensagem que é exibida ao seu usuário sobre para qual caso de uso você está solicitando os dados deles no campo `purpose`. Por padrão, o widget exibe a seguinte mensagem: *Soluções financeiras personalizadas oferecidas por meio de recomendações sob medida, visando melhores ofertas de produtos financeiros e de crédito.*. Para alterar o conteúdo, basta adicionar seu texto (máximo de 600 caracteres) ao campo `purpose`: ```json Consent Purpose { "widget": { "consent": { "purpose": "Seu texto personalizado aqui. Máximo de 600 caracteres", ... } } } ``` #### callback_urls No objeto `widget`, você precisa adicionar o objeto `callback_urls` com as seguintes informações: - `success` é o URL deeplink para o qual seu usuário é redirecionado quando o fluxo é bem-sucedido. - `exit` é o URL deeplink para o qual seu usuário é redirecionado quando sai do widget antes de completar o fluxo. - `event` é o URL deeplink para o qual seu usuário é redirecionado quando ocorre um erro. #### terms_and_conditions_url No objeto `consent`, você precisa adicionar um link para os termos e condições da sua empresa usando o parâmetro `terms_and_conditions_url`. #### permissions No objeto `consent`, enviamos uma lista padrão de recursos para recuperar para o usuário usando o parâmetro `permissions`. O valor de `permissions` deve ser sempre o seguinte array de itens: `["REGISTER", "ACCOUNTS", "CREDIT_CARDS", "CREDIT_OPERATIONS"]`. > 🚧 Alterando Permissões de Consentimento Se você precisar alterar as permissões de consentimento padrão, por favor, entre em contato com nossa [equipe de suporte](https://support.belvo.com/hc/en-us/requests/new). #### identification_info No objeto `consent`, você precisa fornecer as informações de identificação do usuário para o qual deseja recuperar informações no parâmetro `identification_info`. As informações que você fornecer aqui devem corresponder às informações que a instituição regulamentada possui para o usuário (por exemplo, para empresas, o CPF e o nome devem ser de um usuário com acesso à conta empresarial). Por exemplo: Individual (OFDA) ```json Individual (OFDA) Identification Info { "consent": { "identification_info": [ { "type": "CPF", "number": "76109277673", "name": "Ralph Bragg" } ] } } ``` Business (OFDA) ```json Business (OFDA) Identification Info { "consent": { "identification_info": [ { "type": "CPF", "number": "76109277673", "name": "Ralph Bragg" }, { "type": "CNPJ", "number": "50685362006773", "name": "Belvo OF test" } ] } } ``` OK! Agora que você pode gerar um token de `access`, você pode iniciar o widget! ## Iniciar o Widget Quando você inicia seu hosted widget, na string da URL você precisa passar seu: - token de `access` gerado - definir `locale` como `pt` Por exemplo: ```text Exemplo de URL do Hosted Widget https://widget.belvo.io/?access_token={access_code}&locale=pt ``` Você também pode passar parâmetros de configuração adicionais, como o tipo de link que deseja criar (`access_mode`), ou quais instituições exibir com base nos recursos que você pode extrair delas (`resources`), na URL. Para uma lista completa de parâmetros (junto com detalhes de implementação), consulte nosso artigo de Configuração de Inicialização (OFDA) do widget. Por exemplo: ```text Exemplo de Query String de Inicialização https://widget.belvo.io/ ?access_token={access_code} &locale=pt &integration_type=openfinance &institution_types=retail &institutions=ofbradesco_br_retail &country_codes=BR &access_mode=recurrent &external_id=HJLSI-897809 &resources=OWNERS,ACCOUNTS ``` ## Lidando com eventos de callback O hosted widget utiliza redirecionamentos de deep link para passar informações sobre o que acontece no widget. Você precisará ser capaz de lidar com eventos de **sucesso**, **saída** e **erro**. A estrutura do deep link é: ```text Exemplo de Estrutura de Deeplink your-url-here://event_name?parameters ``` | Parâmetro | Descrição | | --- | --- | | `your-url-here` | Seu manipulador de deeplink (esquema) | | `event_name` | O nome do evento (host) | | `parameters` | Os parâmetros do evento (enviados como query strings) | ### Guias da plataforma Para ajudar no seu desenvolvimento, criamos guias sobre como configurar deep links e escutar eventos para as seguintes plataformas: - iOS (Swift) - Android (Kotlin) - React Native ### Evento de sucesso Você receberá um evento `success` quando seu usuário tiver conectado com sucesso sua conta à instituição usando o widget. Ser capaz de lidar com o evento `success` é crítico, pois ele contém o `id` do link do usuário (necessário para posteriormente recuperar dados da API da Belvo). ```text Exemplo de Evento de Sucesso your-url-here://success ?link={id}} &institution={institution_name} your-url-here://success ?link=cb65f82c-dc93-4d3e-8270-9a27528397f5 &institution=erebor_br_retail ``` | Parâmetro | Descrição | Exemplo | | --- | --- | --- | | `link` | O ID do link (UUID) para o usuário. Você precisará deste ID para poder fazer solicitações adicionais para o usuário. | `cb65f82c-dc93-4d3e-8270-9a27528397f5` | | `institution` | A instituição com a qual o link foi criado. | `erebor_br_retail` | ### Evento de saída Você receberá um evento `exit` quando o seu usuário final sair do widget: - antes de conectar a conta. - após selecionar uma instituição. - devido a um erro. ```text Exemplo de Evento de Saída your-url-here://exit ?last_encountered_error_code={error_code} &last_encountered_error_message={error_message} &meta_data_institution_name={institution_name} &meta_data_step=abandon-{step_name} your-url-here://exit ?last_encountered_error_code=login_error &last_encountered_error_message=Invalid%20credentials%20provided%20to%20login%20to%20the%20institution &meta_data_institution_name=amex_mx_retail &meta_data_step=abandon-survey ``` #### last_encountered_error A query string `last_encountered_error` é enviada apenas se ocorrer um erro. Veja a tabela abaixo para uma lista completa 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 tentar acessar a instituição. Tente novamente mais tarde. | | `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 A query string `meta_data` é enviada sempre que um usuário sai do widget. Veja a tabela abaixo para uma lista de possíveis valores. | Parâmetro | Descrição | Exemplo | | --- | --- | --- | | `step` | Enviado quando o usuário sai do widget na tela inicial. O valor do parâmetro é sempre `abandon-survey`. | `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. | `ofmockbank_br_retail`. | ### Evento de erro Você receberá um evento `error` sempre que ocorrer um erro durante o uso do widget. ```text Exemplo de Evento de Erro your-url-here://error ?error={error_name} &error_message={error_message} your-url-here://error ?error=ACCESS_TOKEN_NOT_VALID &error_message=The%20access%20token%20was%20not%20provided%20or%20is%20not%20valid ``` Veja a tabela abaixo para uma lista de possíveis códigos de erro e suas mensagens. | Código de erro | Mensagem de erro (URL-Encoded) | | --- | --- | | `ACCESS_TOKEN_NOT_VALID` | The access token was not provided or is not valid | ### Evento de aviso Você receberá um evento `warning` sempre que ocorrer um evento não terminal durante o uso do widget. ```text Exemplo de Evento de Aviso your-url-here://warning ?warning={warning_code} &warning_message={warning_message} your-url-here://warning ?warning=institution_disabled &warning_message=The%20institution%20is%20temporarily%20unavailable. ``` Veja a tabela abaixo para uma lista de possíveis códigos de aviso e suas mensagens. | Código de aviso | Mensagem de aviso (URL-Encoded) | | --- | --- | | `institution_disabled` | The institution is temporarily unavailable. | br Agora que você pode lidar com deep links e recuperar o `id` do link a partir do evento `success`, você pode começar a recuperar dados sobre seu usuário. ## Recuperando 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)