> ## 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 criar ligação bancária: ligar ou renovar um banco

> O endpoint da Didit para criar uma ligação bancária inicia uma execução do Bank Link no seu servidor e devolve o URL alojado para ligar o banco.

O endpoint Criar uma Bank Link da Didit inicia uma execução da Bank Link no seu servidor, para ligar um banco ou renovar uma ligação, e devolve o `url` alojado.
Todos os campos têm um valor predefinido, pelo que o pedido mais simples é `{}` mais o que pretender.
Guarde o `id` devolvido junto do seu utilizador e confirme o resultado por si próprio com [Obter uma Bank Link](https://docs.didit.me/pt/standalone-apis/bank-link-get.md) ou com o webhook `bank.link.completed`.
Consulte o [início rápido](https://docs.didit.me/pt/core-technology/bank-verification/quickstart.md) e a [Bank Link](https://docs.didit.me/pt/core-technology/bank-verification/bank-link.md).


## OpenAPI

````yaml pt/openapi-25.json POST /v3/bank/links/
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/links/:
    post:
      tags:
        - Bank Data
      summary: Criar uma ligação bancária
      description: >-
        Cria uma ligação bancária: uma execução do fluxo em que uma pessoa liga
        um banco ou renova uma conexão. Envie a pessoa para `url`. O
        `client_token` destina-se ao Bank Link incorporado da Didit, que ainda
        não foi disponibilizado: por agora, abra o `url`. Uma ligação concluída
        dá origem a uma conexão.


        O pedido mais pequeno é `{}` mais o que pretender. Predefinições: `mode`
        connect, `access` one_time, `data` apenas accounts, `history_days` 90,
        `ownership.compare` none, `segment` any, `duplicates` reuse,
        `allow_one_time_fallback` false e, para o acesso contínuo, um
        consentimento tão longo quanto o banco permitir.


        A resposta inclui a cotação: o preço fica fixado na ligação e é cobrado
        conforme cotado. A chave de API nunca chega a um navegador ou a uma
        aplicação: apenas o `url` chega.


        Confirme o resultado por si com `get_link` ou com o webhook
        `bank.link.completed`; nunca confie num id de ligação enviado pelo
        navegador. Histórico: envie `history_from` ou `history_days`, não ambos.
        Onde o banco o permitir, o acesso contínuo continua a funcionar até o
        consentimento terminar; a data real está em cada conexão.


        Requer uma chave de API com a permissão Dados bancários (`bank-data`),
        com permissões de escrita para esta operação, que altera algo. Uma chave
        com acesso total não a inclui: conceda-a explicitamente ao criar a
        chave, ou a chamada responde com `403 bank_data_access_denied`.
      operationId: createBankLink
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankLinkCreateRequest'
            example:
              mode: connect
              access: ongoing
              country: ESP
              segment: business
              data:
                - accounts
                - balances
                - transactions
              history_from: '2026-01-01'
              consent_days: 180
              ownership:
                compare: none
              end_user:
                reference: client-7731
                email: ana@example.com
              redirect_url: https://app.example.com/bank/return
              allowed_origins:
                - https://app.example.com
              language: es
              vendor_data: client-7731
      responses:
        '201':
          description: A ligação foi criada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankLink'
              examples:
                Ongoing business connection:
                  summary: Acesso contínuo para uma conta de empresa em Espanha
                  value:
                    id: 0b9c4f1e-6a2d-4e8b-9f31-7c5d2e1a8b40
                    mode: connect
                    access: ongoing
                    status: created
                    url: https://verify.didit.me/bank/link/example-link-token
                    client_token: example-client-token
                    expires_at: '2026-11-21T13:00:00Z'
                    connection_id: null
                    check_id: null
                    reused: false
                    error: null
                    quote:
                      id: 7a3e9c52-1d84-4b06-8f2a-c5e0b9d17a43
                      lines:
                        - meter: bank_data_connection_month
                          unit: connection_month
                          price_usd: '0.9000'
                      fallback_lines: null
                      total_usd: '0.9000'
                      valid_until: '2026-11-21T13:00:00Z'
                      scopes:
                        - accounts
                        - balances
                        - transactions
                    vendor_data: client-7731
        '400':
          description: >-
            O pedido foi recusado antes de qualquer ecrã. `field` indica o que
            corrigir: `invalid_request` para um valor fora do intervalo ou uma
            combinação não permitida, e os códigos mais específicos apresentados
            aqui.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Bank cannot keep access open:
                  summary: O banco não consegue manter o acesso aberto
                  value:
                    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
                History window ambiguous:
                  summary: Período do histórico ambíguo
                  value:
                    code: history_window_ambiguous
                    message: Send history_from or history_days, not both.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: history_from
                    next_action: null
                    retry_after: null
                Redirect URL not registered:
                  summary: URL de redirecionamento não registado
                  value:
                    code: redirect_url_not_registered
                    message: >-
                      This redirect_url is not one of the return addresses
                      registered for your application. Addresses are matched
                      exactly (scheme, host, port, path and query); in sandbox a
                      plain http localhost address needs no registration. Send a
                      registered address, or leave redirect_url out (automatic
                      return to your page is then not promised).
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: redirect_url
                    next_action: null
                    retry_after: null
                Segment not available:
                  summary: Segmento não disponível
                  value:
                    code: segment_not_available
                    message: >-
                      This bank does not offer this kind of account through Bank
                      Link.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: segment
                    next_action: null
                    retry_after: null
                Window not available:
                  summary: Janela indisponível
                  value:
                    code: window_not_available
                    message: This bank cannot deliver the requested history window.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: history_from
                    next_action: null
                    retry_after: null
                Invalid request:
                  summary: Pedido inválido
                  value:
                    code: invalid_request
                    message: The request is not valid.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: expires_in
                    next_action: null
                    retry_after: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: O saldo não cobre o preço cotado. Carregue saldo e tente novamente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Insufficient credits:
                  summary: Créditos insuficientes
                  value:
                    code: insufficient_credits
                    message: The balance cannot cover the quoted price.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: top_up_balance
                    retry_after: null
        '403':
          description: >-
            Recusado: o seu contrato não tem tarifa para este país, ou a chave
            não tem a permissão Bank data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                No contract rate:
                  summary: Sem tarifa contratual
                  value:
                    code: contract_rate_missing
                    message: Your contract has no rate for bank data in this country.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: null
                    retry_after: null
                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
        '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/RateLimitedWrite'
        '500':
          $ref: '#/components/responses/BankDataInternalError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST 'https://verification.didit.me/v3/bank/links/' \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "mode": "connect",
                "access": "ongoing",
                "country": "ESP",
                "segment": "business",
                "data": [
                  "accounts",
                  "balances",
                  "transactions"
                ],
                "history_from": "2026-01-01",
                "consent_days": 180,
                "ownership": {
                  "compare": "none"
                },
                "end_user": {
                  "reference": "client-7731",
                  "email": "ana@example.com"
                },
                "redirect_url": "https://app.example.com/bank/return",
                "allowed_origins": [
                  "https://app.example.com"
                ],
                "language": "es",
                "vendor_data": "client-7731"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.bank.create_link(
                mode="connect",
                access="ongoing",
                country="ESP",
                segment="business",
                data=["accounts", "balances", "transactions"],
                history_from="2026-01-01",
                consent_days=180,
                ownership={
                    "compare": "none",
                },
                end_user={
                    "reference": "client-7731",
                    "email": "ana@example.com",
                },
                redirect_url="https://app.example.com/bank/return",
                allowed_origins=["https://app.example.com"],
                language="es",
                vendor_data="client-7731",
            )
            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.createLink({
              mode: "connect",
              access: "ongoing",
              country: "ESP",
              segment: "business",
              data: ["accounts", "balances", "transactions"],
              history_from: "2026-01-01",
              consent_days: 180,
              ownership: {
                compare: "none",
              },
              end_user: {
                reference: "client-7731",
                email: "ana@example.com",
              },
              redirect_url: "https://app.example.com/bank/return",
              allowed_origins: ["https://app.example.com"],
              language: "es",
              vendor_data: "client-7731",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.CreateLink(ctx, didit.BankCreateLinkParams{\n\tBody: didit.BankLinkCreateRequest{\n\t\tMode:        didit.Some(didit.BankLinkCreateRequestMode(\"connect\")),\n\t\tAccess:      didit.Some(didit.BankLinkCreateRequestAccess(\"ongoing\")),\n\t\tCountry:     didit.String(\"ESP\"),\n\t\tSegment:     didit.Some(didit.BankLinkCreateRequestSegment(\"business\")),\n\t\tData:        didit.Some([]didit.BankLinkCreateRequestData{\"accounts\", \"balances\", \"transactions\"}),\n\t\tHistoryFrom: didit.String(\"2026-01-01\"),\n\t\tConsentDays: didit.Int(180),\n\t\tOwnership: didit.Some(didit.BankLinkOwnershipRequest{\n\t\t\tCompare: didit.Some(didit.BankLinkOwnershipRequestCompare(\"none\")),\n\t\t}),\n\t\tEndUser: didit.Some(didit.BankLinkEndUser{\n\t\t\tReference: didit.String(\"client-7731\"),\n\t\t\tEmail:     didit.String(\"ana@example.com\"),\n\t\t}),\n\t\tRedirectURL:    didit.String(\"https://app.example.com/bank/return\"),\n\t\tAllowedOrigins: didit.Some([]string{\"https://app.example.com\"}),\n\t\tLanguage:       didit.String(\"es\"),\n\t\tVendorData:     didit.String(\"client-7731\"),\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import java.time.LocalDate;

            import java.util.List;

            import me.didit.Didit;

            import me.didit.types.BankLinkCreateRequest;

            import me.didit.types.BankLinkEndUser;

            import me.didit.types.BankLinkOwnershipRequest;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.bank().createLink(BankLinkCreateRequest.builder()
                    .mode(BankLinkCreateRequest.Mode.of("connect"))
                    .access(BankLinkCreateRequest.Access.of("ongoing"))
                    .country("ESP")
                    .segment(BankLinkCreateRequest.Segment.of("business"))
                    .data(List.of(BankLinkCreateRequest.Data.of("accounts"), BankLinkCreateRequest.Data.of("balances"), BankLinkCreateRequest.Data.of("transactions")))
                    .historyFrom(LocalDate.parse("2026-01-01"))
                    .consentDays(180L)
                    .ownership(BankLinkOwnershipRequest.builder()
                            .compare(BankLinkOwnershipRequest.Compare.of("none"))
                            .build())
                    .endUser(BankLinkEndUser.builder()
                            .reference("client-7731")
                            .email("ana@example.com")
                            .build())
                    .redirectUrl("https://app.example.com/bank/return")
                    .allowedOrigins(List.of("https://app.example.com"))
                    .language("es")
                    .vendorData("client-7731")
                    .build());
            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->createLink([
                'mode' => 'connect',
                'access' => 'ongoing',
                'country' => 'ESP',
                'segment' => 'business',
                'data' => ['accounts', 'balances', 'transactions'],
                'history_from' => '2026-01-01',
                'consent_days' => 180,
                'ownership' => [
                    'compare' => 'none',
                ],
                'end_user' => [
                    'reference' => 'client-7731',
                    'email' => 'ana@example.com',
                ],
                'redirect_url' => 'https://app.example.com/bank/return',
                'allowed_origins' => ['https://app.example.com'],
                'language' => 'es',
                'vendor_data' => 'client-7731',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.bank.create_link(
              mode: "connect",
              access: "ongoing",
              country: "ESP",
              segment: "business",
              data: ["accounts", "balances", "transactions"],
              history_from: "2026-01-01",
              consent_days: 180,
              ownership: {
                compare: "none",
              },
              end_user: {
                reference: "client-7731",
                email: "ana@example.com",
              },
              redirect_url: "https://app.example.com/bank/return",
              allowed_origins: ["https://app.example.com"],
              language: "es",
              vendor_data: "client-7731"
            )
            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.CreateLinkAsync(new
            BankLinkCreateRequest

            {
                Mode = new BankLinkCreateRequestMode("connect"),
                Access = new BankLinkCreateRequestAccess("ongoing"),
                Country = "ESP",
                Segment = new BankLinkCreateRequestSegment("business"),
                Data = new BankLinkCreateRequestData[] { "accounts", "balances", "transactions" },
                HistoryFrom = "2026-01-01",
                ConsentDays = 180,
                Ownership = new BankLinkOwnershipRequest
                {
                    Compare = new BankLinkOwnershipRequestCompare("none"),
                },
                EndUser = new BankLinkEndUser
                {
                    Reference = "client-7731",
                    Email = "ana@example.com",
                },
                RedirectUrl = "https://app.example.com/bank/return",
                AllowedOrigins = new string[] { "https://app.example.com" },
                Language = "es",
                VendorData = "client-7731",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Chave opcional, à sua escolha, para garantir a segurança de novas
        tentativas numa operação, com até 255 caracteres (um UUID funciona). Um
        pedido repetido com a mesma chave, endpoint, parâmetros de query e corpo
        recebe a primeira resposta, com o mesmo código de estado e o mesmo
        corpo, e não é executado nem faturado uma segunda vez. A mesma chave com
        outro endpoint, outros parâmetros de query ou outro corpo devolve `409`
        `idempotency_key_reused`. Enquanto o primeiro pedido ainda estiver em
        execução, devolve `409` `idempotency_key_in_progress` com `Retry-After`.
        Um pedido falhado (qualquer `4xx` ou `5xx`) não é guardado, pelo que
        pode ser enviado novamente com a mesma chave. As chaves pertencem à sua
        aplicação, quer chame a API com uma chave de API, quer com um token de
        acesso. Consulte [Novas tentativas e
        idempotência](/pt/integration/api-errors#novas-tentativas-e-idempotência).
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    BankLinkCreateRequest:
      type: object
      description: >-
        Crie uma ligação bancária (Bank Link). O pedido mais pequeno é `{}` mais
        o que pretender: todos os campos têm um valor predefinido.
      properties:
        mode:
          type: string
          enum:
            - connect
            - renew
          description: >-
            `connect` (predefinido) cria uma nova conexão. `renew` requer
            `connection_id` e reutiliza as definições dessa conexão.
          default: connect
        connection_id:
          type: string
          description: 'A ligação a renovar. Apenas com `mode: renew`.'
          format: uuid
        access:
          type: string
          enum:
            - one_time
            - ongoing
          description: >-
            `one_time` (predefinido) lê os dados uma única vez. `ongoing` mantém
            o acesso aberto até que o consentimento termine ou alguém o
            interrompa. Quando `institution_id` está definido, um banco que não
            consegue manter o acesso aberto responde com `400
            ongoing_access_not_available` antes de qualquer ecrã. Sem ele, o
            seletor de bancos lista apenas os bancos que conseguem.
          default: one_time
        country:
          type: string
          description: >-
            Opcional. Sem este campo, a pessoa escolhe entre os países que a sua
            aplicação ativou. Tem de ser um país que o Bank Link serve; qualquer
            outro, incluindo `ZZZ`, responde com `400 invalid_request` e `field:
            country`. Um corpo de pedido vazio continua válido.
          pattern: ^[A-Z]{3}$
        institution_id:
          type: string
          description: >-
            Banco opcional a pré-selecionar, obtido de `list_institutions`.
            Ignora o seletor.
          maxLength: 64
        segment:
          type: string
          enum:
            - personal
            - business
            - any
          description: >-
            Filtra o seletor e indica ao banco qual o acesso a abrir, quando o
            banco os separa. Predefinição `any`.
          default: any
        data:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: >-
            O que ler. `accounts` está sempre incluído: nome, tipo, moeda,
            identificadores e o nome do titular quando o banco o partilha.
            Predefinido `["accounts"]`.
          default:
            - accounts
          maxItems: 3
        history_days:
          type: integer
          description: >-
            Dias de histórico de transações a pedir, de 1 a 365, por
            predefinição 90. O banco pode entregar menos: cada conta indica o
            que entregou em `history_coverage`. Não pode ser enviado em conjunto
            com `history_from`.
          minimum: 1
          maximum: 365
          default: 90
        history_from:
          type: string
          description: >-
            Data de início do histórico a pedir, em vez de `history_days`. Não
            pode ser enviada com `history_days`: ambos juntos respondem `400
            history_window_ambiguous`. Uma data anterior a 365 dias, ou no
            futuro, responde `400 window_not_available`.
          format: date
        extended_history:
          type: string
          enum:
            - standard
            - allow_extra_auth
          description: >-
            `allow_extra_auth` permite que um banco que pede uma confirmação
            adicional disponibilize histórico mais antigo.
          default: standard
        consent_days:
          type: integer
          description: >-
            Apenas para ligações contínuas. Número de dias para pedir ao banco
            que mantenha o acesso aberto, 1 ou mais. Predefinição: o máximo que
            o banco permite. A ligação indica a data que o banco concedeu
            efetivamente em `consent.expires_at`. Com `access: one_time`,
            responde com `400 invalid_request` e `field: consent_days`.
          minimum: 1
          maximum: 32767
        ownership:
          $ref: '#/components/schemas/BankLinkOwnershipRequest'
        end_user:
          $ref: '#/components/schemas/BankLinkEndUser'
        redirect_url:
          type: string
          description: >-
            Para onde o navegador vai no fim, com `link_id`, `status` e um
            `state` assinado (apenas para apresentação: o webhook e `get_link`
            são a referência autoritativa). Numa aplicação de sandbox, um
            endereço `http` simples de `localhost`, `127.0.0.1` ou `[::1]`
            (qualquer porta e caminho, sem credenciais, sem fragmento) não
            precisa de registo. Qualquer outro endereço responde `400
            redirect_url_not_registered`: o registo de outros endereços ainda
            não está disponível. Sem `redirect_url`, a pessoa termina na página
            de resultados da própria Didit.
          format: uri
          maxLength: 2048
        allowed_origins:
          type: array
          items:
            type: string
            format: uri
          description: >-
            Aceite, mas não utilizado atualmente: reservado para o Bank Link
            incorporado da Didit, que ainda não foi lançado. Origens HTTPS, até
            50.
          maxItems: 50
        language:
          type: string
          description: >-
            Código de idioma opcional, como `es` ou `pt-BR`. Caso contrário, o
            idioma do navegador.
          pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})?$
          maxLength: 16
        vendor_data:
          type: string
          description: A sua referência, devolvida na ligação e na conexão.
          maxLength: 255
        expires_in:
          type: integer
          description: >-
            Tempo de vida da ligação em segundos, de 300 a 86400. Predefinido:
            3600.
          minimum: 300
          maximum: 86400
          default: 3600
        duplicates:
          type: string
          enum:
            - reuse
            - allow
          description: >-
            `reuse` (predefinido) conclui uma ligação que remete para contas que
            já partilha como uma renovação dessa ligação. `allow` cria uma
            segunda ligação independente.
          default: reuse
        allow_one_time_fallback:
          type: boolean
          description: >-
            Com `ongoing`, permite que a pessoa continue com uma leitura pontual
            num banco que não consegue manter o acesso aberto, depois de
            confirmar o acesso reduzido no próprio ecrã do banco. A cotação
            mostra o custo. Apenas com `access: ongoing`: com acesso pontual,
            responde com `400 invalid_request` e `field:
            allow_one_time_fallback`.
          default: false
        accept_reduced_grant:
          type: boolean
          description: >-
            Quando o banco ou a pessoa concede menos do que pediu, conclua a
            ligação e cobre apenas os âmbitos concedidos. Caso contrário, a
            ligação termina em `failed` com `reduced_grant` e nada é cobrado.
          default: false
        sandbox:
          type: object
          description: >-
            Apenas aplicações sandbox: escolhe o cliente do Didit Test Bank.
            Ignorado numa aplicação de produção.
          properties:
            persona:
              type: string
              enum:
                - personal_basic
                - business_multi
                - long_history
                - pending
                - sparse_fields
                - no_ongoing
              description: >-
                O cliente do Test Bank: `personal_basic` (uma conta à ordem, 60
                movimentos), `business_multi` (três contas detidas por uma
                empresa), `long_history` (uma conta com 400 dias e 1 400
                movimentos; uma leitura devolve os últimos 365 dias, por isso
                defina `history_days` como 365), `pending` (inclui transações
                pendentes), `sparse_fields` (sem data-valor, sem IBAN da
                contraparte, sem referência bancária) ou `no_ongoing` (um banco
                que só permite acesso pontual: use `allow_one_time_fallback`).
            switches:
              type: array
              items:
                type: string
                enum:
                  - partial_grant
                  - renewal_other_login
                  - expired_cursor
                  - webhook_twice
                  - midnight_booking
                  - blocked_popup
                  - bank_app_return
              description: >-
                Aceite e reservado para o simulador do sandbox: os valores não
                alteram nada atualmente.
    BankLink:
      type: object
      description: >-
        Uma execução do Bank Link para uma pessoa: ligar um banco ou renovar uma
        ligação. Confirme pessoalmente a ligação com `get_link`: nunca confie
        num id enviado pelo navegador.
      properties:
        id:
          type: string
          description: Identificador do link.
          format: uuid
        mode:
          type: string
          enum:
            - connect
            - renew
        access:
          type: string
          enum:
            - one_time
            - ongoing
        status:
          type: string
          enum:
            - created
            - opened
            - connecting
            - completed
            - cancelled
            - expired
            - failed
          description: >-
            Estado do link. `completed`, `cancelled`, `expired` e `failed` são
            estados finais.
        url:
          type: string
          description: >-
            A página alojada para onde enviar a pessoa. Devolvida apenas quando
            a ligação é criada; `null` nas leituras seguintes, porque o token
            não é guardado.
          nullable: true
          format: uri
        client_token:
          type: string
          description: >-
            O token do Bank Link incorporado da Didit, que ainda não foi
            disponibilizado: abra `url` hoje. Devolvido apenas quando a ligação
            é criada; `null` nas leituras seguintes. Tem uma única finalidade e
            uma duração curta. Não contém dados pessoais. Nunca o registe.
          nullable: true
        expires_at:
          type: string
          description: Quando uma ligação não resgatada deixa de funcionar.
          format: date-time
        connection_id:
          type: string
          description: >-
            A ligação criada ou renovada por esta hiperligação, quando `status`
            é `completed`.
          format: uuid
          nullable: true
        check_id:
          type: string
          description: >-
            O resultado da verificação de propriedade desta ligação, quando foi
            pedido `ownership.compare` com valor diferente de `none`.
          format: uuid
          nullable: true
        reused:
          type: boolean
          description: >-
            `true` quando a ligação foi concluída como renovação de uma ligação
            existente, porque a pessoa já partilha exatamente estas contas
            (`duplicates: reuse`). Nada é cobrado duas vezes.
        error:
          allOf:
            - $ref: '#/components/schemas/BankLinkError'
          nullable: true
          description: >-
            Motivo da falha da ligação, quando `status` é `failed`. Caso
            contrário, `null`.
        quote:
          $ref: '#/components/schemas/BankLinkQuote'
        vendor_data:
          type: string
          description: A sua referência do pedido.
          nullable: true
      required:
        - id
        - mode
        - access
        - status
        - url
        - client_token
        - expires_at
        - connection_id
        - check_id
        - reused
        - error
        - quote
        - vendor_data
    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
    BankLinkOwnershipRequest:
      type: object
      description: Comparação opcional do titular da conta com uma pessoa ou uma empresa.
      properties:
        compare:
          type: string
          enum:
            - none
            - person
            - business
          description: >-
            Com o que é comparado o titular da conta. `none` (predefinido) não
            dá veredicto e não precisa de referência. `person` precisa de
            `reference_identity` ou `session_id`. `business` precisa de
            `business` ou `business_session_id`. Envie exatamente uma referência
            do tipo com que compara, e nenhuma com `none`.
          default: none
        match:
          type: string
          enum:
            - any_holder
            - all_holders
          description: >-
            Se tem de haver correspondência com um titular legal ou com todos os
            titulares legais. Os representantes nunca contam.
          default: any_holder
        reference_identity:
          type: object
          description: >-
            Valores fornecidos pelo chamador para comparar com o titular da
            conta. Não podem ser enviados com `session_id`.
          properties:
            full_name:
              type: string
              maxLength: 255
            date_of_birth:
              type: string
              format: date
            address:
              type: string
              maxLength: 500
            phone:
              type: string
              maxLength: 64
            email:
              type: string
              maxLength: 255
        session_id:
          type: string
          description: >-
            Uma sessão de verificação da Didit concluída da pessoa com a qual
            comparar. Não pode ser enviada com `reference_identity`.
          format: uuid
        business:
          type: object
          description: A empresa a comparar com o titular da conta.
          properties:
            legal_name:
              type: string
              maxLength: 255
            registration_id:
              type: string
              maxLength: 128
          required:
            - legal_name
        business_session_id:
          type: string
          description: >-
            Uma verificação de empresa da Didit com a qual comparar. Não pode
            ser enviada com `business`.
          format: uuid
    BankLinkEndUser:
      type: object
      description: A pessoa ou empresa que liga a conta.
      properties:
        reference:
          type: string
          description: >-
            O seu próprio id para a pessoa ou empresa. Pesquisável com
            `end_user_reference` e usado para reconhecer uma conexão repetida.
          maxLength: 255
        email:
          type: string
          description: >-
            Opcional. Quando a rota bancária exige uma morada verificada da
            pessoa e não enviou uma, o Bank Link pede-a à pessoa. Nunca
            utilizada para marketing.
          format: email
          maxLength: 254
    BankLinkError:
      type: object
      description: >-
        O motivo pelo qual a ligação terminou com `failed`. Nada foi publicado
        nem cobrado.
      properties:
        code:
          type: string
          enum:
            - duplicate_conflict
            - renewal_login_mismatch
            - reduced_grant
            - corporate_approval_not_supported
            - ongoing_access_not_available
            - bank_unavailable
            - bank_cancelled
            - consent_declined
            - read_limit
            - renewal_not_needed
            - renewal_window_expired
            - first_sync_failed
          description: >-
            Motivo da falha da ligação. Uma ligação com falha não é um erro
            HTTP: a ligação é devolvida com `status: failed` e este objeto. Uma
            ligação de renovação cuja conexão tenha entretanto mudado é
            devolvida com `renewal_not_needed` ou `renewal_window_expired`.
        message:
          type: string
          description: Explicação em linguagem simples para um programador.
        conflicts_with:
          type: array
          nullable: true
          items:
            type: string
            format: uuid
          description: >-
            Com `duplicate_conflict`: os ids das conexões ativas que se
            sobrepõem. Renove uma delas ou crie novamente a ligação com
            `duplicates: allow`.
      required:
        - code
        - message
        - conflicts_with
    BankLinkQuote:
      type: object
      description: >-
        O preço de uma ligação, fixado na criação. O valor cobrado é o da
        cotação. As leituras nunca são faturadas.
      properties:
        id:
          type: string
          description: Identificador da cotação.
          format: uuid
        lines:
          type: array
          items:
            $ref: '#/components/schemas/BankLinkQuoteLine'
          description: >-
            As linhas de preços cobradas por esta ligação, para os âmbitos
            solicitados.
        fallback_lines:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/BankLinkQuoteLine'
          description: >-
            O que uma alternativa de pagamento único custaria, apenas quando a
            ligação foi criada com `allow_one_time_fallback`. É apresentado na
            resposta de criação e é `null` caso contrário. Uma leitura pontual
            com dados pode custar mais do que um primeiro mês de acesso
            contínuo.
        total_usd:
          type: string
          description: >-
            Total de `lines` em USD. O total só pode descer: com uma concessão
            reduzida, ou quando a pessoa escolhe um país com um preço mais
            baixo.
          pattern: ^-?\d+(\.\d+)?$
        valid_until:
          type: string
          description: >-
            A cotação está fixada à ligação e é válida durante toda a vida útil
            da ligação, pelo que é igual a `expires_at`.
          format: date-time
        scopes:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: Os dados definem o âmbito dos preços da cotação.
      required:
        - id
        - lines
        - fallback_lines
        - total_usd
        - valid_until
        - scopes
    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
    BankLinkQuoteLine:
      type: object
      description: Uma linha com preço de uma cotação.
      properties:
        meter:
          type: string
          description: >-
            O que é cobrado, por exemplo `bank_data_connection_month`,
            `bank_verification`.
          example: bank_data_connection_month
        unit:
          type: string
          description: >-
            O que é uma unidade, por exemplo `connection_month` ou
            `completed_sign_in`.
          example: connection_month
        price_usd:
          type: string
          description: >-
            Preço de uma unidade em USD, uma cadeia decimal com 4 casas
            decimais. Os montantes nos exemplos são ilustrativos; o preço de
            cada país é indicado na página de preços.
          pattern: ^-?\d+(\.\d+)?$
          example: '0.9000'
      required:
        - meter
        - unit
        - price_usd
  responses:
    Unauthorized:
      description: Não autorizado
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: Chave de API inválida
              value:
                detail: Invalid API Key.
    RateLimitedWrite:
      description: >-
        Foi excedido o limite partilhado de escrita de 300 pedidos por minuto
        por chave de API. Respeite `Retry-After` antes de tentar novamente.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitBudgetError'
          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
      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'
    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.