# Registrar um novo link

## ▶️ 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  abaixo.

Endpoint: POST /api/links/
Version: 1.223.0
Security: basicAuth

## Response 201 fields (application/json):

  - `id` (string)
    Identificador único da Belvo para o item atual.
    Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"

  - `institution` (string)
    Nome da instituição segundo a Belvo.
    Example: "erebor_mx_retail"

  - `access_mode` (string,null)
    O tipo de link. Para mais informações, consulte nosso artigo de Links. Retornamos um dos seguintes valores enum: -  -  -
    Enum: "single", "recurrent", null

  - `last_accessed_at` (string,null)
    O timestamp ISO-8601 do acesso mais recente e bem-sucedido da Belvo à instituição para o link fornecido.
    Example: "2021-03-09T10:28:40.000Z"

  - `created_at` (string)
    O carimbo de data e hora ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo.
    Example: "2022-02-09T08:45:50.406032Z"

  - `external_id` (string)
    Um identificador adicional para o link, fornecido por você, para armazenar no banco de dados da Belvo.  incluir nenhuma Informação Pessoal Identificável (PII).  ter pelo menos três caracteres.

Se identificarmos que o identificador contém PII, forçaremos um valor . Para mais informações, consulte nosso artigo sobre criação de links.
    Example: "56ab5706-6e00-48a4-91c9-ca55968678d9"

  - `institution_user_id` (string)
    > 📘 Info
>
> Aplicável apenas para links criados .

Uma string única de 44 caracteres que pode ser usada para identificar um usuário em uma determinada instituição.

📚 Confira nosso artigo no DevPortal sobre como evitar links duplicados para mais informações e dicas sobre como usá-la.
    Example: "sooE7XJWEKypZJR603ecaWYk-8Ap0oD8Nr1pBQ4eG9c="

  - `status` (string)
    O status atual do link. Para mais informações, consulte nosso artigo sobre Link no devportal.  
Retornamos um dos seguintes valores:  
  -   
  -   
  -   
  -
    Enum: "valid", "invalid", "unconfirmed", "token_required"

  - `created_by` (string)
    O ID único para o usuário que criou este item.
    Example: "bcef7f35-67f2-4b19-b009-cb38795faf09"

  - `refresh_rate` (string,null)
    A taxa de atualização para o link recorrente. Para mais informações, consulte nossa documentação de links recorrentes em nosso DevPortal.
Retornamos um dos seguintes valores de enum:
  - 
  - 
  - 
  -  (padrão)
  -  (uma vez por mês)
  -  (para links únicos)
    Enum: "6h", "12h", "24h", "7d", "30d", null

  - `credentials_storage` (string)
    Indica se as credenciais devem ou não ser armazenadas (e a duração para a qual as credenciais serão armazenadas).

- Para links recorrentes, isso é definido como  por padrão (e não pode ser alterado).
- Para links únicos, isso é definido como  por padrão.

Pode ser:
  -  para armazenar credenciais (até que o link seja excluído)
  -  para não armazenar credenciais
  - Qualquer valor entre  e  para indicar o número de dias que você deseja que as credenciais sejam armazenadas.

Para mais informações, confira a seção credentials_storage do nosso artigo sobre controles de retenção de dados.
    Example: "27d"

  - `fetch_resources` (array)
    Um array de recursos para o qual você receberá uma atualização histórica.
    Example: ["ACCOUNTS","TRANSACTIONS"]

  - `stale_in` (string)
    Indica por quanto tempo qualquer dado derivado do usuário deve ser armazenado no banco de dados da Belvo para o link (tanto único quanto recorrente). Por exemplo, se você enviar , a Belvo removerá qualquer dado relacionado ao usuário de seu banco de dados após 90 dias. Para mais informações, confira a seção stale_in do nosso artigo sobre controles de retenção de dados.

> 📘 Informação
>
> A Belvo removerá dados apenas para links que não foram atualizados no período que você fornecer em . A Belvo removerá dados apenas para links que não foram atualizados no período que você fornecer em .

Por padrão, a Belvo armazena dados do usuário por 365 dias, a menos que o link seja deletado.
    Example: "42d"

## Response 403 fields (application/json):

  - `code` (string)
    Um código de erro único () que permite classificar e tratar o erro programaticamente.

ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    Uma breve descrição do erro.

Para erros , a descrição é:

  - .
    Example: "You don't have access to this resource."

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: ). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    Um código de erro único () que permite classificar e lidar com o erro programaticamente.
    Example: "not_found"

  - `message` (string)
    Uma breve descrição do erro.

Para erros , a descrição é:

  -
    Example: "Not found"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: ). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    Um código de erro único () que permite classificar e lidar com o erro programaticamente.

ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 408 request_timeout.
    Example: "request_timeout"

  - `message` (string)
    Uma breve descrição do erro.

Para erros de , a descrição é:

  - .
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: ). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 428 fields (application/json):

  - `code` (string)
    Um código de erro único () que permite classificar e lidar com o erro programaticamente.
ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 428 token_required.
    Example: "token_required"

  - `message` (string)
    Uma breve descrição do erro. Para erros , a descrição é:

- .
    Example: "A MFA token is required by the institution to login"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: ). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

  - `session` (string)
    Um ID único de 32 caracteres da sessão de login (correspondente a um padrão regex de: ).
    Example: "2675b703b9d4451f8d4861a3eee54449"

  - `expiry` (integer)
    Tempo de duração da sessão em segundos.
    Example: 9600

  - `link` (string)
    Identificador único criado pela Belvo, usado para referenciar o Link atual.
    Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"

  - `token_generation_data` (object)
    Detalhes sobre como gerar o token.

  - `token_generation_data.instructions` (string)
    Instruções para geração de token.
    Example: "Use this code to generate the token"

  - `token_generation_data.type` (string)
    Tipo de dados para gerar o token (QR code, desafio numérico).
    Example: "numeric"

  - `token_generation_data.value` (string)
    Valor a ser usado para gerar o token.
    Example: "12345"

  - `token_generation_data.expects_user_input` (boolean)
    Indica se o usuário precisa fornecer entrada para concluir a autenticação. Quando definido como , seu usuário pode precisar:
- confirmar o login em outro dispositivo
- escanear um código QR
Você ainda precisará fazer uma chamada PATCH para concluir a solicitação.
    Example: true

## Response 500 fields (application/json):

  - `code` (string)
    Um código de erro único () que permite classificar e tratar o erro de forma programática.

ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 500 unexpected_error.
    Example: "unexpected_error"

  - `message` (string)
    Uma breve descrição do erro.

Para erros , a descrição é:

  - .
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: ). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"