# 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 Body Params abaixo.

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

## Request fields (application/json):

  - `body` (object, required) — one of:
    - Links de Emprego (Brasil):
      - `institution` (string, required)
        O nome Belvo para a instituição. Para instituições de emprego no Brasil, você pode selecionar as seguintes instituições:

- inss_br_employment
        Example: "inss_br_employment"
      - `username` (string, required)
        O CPF (ID) do usuário usado para fazer login na instituição. Você pode fornecê-lo com 11 caracteres ou no formato XXX.XXX.XXX-XX.
        Example: "231.002.999-00"
      - `password` (string, required)
        A senha do usuário usada para fazer login na instituição.
        Example: "1234B789C234AGH"
      - `external_id` (string)
        Um identificador adicional para o link, fornecido por você, para armazenar no banco de dados da Belvo. Não pode incluir nenhuma Informação Pessoal Identificável (PII). Deve ter pelo menos três caracteres.

Se identificarmos que o identificador contém PII, forçaremos um valor null. Para mais informações, consulte nosso artigo sobre criação de links.
        Example: "56ab5706-6e00-48a4-91c9-ca55968678d9"
      - `access_mode` (string)
        O tipo de link a ser criado.

- Use single para fazer requisições POST ad hoc únicas para contas, proprietários e transações.
- Use recurrent para que o Belvo acesse informações de forma recorrente, garantindo que você sempre tenha dados atualizados de contas, proprietários, saldos e transações.

Para mais informações, consulte nosso artigo de Links.
        Enum: "single", "recurrent"
      - `fetch_resources` (array)
        Uma matriz de recursos para os quais você gostaria de receber uma atualização histórica.

Para Empregos Brasil (INSS), você pode selecionar os seguintes recursos:
  - EMPLOYMENTS
  - OWNERS
        Enum: "EMPLOYMENTS", "OWNERS"
      - `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 store por padrão (e não pode ser alterado).
- Para links únicos, isso é definido como 365d por padrão.

Pode ser:
  - store para armazenar credenciais (até que o link seja excluído)
  - nostore para não armazenar credenciais
  - Qualquer valor entre 1d e 365d 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"
      - `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 90d, 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 stale_in. A Belvo removerá dados apenas para links que não foram atualizados no período que você fornecer em stale_in.

Por padrão, a Belvo armazena dados do usuário por 365 dias, a menos que o link seja deletado.
        Example: "42d"
    - Links de Emprego (México):
      - `institution` (string, required)
        O nome Belvo para a instituição. Para instituições de emprego no México, você pode selecionar as seguintes instituições:

- imss_mx_employment
- issste_mx_employment
- planet_mx_employment (instituição Sandbox)
        Example: "imss_mx_employment"
      - `username` (string, required)
        A CURP (ID) do usuário usada para fazer login na instituição.
        Example: "BLPM951331IONVGR54"
      - `username2` (string)
        O endereço de e-mail do usuário usado para fazer login na instituição. Nota necessária para issste_mx_employment.
        Example: "carlos@bex.com"
      - `external_id` (string)
        Um identificador adicional para o link, fornecido por você, para armazenar no banco de dados da Belvo. Não pode incluir nenhuma Informação Pessoal Identificável (PII). Deve ter pelo menos três caracteres.

Se identificarmos que o identificador contém PII, forçaremos um valor null. Para mais informações, consulte nosso artigo sobre criação de links.
        Example: "56ab5706-6e00-48a4-91c9-ca55968678d9"
      - `access_mode` (string)
        O tipo de link a ser criado.

- Use single para fazer requisições POST ad hoc únicas para contas, proprietários e transações.
- Use recurrent para que o Belvo acesse informações de forma recorrente, garantindo que você sempre tenha dados atualizados de contas, proprietários, saldos e transações.

Para mais informações, consulte nosso artigo de Links.
        Enum: same as `access_mode` in "Links de Emprego (Brasil)" (2 values)
      - `fetch_resources` (array)
        Uma matriz de recursos para os quais você gostaria de receber uma atualização histórica.

Para Registros de Emprego no México (IMSS e ISSSTE), você pode selecionar os seguintes recursos:
  - EMPLOYMENT_RECORDS

Além disso, você pode optar pelos seguintes recursos específicos de Registros de Emprego (entre em contato com seu representante, pois custos adicionais se aplicam):
  - CURRENT_EMPLOYMENTS (somente IMSS)
  - EMPLOYMENT_METRICS (somente IMSS)
        Enum: "EMPLOYMENT_RECORDS", "CURRENT_EMPLOYMENTS", "EMPLOYMENT_METRICS"
      - `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 store por padrão (e não pode ser alterado).
- Para links únicos, isso é definido como 365d por padrão.

Pode ser:
  - store para armazenar credenciais (até que o link seja excluído)
  - nostore para não armazenar credenciais
  - Qualquer valor entre 1d e 365d 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"
      - `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 90d, 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 stale_in. A Belvo removerá dados apenas para links que não foram atualizados no período que você fornecer em stale_in.

Por padrão, a Belvo armazena dados do usuário por 365 dias, a menos que o link seja deletado.
        Example: "42d"
    - Fiscal Links (México):
      - `institution` (string, required)
        O nome Belvo para a instituição. Para instituições fiscais no México, você pode selecionar as seguintes instituições:

- sat_mx_fiscal
- tatooine_mx_fiscal (Instituição Sandbox)
        Example: "sat_mx_fiscal"
      - `username` (string, required)
        O RFC (ID fiscal) do usuário usado para fazer login na instituição.
        Example: "123456789101"
      - `password` (string, required)
        A senha do usuário usada para fazer login na instituição.
        Example: "passw0rd"
      - `external_id` (string)
        Um identificador adicional para o link, fornecido por você, para armazenar no banco de dados da Belvo. Não pode incluir nenhuma Informação Pessoal Identificável (PII). Deve ter pelo menos três caracteres.

Se identificarmos que o identificador contém PII, forçaremos um valor null. Para mais informações, consulte nosso artigo sobre criação de links.
        Example: "56ab5706-6e00-48a4-91c9-ca55968678d9"
      - `access_mode` (string)
        O tipo de link a ser criado.

- Use single para fazer requisições POST ad hoc únicas para contas, proprietários e transações.
- Use recurrent para que o Belvo acesse informações de forma recorrente, garantindo que você sempre tenha dados atualizados de contas, proprietários, saldos e transações.

Para mais informações, consulte nosso artigo de Links.
        Enum: same as `access_mode` in "Links de Emprego (Brasil)" (2 values)
      - `fetch_resources` (array)
        Um array de recursos para os quais você gostaria de receber uma atualização histórica.

Para Fiscal Mexico (SAT), você pode selecionar os seguintes recursos:
  - FINANCIAL_STATEMENTS
  - INVOICES
  - TAX_COMPLIANCE_STATUS
  - TAX_RETENTIONS
  - TAX_RETURNS
  - TAX_STATUS
        Enum: "FINANCIAL_STATEMENTS", "INVOICES", "TAX_COMPLIANCE_STATUS", "TAX_RETENTIONS", "TAX_RETURNS", "TAX_STATUS"
      - `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 store por padrão (e não pode ser alterado).
- Para links únicos, isso é definido como 365d por padrão.

Pode ser:
  - store para armazenar credenciais (até que o link seja excluído)
  - nostore para não armazenar credenciais
  - Qualquer valor entre 1d e 365d 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"
      - `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 90d, 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 stale_in. A Belvo removerá dados apenas para links que não foram atualizados no período que você fornecer em stale_in.

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

## 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: - single - recurrent - null
    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. Não pode incluir nenhuma Informação Pessoal Identificável (PII). Deve ter pelo menos três caracteres.

Se identificarmos que o identificador contém PII, forçaremos um valor null. 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 após 08-02-2022.

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:  
  - valid  
  - invalid  
  - unconfirmed  
  - token_required
    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:
  - 6h
  - 12h
  - 24h
  - 7d (padrão)
  - 30d (uma vez por mês)
  - null (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 store por padrão (e não pode ser alterado).
- Para links únicos, isso é definido como 365d por padrão.

Pode ser:
  - store para armazenar credenciais (até que o link seja excluído)
  - nostore para não armazenar credenciais
  - Qualquer valor entre 1d e 365d 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 90d, 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 stale_in. A Belvo removerá dados apenas para links que não foram atualizados no período que você fornecer em stale_in.

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 (access_to_resource_denied) 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 access_to_resource_denied, a descrição é:

  - You don't have access to this resource..
    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: [a-f0-9]{32}). 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 (not_found) que permite classificar e lidar com o erro programaticamente.
    Example: "not_found"

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

Para erros not_found, a descrição é:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). 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 (request_timeout) 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 request_timeout, a descrição é:

  - The request timed out, you can retry asking for less data by changing your query parameters.
    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: [a-f0-9]{32}). 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 (token_required) 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 token_required, a descrição é:

- A instituição requer um token MFA para fazer login.
    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: [a-f0-9]{32}). 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: [a-f0-9]{32}).
    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 false, 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 (unexpected_error) 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 unexpected_error, a descrição é:

  - Belvo não consegue processar a solicitação devido a um problema interno do sistema ou a uma resposta não suportada de uma instituiçã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: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"