# Visão Geral do Hosted Widget (OFDA) ## Introdução Para aplicativos nativos móveis, criamos uma versão hosted do nosso widget que simplifica significativamente o seu processo de desenvolvimento e integração. Tudo o que é necessário é criar uma webview em seu aplicativo e algum conhecimento sobre como lidar com redirecionamentos 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. Manipular eventos de callback 4. Recuperar dados Para aplicativos nativos móveis, desenvolvemos um fluxo App2App especializado que melhora a experiência do usuário quando ele está conectando 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, você deve ter habilitado uma URL de webhook no dashboard. Para links únicos, você pode definir quais recursos a Belvo irá recuperar de forma assíncrona informações históricas usando o parâmetro `fetch_resources`. Para mais informações, veja nossa documentação de Fluxo de trabalho assíncrono de dados históricos (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ê iniciar seu hosted widget, na string da URL você precisa passar seu: - token de `access` gerado - definir `locale` como `pt` - definir `mode` como `webapp` Por exemplo: ```curl Exemplo de URL do Hosted Widget https://widget.belvo.io/?access_token={access_code}&locale=pt&mode=webapp ``` 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 String de Consulta de Inicialização https://widget.belvo.io/ ?access_token={access_code} &locale=pt &mode=webapp &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 **success**, **exit** e **error**. A estrutura do deep link é: ### 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 à sua 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 Belvo). | Parâmetro | Descrição | | --- | --- | | `link` | O ID do link para o usuário. Você precisará deste ID para poder fazer solicitações adicionais para o usuário. | | `institution` | A instituição com a qual o link foi criado. | ```curl Evento de Sucesso your-url-here://success ?link=cb65f82c-dc93-4d3e-8270-9a27528397f5 &institution=erebor_br_retail ``` ### Evento de saída Você receberá um evento `exit` quando seu usuário final sair do widget: - antes de conectar sua conta. - após selecionar uma instituição. - devido a um erro. br #### last_encountered_error A string de consulta `last_encountered_error` é enviada apenas se um erro ocorrer. 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 fazer login na 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` | 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 string de consulta `meta_data` é enviada sempre que um usuário sai do widget. Veja a tabela abaixo para uma lista de valores possíveis. | 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`. | ```text Exemplo de Evento de Saída 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 ``` ### Evento de erro Você receberá um evento `error` sempre que ocorrer um erro durante o uso do widget. Veja a tabela abaixo para uma lista de possíveis códigos de erro e suas mensagens. | Código de erro | Mensagem de erro | | --- | --- | | `ACCESS_TOKEN_NOT_VALID` | O token de acesso não foi fornecido ou não é válido | ```text Exemplo de Evento de Erro your-url-here://error ?error=ACCESS_TOKEN_NOT_VALID &error_message=The%20access%20token%20was%20not%20provided%20or%20is%20not%20valid ``` br ### Evento de aviso Você receberá um evento `warning` sempre que ocorrer um evento não terminal durante o uso do widget. Veja a tabela abaixo para uma lista de possíveis códigos de aviso e suas mensagens. | Código de aviso | Mensagem de aviso | | --- | --- | | `institution_disabled` | A instituição está temporariamente indisponível. | ```text Exemplo de Evento de Aviso your-url-here://warning ?warning=institution_disabled &warning_message=A%20institui%C3%A7%C3%A3o%20est%C3%A1%20temporariamente%20indispon%C3%ADvel. ``` br Agora que você pode lidar com deep links e recuperar o `id` do link 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)