# Links

Um **Link** é um conjunto de credenciais associado ao acesso de um usuário final a uma **instituição**. Você precisará registrar um **Link** antes de acessar informações desse usuário final específico, como detalhes de conta ou transações.

Recomendamos usar o Belvo Hosted Widget para gerenciar o processo de conexão.

## Listar links

 - [GET /api/links/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/listlinks.md): ## ▶️ Uso

Com o método List Links, você pode:

1. Listar todos os links relacionados à sua conta Belvo (sem usar parâmetros de consulta).
2. Obter os detalhes de um link.id específico (usando o parâmetro de consulta id).

## 📖 Paginação

Este método retorna uma resposta paginada (padrão: 100 itens por página). Você pode usar o parâmetro de consulta page_size para aumentar o número de itens retornados até um máximo de 1000 itens. Você pode usar o parâmetro de consulta page para navegar pelos resultados. Para mais detalhes sobre como navegar pelas respostas paginadas da Belvo, consulte nosso artigo Dicas de Paginação.

## 🔦 Filtrando Respostas

Consulte a lista de consultas abaixo para ver uma lista de campos pelos quais você pode filtrar suas respostas. Para mais informações sobre como usar filtros, veja nosso artigo Filtrando respostas.

## Registrar um novo link

 - [POST /api/links/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/registerlink.md): ## ▶️ Uso

Registre um novo link (uma conexão entre seu usuário e sua instituição) usando a API da Belvo.

> 👍 Recomendamos fortemente o uso do nosso Connect Widget para gerenciar a criação de links e atualizações de status de links.

Para facilitar, incluímos exemplos personalizados para os links que você pode criar para cada um dos nossos produtos. Basta clicar no tipo de link que você deseja criar na seção Body Params abaixo.

## Solicitação completa de links

 - [PATCH /api/links/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/patchlinks.md): Usado para retomar uma sessão de registro de Link que foi pausada porque um token MFA foi exigido pela instituição.

## Obter detalhes de um link

 - [GET /api/links/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/detaillink.md): Obtenha os detalhes de um link específico.

## Modificar a recuperação de dados de um link

 - [PATCH /api/links/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/modifylinkdataretrieval.md): Modificar as configurações de recuperação de dados para um link específico. Atualmente, você pode:

- Alterar o modo de acesso de um link de single para recurrent ou de recurrent para single.
- Modificar o período stale_in para o link.
- Modificar os recursos históricos que você deseja recuperar para o link (fetch_resources).

## Alterando o access_mode de um link

Quando você altera um link de single para recurrent, no dia seguinte é acionada uma atualização histórica dos recursos principais para o link (resultando no recebimento de webhooks de historical_update para o link). Você será cobrado por essas atualizações históricas.

## Modificando stale_in

Se você apenas modificar o período stale_in para um link, isso não acionará uma atualização histórica. Para acionar uma atualização histórica para o link, você deve alterar o access_mode.

## Modificando fetch_resources

Se você apenas modificar o fetch_resources para um link, isso não acionará uma atualização histórica. Para acionar uma atualização histórica para o link, você deve alterar o access_mode.

## Atualizar as credenciais de um link

 - [PUT /api/links/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/updatelink.md): Atualize as credenciais de um link específico. Se o link atualizado com sucesso for recorrente, acionamos automaticamente uma atualização do link. Se encontrarmos dados novos, você receberá webhooks de atualização histórica.

> 👍 Use nosso Connect Widget
>
> Recomendamos usar nosso Connect Widget para lidar com a atualização de links invalid ou token_required.

## Excluir um link

 - [DELETE /api/links/{id}/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/destroylink.md): Exclua um link específico e todos os dados associados (por exemplo: transações, contas, faturas, declarações de impostos, empregos, etc.) desse link da sua conta Belvo. Esta ação é irreversível e você não poderá recuperar os dados excluídos.

{% admonition type="success" name="Use o cabeçalho X-Belvo-Request-Mode: async" %}
  Recomendamos fortemente definir o cabeçalho X-Belvo-Request-Mode como async para habilitar a exclusão assíncrona. Dessa forma, você evitará o limite de taxa de 5 exclusões por minuto. Quando configurado, o endpoint responderá com um status 202 Accepted e fornecerá um ID de solicitação para rastrear o processo de exclusão. Assim que o processo for concluído, você receberá uma notificação webhook link_deleted.
  
  Se você não definir este cabeçalho, o endpoint responderá com um status 204 No Content, mas você estará sujeito ao limite de taxa de 5 exclusões por minuto. Se exceder esse limite, você receberá um erro 429 Too Many Requests.
{% /admonition %}

## Acionar uma atualização histórica para um link

 - [POST /api/links/{id}/refresh/](https://developers.belvo.com/pt-br/apis/belvoopenapispec/links/refreshhistoricaldataforlink.md): {% admonition type="warning" name="Limite de Requisições Concorrentes" %}
  Para evitar requisições duplicadas, este endpoint possui um período de cooldown de 10 minutos por link. Se você tentar atualizar o mesmo link dentro de 10 minutos após uma solicitação anterior, receberá um erro 409 Conflict com a mensagem "The link has already been refreshed. Please wait X minutes before trying again.".
{% /admonition %}

Use este método para acionar uma atualização histórica para um link específico (único ou recorrente). Utilize o parâmetro fetch_resources para especificar quais recursos você deseja atualizar. Se você não especificar este parâmetro, a atualização histórica será realizada para todos os recursos suportados pela instituição à qual o link está associado.

Em uma solicitação bem-sucedida, nossa API responderá com um código de status 202 e um request_id que você poderá usar posteriormente para associar um webhook de historical_update a esta solicitação.

{% admonition type="info" name="Não atualiza a definição do link" %}
  Este endpoint não atualiza a definição do link em si, apenas os dados históricos para os recursos especificados. Se você deseja alterar permanentemente o fetch_resources do link, deve usar o método Modificar a recuperação de dados de um link.
{% /admonition %}