Introdução

Sempre que um usuário se conecta à sua instituição usando a API da Belvo, criamos um Link. Um Link é um conjunto de credenciais criptografadas, por exemplo, o username e senha, que está associado ao usuário. Você sempre precisará primeiro registrar um Link antes de poder acessar informações específicas para aquele usuário final.

Links recorrentes

Com links recorrentes, a Belvo atualiza automaticamente as informações semanalmente e notifica você via <a href="../../developer_resources/resources-webhooks-aggregation target="_blank">webhook para que você sempre tenha dados atualizados. Então, quando você receber o webhook, pode usar requisições GET para os endpoints de Lista ou Detalhe para acessar instantaneamente informações atualizadas, sem precisar se conectar à instituição.

Quando você cria um link recorrente, a Belvo recupera automaticamente informações chave sobre o Link ID. Assim que tivermos as informações, enviaremos um evento de webhook histórico indicando que você pode fazer uma requisição GET para essas informações.

Recomendamos que você não faça chamadas POST imediatamente após um link ser criado. Em vez disso, aguarde um webhook de atualização histórica que indica que a Belvo coletou os dados e então você pode fazer uma requisição GET para recuperar as informações (o webhook é enviado logo após um link ser criado). Se você fizer uma requisição GET antes de receber um webhook histórico, receberá respostas com campos de dados vazios ou informações duplicadas.

Taxas de atualização

Por padrão, os links recorrentes são atualizados automaticamente uma vez a cada sete dias. No entanto, você pode alterar a frequência de atualização dos seus links recorrentes para:

• 6 horas (quatro vezes por dia)
• 12 horas (duas vezes por dia)
• 24 horas (uma vez por dia)
• 30 dias (uma vez por mês)
  Nota: com a taxa de atualização de 30 dias, distribuímos as atualizações de links entre o dia 1 e o dia 20 do mês em questão. A data de atualização para cada link recorrente mensal é inicialmente atribuída aleatoriamente entre o dia 1 e o dia 20 do mês. Se as atualizações de links seguintes forem bem-sucedidas, as atualizações subsequentes para este link ocorrerão no mesmo dia de cada mês. Os links não são programados para serem atualizados após o dia 20 do mês para reservar algum tempo para possíveis novas tentativas. Para mais informações, confira nosso artigo do Centro de Ajuda sobre Links recorrentes mensais.

Com links recorrentes, atualizamos as seguintes informações de acordo com a frequência escolhida:

Single links

Single links são usados para realizar acesso ad hoc a dados de contas, proprietários, transações, e assim por diante. Por exemplo, você pode usá-lo quando quiser fazer um processo de subscrição para avaliar o risco antes de emprestar dinheiro.

Para single links, você precisa passar o parâmetro fetch_resources ao criar e então escutar por webhooks assim que os dados históricos tiverem sido extraídos de forma assíncrona.

Link Statuses

Um link pode ter diferentes status, que refletem se o link está operacional ou se é necessária uma ação para restaurar o link.

Verificando o status de um link

Você pode encontrar o status de um link fazendo uma das seguintes consultas e verificando o valor do campo status na resposta JSON:

Liste todos os links atuais

Use o método List all links para obter todos os links aos quais você atualmente tem acesso. Você pode realizar filtragens nas respostas para retornar apenas os links que têm um determinado status. No exemplo abaixo, filtramos a resposta para ter apenas links inválidos.

# Filtrar por links inválidos
curl --request POST 'https://sandbox.belvo.com/api/links/?page_size=1000&status=invalid'\
  -u [Secret Key ID]:[Secret Key PASSWORD]

# Obter a lista completa de links
curl --request POST 'https://sandbox.belvo.com/api/links/?page_size=1000'\
  -u [Secret Key ID]:[Secret Key PASSWORD]

Se você quiser saber mais sobre como aplicar filtros em suas consultas, veja nosso artigo Filtrando respostas.

Obter detalhes de um link específico

Use o método Obter detalhes de um link para obter os detalhes de um link específico.

curl --request GET 'https://sandbox.belvo.com/api/links/{id}' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Onde:

• {id} é o ID do link. Por exemplo: c70a25d4-d8ad-9999-b59e-b8f57f0e7123.

Melhores Práticas para Criação de Links

Ao configurar o fluxo de criação de links:

1. Certifique-se de primeiro registrar seus usuários na sua plataforma.
2. Use o Connect Widget para criar seus links.
3. Armazene o link_id recebido no seu banco de dados.

Links órfãos

Um link órfão é um link que foi criado, mas não foi associado a um usuário no seu banco de dados.

Links órfãos podem ocorrer quando:

• você não registra seu usuário primeiro na sua plataforma.
• seu usuário fecha seu aplicativo (móvel ou navegador) durante um processo de conexão bem-sucedido.

Para recuperar links órfãos criados devido ao usuário fechar seu aplicativo, recomendamos usar o parâmetro external_id como um identificador adicional para seu link no banco de dados da Belvo.

Adicionando seu próprio identificador

Você pode usar o parâmetro opcional external_id ao criar um novo link para fornecer um identificador único adicional dentro do sistema Belvo. Isso é particularmente útil, pois você pode posteriormente fazer uma solicitação ao endpoint de Links da Belvo e filtrar todos os links associados a um external_id.

Ao usar external_id e filtragem, você pode:

• listar todos os links relacionados a um usuário.
• obter o status mais recente de cada link e, se necessário, solicitar ao usuário que atualize seu token ou suas credenciais para uma instituição.
• identificar quaisquer links órfãos para esse usuário e, em seguida, associar o link_id no seu banco de dados.

O external_id que você fornecer:

• deve ser um ID único para cada usuário no seu banco de dados.
• deve ter pelo menos três caracteres.
• pode ser composto apenas por letras, números, hífens (-) e sublinhados (_).
• não pode conter nenhuma informação pessoalmente identificável sobre o usuário (e-mail, nome, número de telefone, número de cartão de crédito, etc.).

Dicas para usar external_id

Para usar o parâmetro opcional external_id, recomendamos fortemente o seguinte fluxo:

1. Registre seus usuários primeiro na sua plataforma e crie um ID único para esse usuário no seu banco de dados.
2. Use o ID único como o valor do parâmetro external_id ao criar um link.
3. Use o Connect Widget para criar seus links.

Então, conforme necessário, você pode periodicamente chamar /links/?external_id={ID único do usuário no seu sistema} e identificar quaisquer links órfãos ou links que precisam ter seu status atualizado.

Evitando links duplicados

Links duplicados ocorrem quando:

• o usuário tenta conectar sua conta à mesma instituição com as mesmas credenciais uma segunda vez.
• você não está armazenando o link_id no seu banco de dados.
• o usuário fecha seu aplicativo (móvel ou navegador) durante um processo de conexão bem-sucedido.

Para ajudá-lo a evitar a duplicação de links, confira nossas dicas úteis abaixo.

Dica #1 - Registre seus usuários primeiro
Certifique-se de registrar seu usuário na sua plataforma primeiro. Desta forma, você sempre terá uma maneira de associar links criados a um usuário no seu banco de dados e acompanhar quais contas eles já conectaram.

Dica #2 - Use external_id

Quando seu usuário inicia uma nova sessão na sua plataforma:

1. Solicite todos os links associados ao usuário: /links/?external_id={ID único do usuário no seu sistema}.

2. Associe quaisquer links órfãos que tenham status=valid ao seu usuário no seu banco de dados e informe ao seu usuário que o link foi criado com sucesso.

Se o status do link não for valid, você pode:

• deletar o link e solicitar que o usuário conecte sua conta novamente.
• atualizar o status do link usando Modo de Atualização do Widget.

Dessa forma, você garantirá que não terá links órfãos e que todos os links associados a um usuário tenham um status valid.

Dica #3 - Use os metadados de callback do widget

Após receber o Callback de Sucesso do widget, você pode usar o ID do link para recuperar informações sobre o link. As informações do link podem então ser comparadas aos links existentes que este usuário já criou no seu banco de dados (Dicas #1 e #2) e utilizar isso para detectar possíveis duplicatas. Por exemplo, você pode comparar uma combinação do institution_id da conta, name da conta e number da conta para determinar se seu usuário já vinculou uma conta ao seu aplicativo.

Dica #4 - Mostre contas já conectadas

Antes de seus usuários abrirem o widget, na sua interface, exiba uma lista de contas que eles já conectaram (para encontrar todas as contas que eles têm, você pode usar o external_id em combinação com os metadados que você recebe do Widget na Dica #3). Ao mostrar essa informação, seus usuários evitarão vincular a mesma conta novamente (e você evita Links duplicados).

Dica #5 - Use institution_user_id para acompanhar os links

Quando seu usuário conecta sua conta, retornamos o institution_user_id, que é uma string única de 44 caracteres que pode ser usada para identificar um usuário em uma determinada instituição. Você pode usar esse identificador para comparar no seu banco de dados se seu usuário já conectou essa conta anteriormente, e se você quiser evitar links duplicados, pode optar por substituir o link.id existente no seu banco de dados.

Exemplo:

1. Seu usuário conecta sua conta a uma instituição e você recebe o seguinte id de link e institution_user_id:

{
	"id": "link-id-1",
	"institution_user_id": "ooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c="
}

2. Seu usuário conecta a mesma conta novamente usando as mesmas credenciais e você recebe:

{
	"id": "link-id-2",
	"institution_user_id": "ooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c="
}

3. Comparando o institution_user_id no seu banco de dados, você vê que esta é a mesma conta. Se você preferir não ter links duplicados no seu banco de dados, pode substituir o link-id-1 por link-id-2 no seu banco de dados e usar link-id-2 para suas futuras solicitações.

Opt-in para prevenir links duplicados

A Belvo oferece um recurso de opt-in projetado para evitar que links duplicados sejam criados, garantindo que seus usuários nunca conectem a mesma conta duas vezes ao seu aplicativo. Se o seu usuário já conectou com sucesso a conta dele e tentar conectar a mesma conta novamente:

• Integrações usando o Connect Widget da Belvo - seus usuários receberão um erro no Connect Widget e seu backend receberá um Error Event Callback.
• Integrações que não usam o Connect Widget da Belvo - você receberá um erro de API 400 duplicated.

Se você deseja optar por este recurso, basta entrar em contato com nossa equipe de suporte e eles ficarão felizes em ajudá-lo! Para usar este recurso, pode ser necessário alterar sua integração para usar o parâmetro external_id na criação do link.

Lidando com Autenticação Multifator (MFA)

Fluxo geral

O fluxo geral para MFA é:

1. Você faz uma solicitação POST para a instituição para recuperar alguns dados ou criar um link.
2. A Belvo envia uma resposta 428 Token Required, detalhando qual método de MFA é necessário para completar a solicitação.
3. Você solicita ao usuário que insira o token de autenticação necessário.
4. Você faz uma solicitação Complete PATCH para o recurso fornecido com o ID do link, ID da sessão e o token de autenticação fornecido pelo usuário.
5. A Belvo envia uma mensagem de sucesso 201.

428 Response

Abaixo você pode ver um payload anotado para uma resposta 428 Token Required. Para informações detalhadas sobre o objeto token_generation_data, por favor, veja a seção Métodos MFA.

[
    {
        "code": "token_required", // Código de resposta
        "message": "Um token MFA é necessário pela instituição para login", // Descrição legível da resposta.
        "session": "be7a15d5f0b84d8ea60f6c12cb2a7b32", // ID da sessão (necessário em sua solicitação PATCH).
        "expiry": "720", // A duração em que o usuário final precisa fornecer um token, em segundos.
        "link": "449e388c-812b-4798-8743-7d11efb6becf", // ID do link do usuário final (necessário em sua solicitação PATCH).
        "token_generation_data": {
           
			// Contém detalhes sobre o Método MFA necessário (inputless, numeric, qr, text). 
			// Por favor, veja a seção relevante
			// abaixo para informações detalhadas.

        },
        "request_id": "b7a3a5b3a3a2b6aa28f4cc98d55cf1f1" // O ID da solicitação (usado para fins de depuração). 
    }
]

expect_user_input

No objeto token_generation_data, incluímos um parâmetro expect_user_input. Quando definido como false, isso indica que o usuário só precisa, por exemplo:

• Escanear um código QR para completar a autenticação (semelhante a como você autentica o aplicativo de desktop do Whatsapp).
• Confirmar o login em outro dispositivo (semelhante à autenticação sem senha)

Inputless

O método MFA Inputless requer que o usuário gere um token de autenticação usando seu dispositivo e forneça a você o token gerado. A resposta 428 Token Required que você recebe terá inputless no campo type. Na sua interface, apenas solicite ao usuário que adicione seu token de entrada.

[
    {
        "code": "token_required",
        "message": "A MFA token is required by the institution to login",
        "session": "be7a15d5f0b84d8ea60f6c12cb2a7b32",
        "expiry": "720",
        "link": "449e388c-812b-4798-8743-7d11efb6becf",
        "token_generation_data": {
            "instructions": "Use your app or device to generate a token",
            "type": "inputless", // <-- O método MFA é inputless.
            "value": null, // <-- Nenhum valor é passado.
          	"expects_user_input": true // <-- Indica que o usuário precisa fornecer dados para completar a autenticação.
        },
        "request_id": "b7a3a5b3a3a2b6aa28f4cc98d55cf1f1"
    }
]

Depois de receber o token do usuário final, você faz uma solicitação PATCH.

Numérico

O método MFA numérico requer que o seu usuário final insira um código em seu dispositivo para receber o token de autenticação. O código que eles precisarão inserir em seu dispositivo é passado na resposta 428 Token Required, onde o campo type será numeric e o campo value conterá o código que o usuário precisa inserir em sua aplicação. Na sua interface, você pode exibir este código para o seu usuário para que ele possa inseri-lo em sua aplicação.

[
    {
        "code": "token_required",
        "message": "A MFA token is required by the institution to login",
        "session": "731b8a5ed45245b3a2bd595382016b5e",
        "expiry": "60",
        "link": "04134743-73f9-41c3-a6dd-06cee3fab627",
        "token_generation_data": {
            "instructions": "Use this code to generate the token",
            "type": "numeric", // <-- O método MFA é numérico.
            "value": "703837", // <-- O código a ser exibido para o usuário.
            "expects_user_input": true // <-- Indica que o usuário precisa fornecer dados para completar a autenticação.
        },
        "request_id": "63cece2a9374b06495a16da5b2265793"
    }
]

Após receber o token do seu usuário final, você faz uma solicitação PATCH.

QR code

O método de MFA com QR Code requer que o seu usuário final escaneie um QR code para obter o token de autenticação.

O QR code que eles precisarão escanear com seu aplicativo é passado na resposta 428 Token Required. O código que eles precisarão inserir em seu dispositivo é passado na resposta 428 Token Required, onde o campo type será qr e o campo value conterá a representação em string BASE64 do QR Code. Você pode analisar essa string para gerar o QR code e exibi-lo para o seu usuário na sua interface.

[
    {
        "code": "token_required",
        "message": "A MFA token is required by the institution to login",
        "session": "433142d512854cf6b10a3ccc08f3fa7d",
        "expiry": "60", 
        "link": "66a5cf30-512d-4830-b616-7dd7d6ecf09f",
        "token_generation_data": {
            "instructions": "Scan this QR code to generate the token",
            "type": "qr", // <-- O método de MFA é um QR code.
            "value": "...", // <-- String BASE64 para analisar e gerar o QR code.
          	"expects_user_input": true // <-- Indica que o usuário precisa fornecer dados para completar a autenticação
        },
        "request_id": "ce05c19b323c1caae6445aff5d4229f8"
    }
]

Depois de receber o token do seu usuário final, você faz uma solicitação PATCH.

Texto

O método de MFA de Texto requer que seu usuário responda a uma pergunta de segurança. A resposta 428 Token Required que você recebe terá text no campo type. Na sua interface, basta solicitar que seu usuário responda à pergunta de segurança e use a string fornecida como o valor do parâmetro token na sua solicitação PATCH.

[
    {
        "code": "token_required",
        "message": "A MFA token is required by the institution to login",
        "session": "be7a15d5f0b84d8ea60f6c12cb2a7b32",
        "expiry": "720",
        "link": "449e388c-812b-4798-8743-7d11efb6becf",
        "token_generation_data": {
            "instructions": "Answer the question to proceed",
            "type": "text", // <-- O método de MFA é uma resposta a uma pergunta de segurança.
            "value": "Where were you born?", // <-- Pergunta de segurança que o usuário precisa responder.
          	"expects_user_input": true // <-- Indica que o usuário precisa fornecer dados para completar a autenticação
        },
        "request_id": "b7a3a5b3a3a2b6aa28f4cc98d55cf1f1"
    }
]

Depois de receber o token do seu usuário final, você faz uma solicitação PATCH.

Enviar token MFA após uma resposta 428

Quando for necessário fornecer um token durante o processo de conexão, você receberá uma resposta 428 Token Required e instruções sobre qual método MFA é necessário. Depois de solicitar ao usuário que insira seu token de autenticação, você deve enviar uma solicitação PATCH para o endpoint Resume do recurso que deseja acessar.

Por exemplo:

curl -X PATCH \
  https://sandbox.belvo.com/api/links/ \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
    "session": "{sessionId}",
		"link": "{linkId}",
    "token": "{userToken}"
}' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Onde:

• {sessionId} é o valor no campo session que você recebe na resposta 428 Token Required.
• {linkId} é o valor no campo link que você recebe na resposta 428 Token Required.
• {userToken} é o token de autenticação (incluindo uma resposta a uma pergunta de segurança) que seu usuário fornece.