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

# API para obter uma ligação bancária: consentimento, sincronização e contas

> A Didit devolve uma ligação bancária com o estado, as datas de consentimento, a sincronização, o resumo das contas e o custo.

O endpoint de obtenção de uma ligação bancária da Didit devolve uma ligação com o respetivo estado, as datas de consentimento, o estado de sincronização, os resumos das contas e o custo.
`sync.initial_status` indica-lhe quando os primeiros dados ficam disponíveis para leitura, `consent.expires_at` indica-lhe quando renovar e `sync.budgets` indica quantas atualizações o banco ainda permite.
Consulte [Ligações](https://docs.didit.me/pt/core-technology/bank-verification/connections.md).


## OpenAPI

````yaml pt/openapi-25.json GET /v3/bank/connections/{id}/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de verificação de identidade. Autentique-se com o cabeçalho x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      Bank Link, ligações, contas, saldos, transações, instituições e cobertura.
      Os dados bancários estão disponíveis para aplicações sandbox. As chamadas
      de uma aplicação de produção respondem com `404` até ao acesso em produção
      ser anunciado. Nada é cobrado no sandbox. Uma chamada feita com uma chave
      de API precisa de uma chave que tenha a permissão de dados bancários
      (`bank-data`): leitura para as leituras, escrita para as operações que
      alteram algo. A verificação de conta é a exceção: precisa de acesso de
      escrita a sessões, ou de acesso total, e não da permissão de dados
      bancários. Os dados bancários não fazem parte do acesso total: uma chave
      de acesso total é recusada, e a chamada responde com `403
      bank_data_access_denied` até criar uma chave que tenha a permissão. Os
      dados bancários em bruto (contas, saldos, transações e o feed de
      alterações) também recusam um pedido que não traga uma chave de API.


      Todas as recusas em `/v3/bank/`, exceto as da verificação de conta, têm o
      mesmo corpo JSON (`code`, `message`, `request_id`, `field`, `next_action`,
      `retry_after`). Um caminho que não é uma operação, um ID que não é um UUID
      ou um sub-recurso desconhecido responde com `404 not_found` em todos os
      métodos, e qualquer erro inesperado responde com `500 internal_error` com
      um `request_id`. Quando os dados bancários não estão disponíveis, todas as
      operações respondem com o `404` padrão da plataforma, exatamente como uma
      rota desconhecida.
paths:
  /v3/bank/connections/{id}/:
    get:
      tags:
        - Bank Data
      summary: Obter uma ligação bancária
      description: >-
        Devolve a ligação com o respetivo consentimento, estado de sincronização
        e um resumo de cada conta. Leia os próprios dados com as operações de
        contas, saldos e transações. Uma ligação eliminada é devolvida como um
        registo mínimo: o seu id, `status: deleted`, o motivo, as datas e o
        estado de `erasure`, e sem contas, saldos, transações, consentimento ou
        dados de sincronização.


        É necessária uma chave de API com a permissão Dados bancários
        (`bank-data`): leitura para esta operação. Uma chave com acesso total
        não inclui esta permissão: atribua-a explicitamente ao criar a chave,
        caso contrário a chamada responde com `403 bank_data_access_denied`.
      operationId: getBankConnection
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: O id da ligação.
      responses:
        '200':
          description: A ligação.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankConnection'
              examples:
                Active ongoing connection:
                  summary: Uma ligação empresarial contínua ativa
                  value:
                    id: 5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35
                    environment: live
                    access: ongoing
                    status: active
                    status_reason: null
                    institution:
                      id: es-banco-norte
                      name: Banco Norte
                      country: ESP
                      logo_url: https://static.example.com/banks/es-banco-norte.png
                    segment: business
                    data:
                      - accounts
                      - balances
                      - transactions
                    consent:
                      status: granted
                      version: 1
                      granted_at: '2026-11-21T12:04:11Z'
                      expires_at: '2027-05-20T12:04:11Z'
                      days_granted: 180
                      renewed_count: 0
                      scopes_requested:
                        - accounts
                        - balances
                        - transactions
                      scopes_granted:
                        - accounts
                        - balances
                        - transactions
                      accounts_granted:
                        - a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                        - c3d84e19-2a7b-4f60-b5e1-9a0c6d3f8e72
                      renewal_action: bank_auth
                      renew_by: '2027-05-20T12:04:11Z'
                      reconfirm_by: null
                      renewable_until: null
                      retain_until: null
                      ended_at: null
                      ended_by: null
                    sync:
                      status: ok
                      initial_status: succeeded
                      initial_complete: true
                      history_complete: true
                      last_synced_at: '2026-11-21T12:04:40Z'
                      next_sync_at: '2026-11-22T06:00:00Z'
                      budgets:
                        - scope: connection
                          resource: all
                          limit: 4
                          remaining: 3
                          resets_at: '2026-11-22T00:00:00Z'
                      last_error: null
                      frequency_per_day: 1
                      live_syncs_left_today: 3
                    accounts:
                      - id: a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                        name: Cuenta negocio
                        type: current
                        usage: business
                        currency: EUR
                        iban_last4: '1332'
                        status: open
                      - id: c3d84e19-2a7b-4f60-b5e1-9a0c6d3f8e72
                        name: Cuenta de ahorro
                        type: savings
                        usage: business
                        currency: EUR
                        iban_last4: '7708'
                        status: open
                    ownership:
                      compare: none
                      match: null
                      check_id: null
                      result: null
                    end_user:
                      reference: client-7731
                    manage_url: null
                    billing:
                      unit: connection_month
                      price_usd: '0.9000'
                      billed_through: '2026-11-30'
                    possible_duplicate_of: null
                    erasure: null
                    vendor_data: client-7731
                    created_at: '2026-11-21T12:03:02Z'
                    updated_at: '2026-11-21T12:04:40Z'
                Renewal required:
                  summary: >-
                    O consentimento terminou; os dados continuam legíveis tal
                    como foram sincronizados pela última vez
                  value:
                    id: 5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35
                    environment: live
                    access: ongoing
                    status: renewal_required
                    status_reason: consent_expired
                    institution:
                      id: es-banco-norte
                      name: Banco Norte
                      country: ESP
                      logo_url: https://static.example.com/banks/es-banco-norte.png
                    segment: business
                    data:
                      - accounts
                      - balances
                      - transactions
                    consent:
                      status: expired
                      version: 1
                      granted_at: '2026-11-21T12:04:11Z'
                      expires_at: '2027-05-20T12:04:11Z'
                      days_granted: 180
                      renewed_count: 0
                      scopes_requested:
                        - accounts
                        - balances
                        - transactions
                      scopes_granted:
                        - accounts
                        - balances
                        - transactions
                      accounts_granted:
                        - a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                        - c3d84e19-2a7b-4f60-b5e1-9a0c6d3f8e72
                      renewal_action: bank_auth
                      renew_by: '2027-05-20T12:04:11Z'
                      reconfirm_by: null
                      renewable_until: '2027-06-19T12:04:11Z'
                      retain_until: '2027-06-19T12:04:11Z'
                      ended_at: '2027-05-20T12:04:11Z'
                      ended_by: bank
                    sync:
                      status: ok
                      initial_status: succeeded
                      initial_complete: true
                      history_complete: true
                      last_synced_at: '2026-11-21T12:04:40Z'
                      next_sync_at: '2026-11-22T06:00:00Z'
                      budgets:
                        - scope: connection
                          resource: all
                          limit: 4
                          remaining: 3
                          resets_at: '2026-11-22T00:00:00Z'
                      last_error: null
                      frequency_per_day: 1
                      live_syncs_left_today: 3
                    accounts:
                      - id: a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                        name: Cuenta negocio
                        type: current
                        usage: business
                        currency: EUR
                        iban_last4: '1332'
                        status: open
                      - id: c3d84e19-2a7b-4f60-b5e1-9a0c6d3f8e72
                        name: Cuenta de ahorro
                        type: savings
                        usage: business
                        currency: EUR
                        iban_last4: '7708'
                        status: open
                    ownership:
                      compare: none
                      match: null
                      check_id: null
                      result: null
                    end_user:
                      reference: client-7731
                    manage_url: null
                    billing:
                      unit: connection_month
                      price_usd: '0.9000'
                      billed_through: '2026-11-30'
                    possible_duplicate_of: null
                    erasure: null
                    vendor_data: client-7731
                    created_at: '2026-11-21T12:03:02Z'
                    updated_at: '2026-11-21T12:04:40Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BankDataAccessDenied'
        '404':
          description: O recurso não existe nesta aplicação e neste ambiente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not found:
                  summary: Não encontrado
                  value:
                    code: not_found
                    message: The resource does not exist.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: null
                    retry_after: null
        '429':
          $ref: '#/components/responses/RateLimitedRead'
        '500':
          $ref: '#/components/responses/BankDataInternalError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            curl
            'https://verification.didit.me/v3/bank/connections/5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35/'
            \
              -H 'x-api-key: YOUR_API_KEY'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.bank.get_connection(
                "11111111-2222-3333-4444-555555555555",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: >-
            import Didit from "@didit-protocol/sdk-node";


            // Reads DIDIT_API_KEY.

            const didit = new Didit();


            const result = await
            didit.bank.getConnection("11111111-2222-3333-4444-555555555555");

            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.GetConnection(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.bank().getConnection("11111111-2222-3333-4444-555555555555");

            System.out.println(result);
        - lang: php
          label: PHP
          source: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            $result =
            $didit->bank->getConnection('11111111-2222-3333-4444-555555555555');

            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: >-
            require "didit"


            # Reads DIDIT_API_KEY.

            didit = Didit::Client.new


            result =
            didit.bank.get_connection("11111111-2222-3333-4444-555555555555")

            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await
            client.Bank.GetConnectionAsync("11111111-2222-3333-4444-555555555555");

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    BankConnection:
      type: object
      description: >-
        A permissão da pessoa para a sua aplicação ler um banco. Uma renovação
        mantém o id da conexão e todos os ids de conta. Uma conexão eliminada
        responde apenas com `id`, `status`, `status_reason`, `created_at` e
        `erasure`: todos os outros campos estão ausentes, e não permanece nela
        nenhum dado do banco, da pessoa ou da conta.
      properties:
        id:
          type: string
          description: Identificador da ligação bancária.
          format: uuid
        environment:
          type: string
          enum:
            - live
            - sandbox
        access:
          type: string
          enum:
            - one_time
            - ongoing
        status:
          type: string
          enum:
            - pending
            - active
            - renewal_required
            - paused
            - revoked
            - deleted
            - failed
          description: >-
            `pending`: primeira sincronização em curso. `active`: consentimento
            válido. `renewal_required`: o consentimento terminou ou o banco quer
            que a pessoa volte a iniciar sessão; os dados podem ser lidos tal
            como na última sincronização, e nada é cobrado. `paused`: saldo
            insuficiente para o mês. `revoked`: acesso interrompido pela pessoa,
            pelo banco ou por si. `deleted`: restam apenas `id`, `status`,
            `status_reason`, `created_at` e `erasure`. `failed`: a primeira
            sincronização nunca teve êxito.
        status_reason:
          type: string
          enum:
            - 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
            - first_sync_failed
            - deleted_by_customer
            - retention_elapsed
            - application_deleted
            - null
          description: >-
            Motivo pelo qual a conexão se encontra neste estado.
            `paused_by_customer` está reservado. Numa conexão `deleted`:
            `deleted_by_customer`, `consent_lapsed`, `retention_elapsed` ou
            `application_deleted`.
          nullable: true
        institution:
          $ref: '#/components/schemas/BankInstitutionSummary'
        segment:
          type: string
          enum:
            - personal
            - business
            - null
          nullable: true
        data:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: Os âmbitos que a pessoa aceitou.
        consent:
          $ref: '#/components/schemas/BankConnectionConsent'
        sync:
          $ref: '#/components/schemas/BankConnectionSync'
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/BankConnectionAccountSummary'
          description: >-
            Resumo de todas as contas da conexão. Leia a conta completa com
            `get_account`.
        ownership:
          $ref: '#/components/schemas/BankConnectionOwnership'
        end_user:
          type: object
          properties:
            reference:
              type: string
              description: O seu id para a pessoa ou empresa.
              nullable: true
          required:
            - reference
        manage_url:
          type: string
          description: >-
            A página de acesso própria da pessoa. `null` até a página de acesso
            estar disponível.
          nullable: true
          format: uri
        billing:
          $ref: '#/components/schemas/BankConnectionBilling'
        possible_duplicate_of:
          type: string
          description: >-
            Definido quando esta ligação pode duplicar outra ligação ativa, mas
            nenhuma referência de `end_user.reference` permitiu confirmar uma
            correspondência.
          format: uuid
          nullable: true
        erasure:
          allOf:
            - $ref: '#/components/schemas/BankConnectionErasure'
          nullable: true
          description: Definido após `delete_connection`; caso contrário, `null`.
        vendor_data:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - status
        - status_reason
        - created_at
        - erasure
    BankDataError:
      type: object
      description: >-
        Corpo de erro de todas as operações de Dados bancários. Todos os campos
        estão sempre presentes.
      properties:
        code:
          type: string
          enum:
            - ongoing_access_not_available
            - segment_not_available
            - window_not_available
            - history_window_ambiguous
            - redirect_url_not_registered
            - link_origin_not_allowed
            - bank_data_access_denied
            - connection_not_active
            - consent_expired
            - renewal_not_needed
            - renewal_window_expired
            - access_removed
            - refresh_limit_reached
            - cursor_expired
            - page_expired
            - invalid_cursor
            - page_token_mismatch
            - contract_rate_missing
            - insufficient_credits
            - invalid_request
            - not_found
            - internal_error
          description: >-
            Código de erro legível por máquina. Baseie as decisões neste valor,
            nunca em `message`.
        message:
          type: string
          description: >-
            Explicação em linguagem simples para um programador. A redação pode
            mudar; não a analise.
        request_id:
          type: string
          description: Identificador deste pedido. Indique-o quando contactar o suporte.
        field:
          type: string
          description: >-
            O campo do pedido a corrigir, quando o erro diz respeito a um campo.
            Caso contrário, `null`.
          nullable: true
        next_action:
          type: string
          enum:
            - retry_later
            - renew_connection
            - create_link
            - restart_from_cursor
            - restart_read
            - top_up_balance
            - enable_bank_data_access
            - contact_support
            - null
          description: >-
            O que fazer a seguir, para que um cliente possa agir sem adivinhar.
            `null` quando não há um passo seguinte padrão.
          nullable: true
        retry_after:
          type: integer
          description: >-
            Segundos a aguardar antes de tentar novamente. Definido em erros de
            limite de pedidos e erros temporários; caso contrário, `null`.
          nullable: true
      required:
        - code
        - message
        - request_id
        - field
        - next_action
        - retry_after
      example:
        code: ongoing_access_not_available
        message: >-
          This bank cannot keep access open. Use access one_time or choose
          another bank.
        request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
        field: institution_id
        next_action: create_link
        retry_after: null
    BankInstitutionSummary:
      type: object
      description: O banco a que se destina uma ligação ou uma hiperligação.
      properties:
        id:
          type: string
          description: >-
            Identificador da Didit para o banco, um slug estável. Use-o como
            `institution_id`.
          example: es-banco-norte
        name:
          type: string
          description: O nome do banco.
          example: Banco Norte
        country:
          type: string
          description: País do banco, ISO 3166-1 alfa-3.
          pattern: ^[A-Z]{3}$
          example: ESP
        logo_url:
          type: string
          description: Logótipo do banco, ou `null`.
          nullable: true
          format: uri
      required:
        - id
        - name
        - country
        - logo_url
    BankConnectionConsent:
      type: object
      description: O consentimento da pessoa para esta conexão.
      properties:
        status:
          type: string
          enum:
            - granted
            - expired
            - revocation_pending
            - revoked
            - revocation_failed
          description: >-
            `revocation_pending` até ao banco confirmar que o consentimento foi
            terminado, e depois `revoked`. `revocation_failed` é tentado
            novamente de forma automática. As recolhas de dados do banco param
            no momento em que é pedida uma revogação.
        version:
          type: integer
          description: >-
            Versão do consentimento. Uma renovação cria a versão seguinte na
            mesma conexão.
        granted_at:
          type: string
          format: date-time
          nullable: true
        expires_at:
          type: string
          description: >-
            Quando termina o consentimento do banco. Quem o define é o banco,
            até `consent_days`.
          format: date-time
          nullable: true
        days_granted:
          type: integer
          description: Duração do consentimento em dias, tal como o banco a concedeu.
          nullable: true
        renewed_count:
          type: integer
          description: Quantas vezes o consentimento foi renovado.
        scopes_requested:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
        scopes_granted:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
        accounts_granted:
          type: array
          items:
            type: string
            format: uuid
          description: IDs das contas que a pessoa partilha.
        renewal_action:
          type: string
          enum:
            - reconfirm
            - bank_auth
            - null
          description: >-
            Forma como funciona uma renovação: `reconfirm` é a pessoa a
            confirmar no ecrã da Didit, sem iniciar sessão no banco, quando o
            banco e as regras do país o permitem. `bank_auth` é um início de
            sessão no banco.
          nullable: true
        renew_by:
          type: string
          description: 'O fim do consentimento: renove antes para não haver interrupção.'
          format: date-time
          nullable: true
        reconfirm_by:
          type: string
          description: >-
            Definido quando `renewal_action` é `reconfirm`: o último momento
            para reconfirmar.
          format: date-time
          nullable: true
        renewable_until:
          type: string
          description: >-
            O último momento em que a mesma ligação pode ser reativada após o
            fim do consentimento. Depois disso, a pessoa liga-se novamente.
            Corresponde a `retain_until`.
          format: date-time
          nullable: true
        retain_until:
          type: string
          description: >-
            Definido quando o acesso termina: durante quanto tempo os dados
            guardados continuam legíveis, conforme a configuração de retenção da
            sua aplicação.
          format: date-time
          nullable: true
        ended_at:
          type: string
          format: date-time
          nullable: true
        ended_by:
          type: string
          enum:
            - end_user
            - bank
            - customer
            - unknown
            - null
          description: >-
            Quem terminou o acesso, definido com base em provas. `unknown`
            quando nem o banco nem a sincronização o indicam.
          nullable: true
      required:
        - status
        - version
        - granted_at
        - expires_at
        - days_granted
        - renewed_count
        - scopes_requested
        - scopes_granted
        - accounts_granted
        - renewal_action
        - renew_by
        - reconfirm_by
        - renewable_until
        - retain_until
        - ended_at
        - ended_by
    BankConnectionSync:
      type: object
      description: Estado de sincronização de uma conexão.
      properties:
        status:
          type: string
          enum:
            - pending
            - ok
            - failing
          description: >-
            `failing` após 24 horas de tentativas falhadas, que são repetidas
            com recuo progressivo. Um banco que pede à pessoa que volte a
            iniciar sessão faz com que a conexão fique em `renewal_required`.
        initial_status:
          type: string
          enum:
            - pending
            - succeeded
            - partial
            - failed
          description: >-
            Resultado da primeira sincronização. A ligação passa a `active` com
            `succeeded` ou `partial`, e passa a `failed` quando nenhuma conta
            for bem-sucedida.
        initial_complete:
          type: boolean
          description: >-
            `true` apenas quando `initial_status` for `succeeded`: as contas, os
            saldos e as transações recentes podem ser consultados.
        history_complete:
          type: boolean
          description: >-
            `true` quando a obtenção do histórico terminou, por qualquer motivo.
            Os intervalos que não foi possível obter estão em
            `history_coverage.missing_ranges` de cada conta.
        last_synced_at:
          type: string
          description: >-
            Quando os dados foram obtidos pela última vez do banco, não quando
            os leu pela última vez.
          format: date-time
          nullable: true
        next_sync_at:
          type: string
          description: >-
            Quando está planeada a próxima sincronização automática. A
            sincronização automática é executada entre uma e quatro vezes por
            dia, consoante o banco (ver `frequency_per_day`).
          format: date-time
          nullable: true
        budgets:
          type: array
          items:
            $ref: '#/components/schemas/BankSyncBudget'
          description: Os limites do banco para obtenções sem a pessoa presente.
        last_error:
          allOf:
            - $ref: '#/components/schemas/BankSyncError'
          nullable: true
          description: O último erro de sincronização, ou `null`.
        frequency_per_day:
          type: integer
          minimum: 1
          maximum: 4
          description: >-
            Quantas vezes por dia a sincronização automática é executada para
            esta ligação, entre uma e quatro, consoante o banco. Quando o banco
            permite mais leituras sem a presença da pessoa, mantêm-se sempre
            pelo menos duas por dia para sincronizações em tempo real.
        live_syncs_left_today:
          type: integer
          minimum: 0
          description: >-
            Quantas sincronizações em tempo real (`refresh_connection`) restam
            hoje dentro do limite do banco: o `remaining` do orçamento mais
            restrito. `null` quando o banco não define limite. As sincronizações
            em tempo real estão incluídas no preço mensal.
          nullable: true
      required:
        - status
        - initial_status
        - initial_complete
        - history_complete
        - last_synced_at
        - next_sync_at
        - budgets
        - last_error
        - frequency_per_day
        - live_syncs_left_today
    BankConnectionAccountSummary:
      type: object
      description: Forma abreviada de uma conta dentro de uma ligação bancária.
      properties:
        id:
          type: string
          description: >-
            ID da conta. Estável durante toda a vida da ligação, incluindo as
            renovações.
          format: uuid
        name:
          type: string
          nullable: true
        type:
          type: string
          enum:
            - current
            - savings
            - card
            - loan
            - investment
            - other
        usage:
          type: string
          enum:
            - personal
            - business
            - unknown
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: Código de moeda ISO 4217.
        iban_last4:
          type: string
          description: Últimos quatro caracteres do IBAN, quando a conta o tiver.
          nullable: true
        status:
          type: string
          enum:
            - open
            - closed
            - access_removed
      required:
        - id
        - name
        - type
        - usage
        - currency
        - iban_last4
        - status
    BankConnectionOwnership:
      type: object
      description: A comparação opcional do titular da conta com uma pessoa ou empresa.
      properties:
        compare:
          type: string
          enum:
            - none
            - person
            - business
        match:
          type: string
          enum:
            - any_holder
            - all_holders
            - null
          nullable: true
        check_id:
          type: string
          description: ID do resultado de propriedade, quando foi pedida uma comparação.
          format: uuid
          nullable: true
        result:
          type: string
          enum:
            - match
            - close_match
            - no_match
            - unknown
            - null
          description: >-
            Veredito. `unknown` sempre que provas em falta sobre o titular
            possam alterá-lo, e quando o banco não partilha os dados do titular.
          nullable: true
      required:
        - compare
        - match
        - check_id
        - result
    BankConnectionBilling:
      type: object
      description: Quanto custa esta conexão. O sandbox nunca é cobrado.
      properties:
        unit:
          type: string
          description: >-
            Unidade de faturação: `connection_month` para o acesso contínuo,
            `one_time` nos restantes casos.
          enum:
            - connection_month
            - one_time
        price_usd:
          type: string
          description: >-
            O seu preço atual para o contador mensal, para a sua aplicação e o
            país, em USD, uma cadeia decimal com 4 casas decimais. Uma conexão é
            cobrada por um mês apenas quando cada âmbito aceite publicou dados
            de pelo menos uma conta nesse mês. `null` para conexões pontuais e
            no sandbox. O acesso contínuo é faturado por conexão ativa por mês;
            o preço atual está na página de preços
            (https://docs.didit.me/getting-started/pricing). Os valores nos
            exemplos são ilustrativos; o preço de um país é apresentado na
            página de preços.
          pattern: ^-?\d+(\.\d+)?$
          nullable: true
        billed_through:
          type: string
          description: O último fim de mês já liquidado.
          format: date
          nullable: true
      required:
        - unit
        - price_usd
        - billed_through
    BankConnectionErasure:
      type: object
      description: Progresso de uma eliminação que pediu.
      properties:
        status:
          type: string
          enum:
            - pending
            - erased
            - failed
          description: >-
            `pending` enquanto a eliminação decorre, `erased` quando não resta
            nenhuma cópia armazenada nem acesso no banco, `failed` quando não
            puder ser confirmada no prazo de 24 horas. Uma eliminação falhada
            mantém os dados da conexão encerrados, é repetida, e a Didit recebe
            um alerta.
        requested_at:
          type: string
          format: date-time
        erased_at:
          type: string
          format: date-time
          nullable: true
          description: Quando a eliminação terminou. `null` até `status` ser `erased`.
      required:
        - status
        - requested_at
        - erased_at
    RateLimitBudgetError:
      type: object
      description: >-
        Devolvido apenas numa recusa de orçamento de limite de pedidos do
        middleware. Outros erros 429, incluindo conflitos de idempotência e
        limites específicos de cada endpoint, não garantem estes campos de
        metadados.
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: Mensagem de recusa por orçamento já existente, legível por humanos.
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: >-
            Referência de suporte opaca: RL- seguido de 32 caracteres
            hexadecimais de UUID em minúsculas.
        limit:
          type: integer
          description: Orçamento do âmbito excedido; igual a X-RateLimit-Limit.
        remaining:
          type: integer
          minimum: 0
          description: Orçamento restante, limitado a zero; igual a X-RateLimit-Remaining.
        reset:
          type: integer
          format: int64
          description: >-
            Hora de reposição da janela em segundos Unix; é igual a
            X-RateLimit-Reset.
        window_seconds:
          type: integer
          description: >-
            Duração da janela fixa em segundos, não o tempo de espera restante.
            Respeite Retry-After antes de tentar novamente.
      example:
        detail: >-
          Write request rate limit exceeded. You can make up to 300 requests per
          minute.
        reference: RL-00000000000040008000000000000001
        limit: 300
        remaining: 0
        reset: 1794358860
        window_seconds: 60
    BankSyncBudget:
      type: object
      description: >-
        Um escalão do limite do banco para obtenções de dados sem a presença da
        pessoa.
      properties:
        scope:
          type: string
          enum:
            - connection
            - account
          description: Contra o que o banco contabiliza o orçamento.
        resource:
          type: string
          enum:
            - all
            - accounts
            - balances
            - transactions
        account_id:
          type: string
          description: A conta, quando `scope` é `account`.
          format: uuid
          nullable: true
        limit:
          type: integer
          description: >-
            Quantas vezes por dia a Didit pode obter dados do banco sem a
            presença da pessoa, tal como o banco o define. Trata-se de um teto
            definido pelo banco, não de uma garantia.
        remaining:
          type: integer
          description: >-
            Leituras restantes para as suas atualizações na janela atual. As
            leituras reservadas para as sincronizações automáticas já foram
            descontadas, e uma sincronização automática nunca utiliza as duas
            últimas leituras do dia, pelo que ficam sempre disponíveis duas
            atualizações a pedido.
        resets_at:
          type: string
          description: Quando a janela é reiniciada.
          format: date-time
      required:
        - scope
        - resource
        - limit
        - remaining
        - resets_at
    BankSyncError:
      type: object
      description: Motivo pelo qual uma sincronização falhou.
      properties:
        code:
          type: string
          description: Código de erro da Didit.
        message:
          type: string
          description: Explicação em linguagem simples.
        at:
          type: string
          description: Quando aconteceu. `null` num resultado por conta.
          format: date-time
          nullable: true
      required:
        - code
        - message
        - at
  responses:
    Unauthorized:
      description: Não autorizado
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: Chave de API inválida
              value:
                detail: Invalid API Key.
    BankDataAccessDenied:
      description: >-
        A chave de API não tem a permissão Dados bancários (`bank-data`) ou, no
        caso de dados bancários em bruto numa aplicação em produção, a definição
        da aplicação "Bank data in the API" está desativada. Os dados bancários
        não fazem parte do acesso total: uma chave com acesso total, uma chave
        restrita a outros recursos e um pedido autenticado sem chave de API
        (credenciais de cliente, para dados em bruto) são todos recusados com
        este corpo de resposta. Crie uma chave e atribua-lhe a permissão
        explicitamente. A recusa acontece antes de qualquer pesquisa, por isso
        não indica se o objeto existe.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Bank data not allowed:
              summary: Dados bancários não permitidos
              value:
                code: bank_data_access_denied
                message: >-
                  Bank data calls need an API key that carries the Bank data
                  permission.
                request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                field: null
                next_action: enable_bank_data_access
                retry_after: null
    RateLimitedRead:
      description: >-
        Orçamento de leitura do middleware excedido. Respeite Retry-After antes
        de tentar novamente.
      headers:
        Retry-After:
          $ref: '#/components/headers/BudgetRetryAfter'
        X-RateLimit-Scope:
          $ref: '#/components/headers/BudgetXRateLimitScope'
        X-RateLimit-Limit:
          $ref: '#/components/headers/BudgetXRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/BudgetXRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/BudgetXRateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitBudgetError'
          example:
            detail: >-
              GET request rate limit exceeded. You can make up to 600 requests
              per minute.
            reference: RL-00000000000040008000000000000001
            limit: 600
            remaining: 0
            reset: 1794358860
            window_seconds: 60
    BankDataInternalError:
      description: >-
        Algo correu mal do lado da Didit. Qualquer erro inesperado em
        `/v3/bank/` responde no formato de erro do Bank, nunca com uma página
        HTML: indique o `request_id` ao suporte.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: Um erro inesperado
              value:
                code: internal_error
                message: >-
                  Something went wrong on our side. Quote the request_id to
                  support.
                request_id: 3f6a1c8e92b54d07a1e38c4b7f0d2e59
                field: null
                next_action: contact_support
                retry_after: null
  headers:
    BudgetRetryAfter:
      description: >-
        Segundos a aguardar, arredondados por excesso para a janela seguinte.
        Presente nas recusas de orçamento do middleware.
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: >-
        O âmbito cujo orçamento foi excedido. Presente nas recusas de orçamento
        do middleware.
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: >-
        Orçamento do âmbito excedido; igual ao limite do corpo. Presente nas
        recusas por orçamento do middleware.
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: >-
        Orçamento restante, limitado a zero; igual a remaining do corpo.
        Presente nas recusas por orçamento do middleware.
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: >-
        Hora de reposição em segundos Unix; é igual a reset no corpo. Presente
        nas recusas de orçamento do middleware.
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        A chave de API da sua aplicação, obtida em Developers -> API keys na
        Business Console. A chave principal tem acesso total. Uma chave com nome
        pode ter o âmbito limitado: nenhum, leitura ou escrita por recurso,
        limitada a alguns fluxos ou apenas a sessões aprovadas, a uma lista de
        endereços IP e a uma data de validade. 401 significa que a chave está
        errada, revogada ou expirada; 403 significa que não foi enviada nenhuma
        chave, que a chave não tem acesso a este recurso ou ação, ou que o
        pedido veio de um endereço fora da sua lista de IP; 404 numa rota de
        sessão significa que a sessão está fora dos fluxos ou estados da chave.
        Uma chave sem acesso a multimédia recebe os URLs de imagem, vídeo e PDF
        como null, e uma chave sem escrita em sessões recebe os links e tokens
        de sessão como null. Consulte https://docs.didit.me/console/api-keys.

````

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