> ## 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.

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

> Uma ligação é a permissão de uma pessoa para ler um banco. Veja os estados, como o consentimento termina, como renová-lo ou revogar o acesso na Didit.

Uma conexão bancária da Didit é a permissão de uma pessoa ou empresa para que a sua aplicação leia os dados de um banco, com as respetivas datas de consentimento, o estado de sincronização e as contas.
Uma [Bank Link](https://docs.didit.me/pt/core-technology/bank-verification/bank-link.md) concluída cria a conexão, que se mantém durante o período permitido pelo banco e pela pessoa.

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

## Acesso pontual e contínuo

| | Pontual | Contínuo |
| - | - | - |
| `access` | `one_time` (predefinição) | `ongoing` |
| O que acontece | Os dados são lidos uma vez quando a pessoa se liga e, depois, o acesso termina (`status_reason: collection_complete`). | O acesso mantém-se aberto até que o consentimento termine ou alguém o interrompa. |
| Dados depois | Legíveis através dos mesmos endpoints. | Sincronizados automaticamente entre uma e quatro vezes por dia, consoante o banco, além de sincronizações em tempo real a pedido. |
| Faturação | Por verificação, ver [preços](https://docs.didit.me/pt/getting-started/bank-verification-pricing.md) | Por ligação ativa por mês, ver [preços](https://docs.didit.me/pt/getting-started/bank-verification-pricing.md) |

O acesso contínuo só funciona num banco quando esse banco o permite.
Consulte o [endpoint de instituições](https://docs.didit.me/pt/standalone-apis/bank-institutions-list.md) ou leia a [página de cobertura](https://docs.didit.me/pt/core-technology/bank-verification/coverage.md).
Quando um banco não pode manter o acesso aberto, a pessoa é informada de que o banco não permite acesso contínuo e de que tem de escolher outro banco.
Defina `allow_one_time_fallback: true` para permitir que a pessoa continue com uma leitura pontual depois de confirmar o acesso reduzido no seu próprio ecrã: a ligação fica então `one_time`.

## Estados

| `status` | Significado | Dados legíveis | Sincronizações | Faturado |
| - | - | - | - | - |
| `pending` | A ligação foi concluída e a primeira sincronização está em curso. | Ainda não | Em curso | Não |
| `active` | O consentimento é válido e a sincronização está a funcionar corretamente ou a tentar novamente. | Sim | Sim | Sim |
| `renewal_required` | O consentimento terminou, ou o banco pede à pessoa que volte a iniciar sessão. `status_reason` indica qual. | Conforme a última sincronização | Não | Não |
| `paused` | O saldo não é suficiente para cobrir o mês. | Conforme a última sincronização | Não | Não |
| `revoked` | O acesso foi interrompido pela pessoa, pelo banco ou por si. `consent.ended_by` indica quem. | Até `consent.retain_until` | Não | Não |
| `deleted` | A ligação e os respetivos dados foram eliminados. | Não | Não | Não |
| `failed` | A primeira sincronização nunca foi concluída com êxito. | Não | Não | Não |

Os valores de `status_reason` são `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é ao valor de `consent_days` que pediu.
Cada ligação mostra as datas reais em `consent`:

* `expires_at` e `renew_by`: o fim do consentimento. Renove antes desse momento para não haver interrupção.
* `renewable_until`: o último momento em que a mesma ligação pode ser reativada após o fim do consentimento.
* `renewed_count`, `version`, `scopes_granted` e `accounts_granted`: o que foi concedido e quantas vezes foi renovado o consentimento.

O consentimento dura o tempo que o banco permitir.
Leia o valor real em cada ligação e o valor específico de cada banco na instituição.

## Renovação

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

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/standalone-apis/bank-connection-renew). Responde com `409 renewal_not_needed` enquanto restarem mais de 30 dias e com `409 renewal_window_expired` depois de `consent.renewable_until`. Caso contrário, responde com `201` e uma ligação de renovação.

A página onde a pessoa conclui uma renovação ainda não está disponível, por isso não envie as pessoas para uma ligação de renovação neste momento.

Se a pessoa deixar o consentimento expirar, a ligação passa para `renewal_required`: os dados continuam legíveis tal como foram sincronizados pela última vez, e não é cobrado nada.
Depois de `consent.renewable_until`, a ligação fica `revoked` com `status_reason: consent_lapsed`, e a pessoa tem de voltar a estabelecer a ligação.

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

## Interromper o acesso

| Quem | Como | O que acontece |
| - | - | - |
| A pessoa | **Deixar de partilhar** no banco | `bank.connection.revoked` com `ended_by: end_user` ou `bank` |
| Você | [`revoke_connection`](https://docs.didit.me/pt/standalone-apis/bank-connection-revoke) | A obtenção de dados do banco é interrompida de imediato. O consentimento passa a `revocation_pending` e, depois, a `revoked` quando o banco confirma. Os dados já lidos continuam acessíveis até eliminar a ligação ou até `consent.retain_until` ser ultrapassado. |
| Você | [`delete_connection`](https://docs.didit.me/pt/standalone-apis/bank-connection-delete) | Interrompe o acesso e elimina a ligação, bem como as respetivas contas, saldos e transações. Irreversível. |

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

## Uma ligação eliminada

Uma ligação eliminada devolve apenas `id`, `status` (`deleted`), `status_reason`, `created_at` e `erasure`.
`status_reason` é `deleted_by_customer`, `consent_lapsed`, `retention_elapsed` ou `application_deleted`.
Nenhum outro campo está presente.

## Duplicados

Uma nova ligação que resolve exatamente para as contas que já partilha com o mesmo `end_user.reference` no mesmo banco é concluída como uma renovação dessa conexão (`reused: true`), sem qualquer cobrança duplicada.
Qualquer outra sobreposição termina a ligação com `failed` e `duplicate_conflict` e `conflicts_with`, antes de qualquer informação ser armazenada ou de ser efetuada qualquer cobrança.
Renove a conexão existente ou crie novamente a ligação com `"duplicates": "allow"` para obter uma segunda conexão independente.

## Gerir as ligações dos seus clientes

* Listar com filtros: [`GET /v3/bank/connections/`](https://docs.didit.me/pt/standalone-apis/bank-connections-list) aceita `status`, `access`, `institution_id`, `country`, `vendor_data`, `end_user_reference`, `consent_expires_before` e `created_after`.
* Veja o custo de uma ligação com o seu 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.