# 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 webhook para que você sempre tenha dados atualizados. Então, quando você recebe o webhook, pode usar requisições GET nos endpoints de Lista ou Detalhe para acessar instantaneamente informações atualizadas, sem precisar se conectar à instituição. ```mermaid sequenceDiagram autonumber participant App as Application participant Belvo as Belvo participant Inst as Institution App->>Belvo: Create a recurrent Link using the widget Belvo->>Inst: Connect and confirm link creation Belvo-->>App: 201 - Created Note over App,Inst: Belvo retrieves historical OWNER, ACCOUNTS, and TRANSACTION information for the Link ID Belvo-->>App: WEBHOOK historical_update (per resource) App->>Belvo: GET /{resource}/?link={link.id} Belvo-->>App: 200 + resource Details Note over App,Inst: At your scheduled Link update frequency, Belvo checks for new information for each link per resource Belvo-->>App: WEBHOOK new_{resource}_available App->>Belvo: GET /{resource}/?link={link.id} Belvo-->>App: 200 + resource Details ``` 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 a criação de um link. 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 a criação de um link). 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 aos usuários 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. | ## Links únicos Links únicos são usados para realizar acesso ad hoc a dados de contas, proprietários, transações, etc. Por exemplo, você pode usá-los quando deseja realizar um processo de subscrição para avaliar o risco antes de emprestar dinheiro. Para links únicos, você precisa passar o parâmetro `fetch_resources` ao criar e, em seguida, ouvir os webhooks assim que os dados históricos forem extraídos de forma assíncrona. ```mermaid sequenceDiagram autonumber participant App as Application participant Belvo as Belvo participant Inst as Institution App->>Belvo: Create a single Link using the widget Note over App,Belvo: fetch_resources = [OWNERS, ACCOUNTS, TRANSACTIONS] Belvo->>Inst: Connect and confirm link creation Belvo-->>App: 201 - Created Note over App,Inst: Belvo retrieves historical OWNER, ACCOUNTS, and TRANSACTION information for the Link ID Belvo-->>App: WEBHOOK historical_update (OWNERS) App->>Belvo: GET /owners/?link={link.id} Belvo-->>App: 200 + Owner Details Belvo-->>App: WEBHOOK historical_update (ACCOUNTS) App->>Belvo: GET /accounts/?link={link.id} Belvo-->>App: 200 + Account Details Belvo-->>App: WEBHOOK historical_update (TRANSACTIONS) App->>Belvo: GET /transactions/?link={link.id} Belvo-->>App: 200 + Transaction Details ``` ## 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. ```mermaid flowchart LR classDef server fill:#FFD580,stroke:#E6B800,color:#000 classDef process fill:#ADD8E6,stroke:#7BAFD4,color:#000 classDef error fill:#FFB6C1,stroke:#FF6B8A,color:#000 subgraph S1["YOUR SERVER"] A["Register your user with your platform"] B["Start the widget"] end subgraph Belvo["BELVO"] direction TB C{"User provides correct credentials?"} D["Link not created"] E["Link created and stored in Belvo database"] F{"App still active?"} G["Orphan Link"] end subgraph S2["YOUR SERVER"] H["Receive Success Callback with link_id and institution"] I["Store response in your DB"] end A --> B --> C C -->|"Yes"| E C -->|"No"| D E --> F F -->|"Yes"| H F -->|"No"| G H --> I class A,B,H,I server class E process class D,G error ``` 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 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. ```mermaid flowchart LR classDef server fill:#FFD580,stroke:#E6B800,color:#000 classDef process fill:#ADD8E6,stroke:#7BAFD4,color:#000 classDef error fill:#FFB6C1,stroke:#FF6B8A,color:#000 classDef orphan fill:#DDA0DD,stroke:#9370DB,color:#000 subgraph S1["YOUR SERVER"] A["Register your user with your platform"] B["Start widget with the unique ID as the external_id"] end subgraph Belvo["BELVO"] direction TB C{"User provides correct credentials?"} D["Link not created"] E["Link created and stored in Belvo database"] F{"App still active?"} G["Orphan Link (retrievable using external_id)"] end subgraph S2["YOUR SERVER"] H["Receive Success Callback with link_id and institution"] I["Store response in your DB"] end A --> B --> C C -->|"Yes"| E C -->|"No"| D E --> F F -->|"Yes"| H F -->|"No"| G H --> I class A,B,H,I server class E process class D error class G orphan ``` ### 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 que você registre 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 Hosted Widget em Modo de Atualização. Desta 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 requisiçõ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 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 ```mermaid sequenceDiagram autonumber participant App as Application participant Belvo as Belvo participant Inst as Institution App->>Belvo: POST /links/ {username, password} Belvo->>Inst: Start connection Belvo-->>App: 428 Token Required + Session ID Note over App,Belvo: Prompt your user to provide the authentication token App->>Belvo: PATCH /links/ {Link ID, session, token} Belvo->>Inst: Complete connection Belvo-->>App: Success ``` O fluxo geral para MFA é: 1. Você faz uma requisição POST para a instituição para recuperar alguns dados ou criar um link. 2. Belvo envia uma resposta 428 Token Required, detalhando qual método MFA é necessário para completar a requisição. 3. Você solicita ao usuário que insira o token de autenticação necessário. 4. Você faz uma requisiçã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. 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.