Extrair Dados Bancários no Brasil (Widget)

Neste guia, vamos orientá-lo em tudo o que você precisa para extrair dados bancários sobre seus usuários da Rede de Open Finance do Brasil usando nossa API. Isso inclui:

• Uma visão geral do fluxo de dados
• Configuração do Hosted Widget da Belvo para conectar seus usuários.
• Obtenção dos dados do seu usuário com base em eventos de webhook enviados pela Belvo.
• Fornecer aos seus usuários uma maneira de gerenciar seus consentimentos.

Pré-requisitos

Antes de prosseguir com sua integração, certifique-se de que você leu nosso guia de introdução. No guia de introdução, você criará uma conta Belvo, gerará algumas chaves de API sandbox e configurará uma URL de webhook. Para fins de teste e desenvolvimento de sua integração, recomendamos fortemente o uso do ambiente Sandbox sempre que possível.

Além disso, para fins de teste e desenvolvimento da sua integração, recomendamos fortemente o uso do ambiente Sandbox junto com a instituição Mockbank. Você pode encontrar credenciais de exemplo para simular diferentes usuários para a instituição Mockbank aqui.

Visão geral do fluxo de dados

A Belvo utiliza um fluxo de trabalho assíncrono para melhorar a extração de dados e o seu fluxo. Como você pode ver no diagrama abaixo, uma vez que o usuário tenha conectado sua conta usando o Hosted Widget e o link seja criado, a Belvo carrega todos os dados de forma assíncrona e, em seguida, notifica você usando webhooks que os dados estão disponíveis para você recuperar.

Configurando o Hosted Widget

Nosso Hosted Widget pode ser incorporado em seu aplicativo como um webview e guiará seu usuário por todas as etapas para conceder seu consentimento para que você acesse seus dados. Isso inclui redirecionar o usuário para sua instituição para fornecer consentimento e, em seguida, de volta para o seu aplicativo. Você pode ver um fluxo simplificado do que acontece durante o processo de conexão do widget no diagrama abaixo:

Basicamente, sempre que você quiser que seu usuário conecte sua conta de uma instituição financeira no Brasil, você precisará:

Gerar um token de access do widget

Para poder iniciar o widget, você precisará primeiro gerar um token de access usando o seguinte payload:

curl -X POST \
  https://sandbox.belvo.com/api/token/ \
  -H 'Content-Type: application/json' \
  -d 'veja o exemplo de payload abaixo'

{
  "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", "BILLS", "INVESTMENTS", "INVESTMENT_TRANSACTIONS"],
  "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-url-here://success",
      "exit": "your-url-here://exit",
      "event": "your-url-here://error"
    },
    "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"
        }
      ]
    },
    "branding": {
      "company_icon": "https://mysite.com/icon.svg",
      "company_logo": "https://mysite.com/logo.svg",
      "company_name": "ACME",
      "company_terms_url": "https://belvo.com/terms-service/",
      "overlay_background_color": "#F0F2F4",
      "social_proof": true,
    },
    "theme": []
  }
}

Além disso, confira nossa seção Generating an access_token do nosso guia de Hosted Widget (OFDA).

{
    "refresh": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MjMzNDY1MDY5MiwiaWF0IjoxNzEyNTcwNjkyLCJqdGkiOiIxMDAxMTg4NDU4Y2M0ZTlhOThmMDA4MmU3MDU...",
    "access": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEyNTcxODkyLCJpYXQiOjE3MTI1NzA2OTIsImp0aSI6ImFiNjRmYjkyZmY1ZjQ0MTU4N2IwM2Y2MDJhMzhh..."
}

Iniciar o widget dentro de uma webview

Em seguida, você precisará redirecionar seu usuário para o widget em uma webview dentro do seu aplicativo:

https://widget.belvo.io/
	?access_token={access}
  &mode=webapp
  &locale=pt
  &access_mode=single
  &external_id=HJLSI-897809

Além disso, confira nossa seção Iniciando o widget do nosso guia de Hosted Widget (OFDA).

Ouça o evento de sucesso que incluirá o id do link.

Assim que seu usuário terminar o fluxo do widget, enviaremos um evento de success para a URL que você forneceu ao gerar o token de access do widget. Este evento incluirá o id do link que você precisará associar ao seu external_id no seu banco de dados.

Para ajudar no seu desenvolvimento, criamos guias sobre como configurar deep links e ouvir eventos para as seguintes plataformas:

• iOS (Swift)
• Android (Kotlin)
• React Native

Aguarde pelos webhooks e recupere dados

Como a Belvo utiliza um fluxo de trabalho assíncrono, uma vez que o link é criado, nós automaticamente recuperamos os últimos 12 meses de dados históricos para o usuário que acabou de conectar sua conta. Nós notificamos você via eventos de webhook assim que os dados são extraídos e você pode recuperá-los. Para mais detalhes, veja a seção Obtendo Dados.

Obtendo Dados

Independentemente de você usar links únicos ou recorrentes, uma vez que seu usuário completa o fluxo do widget com sucesso, a Belvo recupera de forma assíncrona os últimos 12 meses de dados de proprietário, conta, transação, fatura e investimento para o link (atualizações históricas). Assim que extraímos os dados, notificamos você usando um webhook que a informação está pronta para ser recuperada.

Se você estiver usando links recorrentes, a Belvo recuperará as informações atualizadas para o link de acordo com sua taxa de atualização (atualizações recorrentes). Assim como nas atualizações históricas, notificamos você usando um webhook que a nova informação está pronta para ser recuperada.

A Rede de Open Finance do Brasil estabelece limites mensais sobre a frequência com que você pode recuperar dados para uma pessoa ou empresa específica. Esses limites operacionais estão vinculados a uma combinação de:

• o CPF ou CNPJ do usuário
• os dados da API que você deseja obter (Proprietário, Conta, Transação ou Fatura)
• o certificado da rede de Open Finance

Uma vez que o limite operacional mensal de chamadas de API é atingido, nenhuma informação adicional pode ser recuperada para o CPF/CNPJ até o início do próximo mês calendário. No entanto, a Belvo implementou otimizações para maximizar a quantidade de dados que você pode recuperar para seus usuários de acordo com suas necessidades de dados. Para mais informações, consulte nosso artigo dedicado Limites da Rede de Open Finance (Brasil).

Atualizações históricas

Abaixo você pode ver o fluxo de dados para links únicos e recorrentes assim que um link é criado:

Cada vez que você receber um webhook para um determinado recurso (owners, accounts, transactions, ou bills), você precisará fazer uma chamada GET para esse endpoint, usando o link ID, para recuperar as informações.

Obter informações do proprietário

A Belvo irá recuperar de forma assíncrona os dados do proprietário dos últimos 12 meses para o seu link e, em seguida, enviará um webhook quando a informação estiver pronta para ser recuperada (veja o exemplo de webhook abaixo):

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "OWNERS", 
  "process_type": "historical_update", 
  "webhook_code": "historical_update",
  "link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", 
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_owners": 2 // Número total de proprietários
  }
}

Assim que você receber o webhook, basta fazer a seguinte solicitação GET Owners para recuperar os dados do link fornecido:

curl --request GET 'https://api.belvo.com/api/owners/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Obter informações da Conta

A Belvo irá recuperar de forma assíncrona os últimos 12 meses de dados da conta para o seu link e, em seguida, enviará um webhook assim que a informação estiver pronta para ser recuperada (veja o exemplo de webhook abaixo):

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "ACCOUNTS", 
  "process_type": "historical_update", 
  "webhook_code": "historical_update",
  "link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", 
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_accounts": 5 // Número total de contas encontradas.
  }
}

Assim que você receber o webhook, você só precisa fazer a seguinte solicitação GET Accounts para recuperar os dados para o link fornecido:

curl --request GET 'https://api.belvo.com/api/accounts/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Obter informações de Transação

A Belvo irá recuperar de forma assíncrona os dados de transação dos últimos 12 meses para o seu link e, em seguida, enviará um webhook assim que a informação estiver pronta para ser recuperada (veja o exemplo de webhook abaixo):

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "TRANSACTIONS", 
  "process_type": "historical_update", 
  "webhook_code": "historical_update",
  "link_id": "2f8ca7a1-c28f-46f2-bb41-21633099a280", 
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_transactions": 19, // Número total de transações encontradas
    "total_inflow_transactions": 10, // Número total de transações de entrada
    "total_outflow_transactions": 9, // Número total de transações de saída
    "first_transaction_date": "2017-01-03", // Data da primeira transação
    "last_transaction_date": "2020-03-25" // Data da última transação
  }
}

Assim que você receber o webhook, você só precisa fazer a seguinte solicitação GET Transactions para recuperar os dados para o link fornecido:

curl --request GET 'https://api.belvo.com/api/transactions/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Obter informações da Fatura

A Belvo irá recuperar de forma assíncrona os dados das faturas dos últimos 12 meses para o seu link e, em seguida, enviará um webhook assim que a informação estiver pronta para ser recuperada (veja o exemplo de webhook abaixo):

{
  "webhook_id": "aadf41a1fc8e4f79a49f7f04027ac999",
  "webhook_type": "BILLS", 
  "process_type": "historical_update", 
  "webhook_code": "historical_update",
  "link_id": "16f68516-bcbc-4cf7-b815-c500d4204e28", 
  "request_id": "4363b08b-51eb-4350-9c74-5df5ac92a7f6",
  "external_id": "your_external_id",
  "data": {
    "total_bills": 2 // Número total de faturas
  }
}

Assim que você receber o webhook, basta fazer a seguinte solicitação GET Bills para recuperar os dados do link fornecido:

curl --request GET 'https://api.belvo.com/api/bills/?link={id}' \
-u [Secret Key ID]:[Secret Key PASSWORD]

Atualizações recorrentes

Se você estiver usando links recorrentes, receberá eventos de webhook de acordo com a frequência que você estabeleceu com a Belvo (diariamente, semanalmente, mensalmente, etc.). A Belvo envia os seguintes eventos de webhook para atualizações:

• new_owners_available
  Você receberá um webhook new_owners_available sempre que detectarmos que houve uma mudança nos detalhes dos proprietários das contas. Para mais informações, consulte nosso artigo dedicado ao webhook de Owners (Aggregation).
• new_accounts_available
  Você receberá um webhook new_accounts_available sempre que detectarmos que houve uma mudança nas contas que o link possui. Para mais informações, consulte nosso artigo dedicado ao webhook de Accounts (Aggregation).
• new_transactions_available
  Você receberá um webhook new_transactions_available sempre que detectarmos que novas transações ocorreram para qualquer conta que o link possui. Para mais informações, consulte nosso artigo dedicado ao webhook de Transactions (Aggregation).
• new_bills_available
  Você receberá um webhook new_bills_available sempre que um novo extrato de fatura de cartão de crédito for gerado para um período de faturamento. Para mais informações, consulte nosso artigo dedicado ao webhook de Bills (Aggregation).

Assim que você receber um webhook sobre informações recém-atualizadas, você só precisa fazer a mesma chamada GET que fez para a atualização histórica para receber as informações atualizadas.

# Recuperar dados do proprietário
curl --request GET 'https://api.belvo.com/api/owners/?link={id}'

# Recuperar dados da conta
curl --request GET 'https://api.belvo.com/api/accounts/?link={id}'

# Recuperar dados da transação
curl --request GET 'https://api.belvo.com/api/transactions/?link={id}'

# Recuperar dados da fatura
curl --request GET 'https://api.belvo.com/api/bills/?link={id}'

Outros eventos de webhook

A Belvo também notifica você quando há alterações no consentimento do seu link. Você pode receber os seguintes webhooks relacionados a consentimentos:

• openfinance_consent_expired
• openfinance_consent_with_unrecoverable_resources
• openfinance_consent_with_temporarily_unavailable_resources

Para os eventos openfinance_consent_expired, você pode solicitar ao seu usuário que renove seu consentimento usando o My Belvo Portal. Para mais informações, consulte nosso artigo dedicado sobre webhook de Consentimento.

Adicionando um link ao Meu Portal Belvo

A Belvo criou o Meu Portal Belvo (MBP) que permite aos usuários gerenciar seus consentimentos de forma simples e direta, atendendo a todos os requisitos das regulamentações.

No seu aplicativo, você deve incluir um link claramente visível para o MBP para que seus usuários possam gerenciar seus consentimentos.

O MBP pode ser configurado de três maneiras diferentes:

• MBP Público
  No site da Belvo, hospedamos uma instância universal do MBP que qualquer usuário pode usar para gerenciar seus consentimentos. Esta instância consolida todos os consentimentos que eles concederam usando o produto OFDA da Belvo. Você simplesmente precisa redirecionar seu usuário para https://meuportal.belvo.com/?mode=landing, onde eles podem inserir seus dados. Seu usuário poderá ver todos os consentimentos que concederam usando a Belvo (incluindo outras aplicações que usam a Belvo para extrair dados da Rede de Open Finance do Brasil).
• MBP Personalizado
  Você pode personalizar o MBP para exibir apenas os consentimentos que seu usuário concedeu à sua aplicação, facilitando o gerenciamento dos consentimentos.
• Modo de Renovação de Consentimento
  O MBP também pode ser usado para renovar um consentimento expirado. A Belvo enviará um webhook quando o consentimento de um dos seus usuários expirar.

Recursos adicionais

Lista de verificação de integração

Criamos uma lista de verificação dedicada a todas as coisas que você deve levar em consideração ao desenvolver sua integração OFDA. Confira aqui: Lista de Verificação de Integração OFDA.

Erros da Open Finance Network

Durante o processo de criação de consentimento, as instituições na Open Finance Network realizam verificações para garantir que a conexão seja estável e segura. Se a instituição determinar que a conexão não é estável ou segura, ela redirecionará o usuário para uma página de erro personalizada com o seguinte conteúdo:

Ocorreu um error. Por favor, verifique o seu CPF ou CNPJ para ter certeza de que está correto, feche o aplicativo e reinicie o processo para conectar sua conta.

E na URL de redirecionamento, você verá um fragmento de URL com os seguintes detalhes:

api.belvo.com/api/consents/callback/#error_description=risk_analysis_denied...

Este erro pode ocorrer pelos seguintes motivos:

• Seu usuário tem uma conexão VPN ativa em seu dispositivo. Recomendamos desligar a VPN e tentar novamente.
• Seu usuário está acessando sua instituição através do aplicativo em seu dispositivo móvel, no entanto, não é a versão mais recente do aplicativo. Algumas instituições exigem que a versão do aplicativo seja a mais recente possível para permitir a autorização de consentimento. Recomendamos atualizar o aplicativo da instituição para a versão mais recente disponível e tentar novamente.
• [Itaú somente] Seu usuário está acessando sua instituição em seu computador desktop, no entanto, ele não tem o aplicativo Guardião 30 horas do Itaú instalado em seu computador. O Itaú exige que os usuários tenham este aplicativo instalado em seu computador desktop para realizar o processo de consentimento.