> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Conexões bancárias: acesso contínuo, consentimento e renovação

> Uma conexão é a permissão de uma pessoa para ler um banco. Veja os status, como o consentimento termina, como renová-lo e como encerrar o acesso na Didit.

Uma conexão bancária da Didit é a permissão de uma pessoa ou empresa para que sua aplicação leia um banco, com as datas de consentimento, o estado de sincronização e as contas desse banco.
Uma [Bank Link](https://docs.didit.me/pt-br/core-technology/bank-verification/bank-link.md) concluída cria a conexão, que permanece válida pelo tempo que o banco e a pessoa permitirem.

Os dados bancários estão disponíveis para aplicações em sandbox; as chamadas de uma aplicação em produção retornam `404` até que o acesso em produção seja anunciado.

## Acesso único e contínuo

| | Único | Contínuo |
| - | - | - |
| `access` | `one_time` (padrão) | `ongoing` |
| O que acontece | Os dados são lidos uma vez, quando a pessoa se conecta. Depois disso, o acesso é encerrado (`status_reason: collection_complete`). | O acesso permanece aberto até o consentimento terminar ou alguém interromper o acesso. |
| Dados depois | Podem ser lidos pelos mesmos endpoints. | Sincronizados automaticamente de uma a quatro vezes por dia, conforme o banco, além de sincronizações sob demanda em tempo real. |
| Cobrança | Por verificação, veja [preços](https://docs.didit.me/pt-br/getting-started/bank-verification-pricing.md) | Por conexão ativa por mês, veja [preços](https://docs.didit.me/pt-br/getting-started/bank-verification-pricing.md) |

O acesso contínuo só funciona em bancos que o permitem.
Consulte o [endpoint de instituições](https://docs.didit.me/pt-br/standalone-apis/bank-institutions-list.md) ou leia a [página de cobertura](https://docs.didit.me/pt-br/core-technology/bank-verification/coverage.md).
Quando um banco não consegue manter o acesso aberto, a pessoa é informada de que o banco não permite acesso contínuo e precisa escolher outro banco.
Defina `allow_one_time_fallback: true` para que a pessoa continue com uma leitura única depois de confirmar o acesso reduzido na própria tela: a conexão fica então como `one_time`.

## Status

| `status` | Significado | Dados legíveis | Sincronizações | Cobrado |
| - | - | - | - | - |
| `pending` | O link foi concluído e a primeira sincronização está em execução. | Ainda não | Em execução | Não |
| `active` | O consentimento é válido e a sincronização está funcionando normalmente ou tentando novamente. | Sim | Sim | Sim |
| `renewal_required` | O consentimento terminou, ou o banco pede que a pessoa faça login novamente. `status_reason` indica qual é o caso. | Conforme a última sincronização | Não | Não |
| `paused` | O saldo não cobre o mês. | Conforme a última sincronização | Não | Não |
| `revoked` | O acesso foi interrompido pela pessoa, pelo banco ou por você. `consent.ended_by` indica quem fez isso. | Até `consent.retain_until` | Não | Não |
| `deleted` | A conexão e os seus dados foram excluídos. | Não | Não | Não |
| `failed` | A primeira sincronização nunca foi bem-sucedida. | Não | Não | Não |

`status_reason` é um dos seguintes valores: `collection_complete`, `consent_expired`, `consent_lapsed`, `bank_requires_sign_in`, `revoked_by_end_user`, `revoked_by_bank`, `revoked_by_customer`, `insufficient_balance`, `paused_by_customer` (reservado, nenhum endpoint o define atualmente) e `first_sync_failed`.

## Consentimento

O banco define o fim do consentimento, até o `consent_days` que você solicitou.
Cada conexão mostra suas datas reais em `consent`:

* `expires_at` e `renew_by`: o fim do consentimento. Renove antes dele para não ter interrupção.
* `renewable_until`: o último momento em que a mesma conexão pode ser reativada depois que o consentimento terminou.
* `renewed_count`, `version`, `scopes_granted` e `accounts_granted`: o que foi concedido e quantas vezes ele foi renovado.

O consentimento dura pelo tempo que o banco permitir.
Consulte o valor real em cada conexão e o valor por banco na instituição.

## Renovação

Uma renovação mantém o id da conexão e todos os ids de conta, e o histórico continua sem duplicatas.

1. A Didit envia `bank.connection.consent_expiring` 14, 7 e 1 dia antes do fim.
2. Chame [`POST /v3/bank/connections/{id}/renew/`](https://docs.didit.me/pt-br/standalone-apis/bank-connection-renew). Ele responde `409 renewal_not_needed` enquanto restarem mais de 30 dias e `409 renewal_window_expired` após `consent.renewable_until`. Caso contrário, responde `201` com um link de renovação.

A página em que a pessoa conclui a renovação ainda não está disponível, então não envie as pessoas para um link de renovação por enquanto.

Se a pessoa deixar o consentimento expirar, a conexão passa para `renewal_required`: os dados permanecem acessíveis como estavam na última sincronização e nada é cobrado.
Após `consent.renewable_until`, ela passa para `revoked` com `status_reason: consent_lapsed`, e a pessoa se conecta novamente.

Para o fluxo completo, veja [Renovar um consentimento bancário](https://docs.didit.me/pt-br/use-cases/renew-bank-consent.md).

## Interromper o acesso

| Quem | Como | O que acontece |
| - | - | - |
| A pessoa | **Stop sharing** no banco dela | `bank.connection.revoked` com `ended_by: end_user` ou `bank` |
| Você | [`revoke_connection`](https://docs.didit.me/pt-br/standalone-apis/bank-connection-revoke) | As buscas do banco são interrompidas imediatamente. O consentimento fica com `revocation_pending` e passa para `revoked` quando o banco confirma. Os dados já lidos continuam legíveis até você excluir a conexão ou até que `consent.retain_until` passe. |
| Você | [`delete_connection`](https://docs.didit.me/pt-br/standalone-apis/bank-connection-delete) | Interrompe o acesso e exclui a conexão, junto com suas contas, saldos e transações. Irreversível. |

Interromper o acesso não é excluir.
Leia [Dados, consentimento e exclusão](https://docs.didit.me/pt-br/core-technology/bank-verification/data-consent-and-deletion.md) para saber exatamente o que a exclusão remove.

## Uma conexão excluída

Uma conexão excluída responde apenas `id`, `status` (`deleted`), `status_reason`, `created_at` e `erasure`.
`status_reason` é `deleted_by_customer`, `consent_lapsed`, `retention_elapsed` ou `application_deleted`.
Todos os outros campos estão ausentes.

## Duplicados

Um novo link que resolve exatamente para as contas que você já compartilha com o mesmo `end_user.reference` no mesmo banco é concluído como uma renovação dessa conexão (`reused: true`) e não cobra duas vezes.
Qualquer outra sobreposição encerra o link com `failed`, `duplicate_conflict` e `conflicts_with`, antes que qualquer coisa seja armazenada ou cobrada.
Renove a conexão existente ou crie o link novamente com `"duplicates": "allow"` para uma segunda conexão independente.

## Gerencie as conexões dos seus clientes

* Listagem com filtros: [`GET /v3/bank/connections/`](https://docs.didit.me/pt-br/standalone-apis/bank-connections-list) aceita `status`, `access`, `institution_id`, `country`, `vendor_data`, `end_user_reference`, `consent_expires_before` e `created_after`.
* Veja quanto custa cada conexão com o objeto `billing`: a unidade, o preço e o mês já liquidado.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.