# 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.

Use seu próprio identificador 🤩
Recomendamos fortemente que você utilize o parâmetro `external_id` ao criar links, pois isso permitirá que você tenha seu próprio identificador único para um link em seu próprio banco de dados. Confira nosso artigo sobre melhores práticas de criação de Link para mais informações.

## 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.

Uso de credenciais do usuário
Ao usar links recorrentes, você deve garantir que está em conformidade com a regulamentação de privacidade de dados do país em que opera. Além disso, recomendamos que você informe os usuários de que suas credenciais serão usadas diariamente para recuperar ciclicamente dados atualizados.

### 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.


Preços das taxas de atualização
Para alterar sua taxa de atualização ou discutir preços de taxas de atualização, basta enviar um e-mail para nossa equipe de vendas em sales@belvo.com, e eles cuidarão disso.

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

| Instituição | Informação inicial | Informação atualizada |
|  --- | --- | --- |
| Bancário (Brasil) | Todas as informações de conta, transação e proprietário | - Informações da conta, incluindo saldo atual e dados de crédito.
- Novas transações (adicionadas desde a última atualização do link recorrente).
- Informações pessoais do proprietário do link.

 |
| Fiscal (México) | Todas as faturas, os status de conformidade fiscal, declarações fiscais e o status fiscal. | - Novas faturas enviadas ou recebidas nos últimos cinco anos.
- Novas declarações fiscais adicionadas nos últimos cinco anos.

 |


## 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.

| Status | Descrição | Ação |
|  --- | --- | --- |
| `valid` | Um link `valid` é um link totalmente funcional. | Nenhuma 🎉 |
| `invalid` | Um link `invalid` significa que as credenciais não são mais válidas. | Você precisa pedir ao seu usuário para atualizar suas credenciais para que o link seja válido novamente.    💡Use o Connect widget no modo de atualização para pedir ao seu usuário que forneça uma nova senha. |
| `unconfirmed` | Um link `unconfirmed` significa que o link nunca foi criado com sucesso. Uma situação comum onde isso pode ocorrer é quando um usuário foi solicitado a fornecer um token MFA, mas nunca o forneceu. | Você precisa retomar o processo de criação do link com um token para completar a criação do link. |
| `token_required` | Um link `token_required` significa que um link anteriormente `valid` agora requer um novo token. | Você precisa retomar o processo de atualização do link com um token.    💡Use o Connect widget no modo de atualização para pedir ao seu usuário que forneça uma nova senha. |


### 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:

#### Listar todos os links atuais

Use o **método Listar todos os 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.


```shell Listar todos os links
# Filtrar por links inválidos
curl --request POST 'https://sandbox.belvo.com/api/links/?page_size=1000&status=invalid'\
  -u SECRET_ID:SECRET_PASSWORD

# Obter a lista completa de links
curl --request POST 'https://sandbox.belvo.com/api/links/?page_size=1000'\
  -u SECRET_ID:SECRET_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.


```shell Obter detalhes de um link
curl --request GET 'https://sandbox.belvo.com/api/links/{id}' \
  -u SECRET_ID:SECRET_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.


Por que você deve primeiro registrar um usuário na sua plataforma e depois usar o widget?
Ao registrar primeiro seu usuário na sua plataforma, você tem uma maneira de associar um usuário a um link criado 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.).


Informações pessoalmente identificáveis com external_id
Se você usar qualquer informação pessoalmente identificável no seu `external_id`, a Belvo definirá o `external_id` como `null`. Assim, você não poderá filtrar seus links por esse `external_id`.

#### 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`:



```json Usuário conecta conta
{
	"id": "link-id-1",
	"institution_user_id": "ooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c="
}
```

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



```json Usuário conecta a mesma conta novamente
{
	"id": "link-id-2",
	"institution_user_id": "ooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c="
}
```

1. 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.


Links com status não confirmado
Na situação em que seu usuário tentou anteriormente criar um link, mas nunca finalizou o fluxo (resultando no `status` do link sendo definido como `unconfirmed`), quando ele tentar conectar a mesma conta novamente, a Belvo permitirá que o link seja criado. Este recurso garante que você ainda possa recuperar informações vitais do usuário e fornece aos seus usuários a capacidade de ainda conectar suas contas.

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.

## Atualizando manualmente dados históricos

Em Beta
O método **Trigger a historical update for a link** está atualmente em Beta Aberto para todos os clientes usarem. Incentivamos você a experimentá-lo e fornecer feedback.

Você pode programaticamente acionar uma atualização histórica para os dados de um link usando nosso método Trigger a historical update for a link. Isso é útil quando você precisa obter os dados mais recentes para recursos específicos sem esperar pela próxima atualização agendada de um link recorrente ou quando deseja acionar uma atualização para um único link.

Ao fazer uma solicitação para este endpoint, você pode especificar quais recursos (`ACCOUNTS`, `TRANSACTIONS`, etc.) deseja atualizar. Se você não especificar nenhum, atualizaremos todos os recursos suportados pela instituição.

Período de Resfriamento
Por favor, esteja ciente de que, para evitar solicitações duplicadas, este endpoint tem um período de resfriamento de 10 minutos por link. Se você tentar atualizar o mesmo link dentro deste intervalo, receberá um erro `409 Conflict`.

## Lidando com Autenticação Multifator (MFA)

Lide com MFA com nosso Connect Widget
Recomendamos fortemente que você use nosso Connect Widget para lidar com a criação de links. Nosso widget lida automaticamente com todo o processo de criação de links, incluindo todos os cenários de token MFA (sem entrada, numérico, código QR ou texto).

### 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 PATCH **Complete** para o recurso dado 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.


### Resposta 428

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


```json Resposta Genérica 428
[
    {
        "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). 
			// Consulte 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 de MFA Inputless requer que o seu 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 que o usuário adicione seu token de entrada.


```json Inputless MFA Payload
[
    {
        "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 de 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 seu 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.

Validade do código numérico
O código numérico incluído na resposta 428 é válido por até 30 ou 60 segundos (dependendo da instituição). Se o seu usuário fornecer o código gerado após esse tempo, a instituição retorna outra resposta 428 com um novo código numérico.


```json Payload MFA Numérico
[
    {
        "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"
    }
]
```

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

### Código QR

O método MFA de Código QR requer que seu usuário final escaneie um código QR para recuperar o token de autenticação.

O código QR 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 Código QR. Você pode analisar essa string para gerar o código QR e exibi-lo para seu usuário na sua interface.

Validade do código QR
O código QR incluído na resposta 428 é válido por até 30 ou 60 segundos (dependendo da instituição). Se seu usuário fornecer seu código gerado após esse tempo, a instituição retorna outra resposta 428 com um novo código QR.


```json QR Code MFA Payload
[
    {
        "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 MFA é um código QR.
            "value": "...", // <-- String BASE64 para analisar e gerar o código QR.
          	"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, apenas solicite 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.


```json Text MFA Payload
[
    {
        "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
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_ID:SECRET_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.