> ## 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 per crear un Bank Link: connectar o renovar un banc

> L'endpoint Create a Bank Link de Didit inicia una execució de Bank Link al vostre servidor i retorna la URL allotjada on la persona connecta un banc.

L'endpoint Create a Bank Link de Didit inicia una execució de Bank Link al teu servidor, per connectar un banc o renovar una connexió, i retorna la `url` allotjada.
Tots els camps tenen un valor per defecte, de manera que la sol·licitud més senzilla és `{}` més el que vulguis.
Guarda l'`id` retornat amb el teu usuari i confirma tu mateix el resultat amb [Obtén un enllaç bancari](https://docs.didit.me/ca/standalone-apis/bank-link-get.md) o amb el webhook `bank.link.completed`.
Consulta l'[inici ràpid](https://docs.didit.me/ca/core-technology/bank-verification/quickstart.md) i [Bank Link](https://docs.didit.me/ca/core-technology/bank-verification/bank-link.md).


## OpenAPI

````yaml ca/openapi-25.json POST /v3/bank/links/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      Bank Link, connexions, comptes, saldos, transaccions, entitats i
      cobertura. Les dades bancàries estan disponibles per a aplicacions en
      sandbox. Les crides d'una aplicació en producció responen `404` fins que
      s'anunciï l'accés en producció. No es cobra res en sandbox. Una crida feta
      amb una clau d'API necessita una clau que tingui el permís Bank data
      (`bank-data`): lectura per a les lectures, escriptura per a les operacions
      que canvien alguna cosa. La comprovació de comptes n'és l'excepció:
      necessita accés d'escriptura a sessions, o accés complet, i no el permís
      Bank data. Bank data no forma part de l'accés complet: una clau amb accés
      complet es rebutja, i la crida respon `403 bank_data_access_denied` fins
      que creïs una clau que tingui el permís. Les dades bancàries en brut
      (comptes, saldos, transaccions i el feed de canvis) també rebutgen una
      sol·licitud que no porti cap clau d'API.


      Cada rebuig sota `/v3/bank/` excepte el de la comprovació de comptes té el
      mateix cos JSON (`code`, `message`, `request_id`, `field`, `next_action`,
      `retry_after`). Un camí que no és una operació, un identificador que no és
      un UUID o un subrecurs desconegut respon `404 not_found` per a qualsevol
      mètode, i qualsevol error inesperat respon `500 internal_error` amb un
      `request_id`. Quan les dades bancàries no estan disponibles, cada operació
      respon el `404` estàndard de la plataforma, exactament com ho fa una ruta
      desconeguda.
paths:
  /v3/bank/links/:
    post:
      tags:
        - Bank Data
      summary: Crea un enllaç bancari
      description: >-
        Crea un enllaç bancari: una execució del flux en què una persona
        connecta un banc o renova una connexió. Envia la persona a `url`. El
        `client_token` és per a l'enllaç bancari integrat de Didit, que encara
        no s'ha publicat: obre el `url` avui. Un enllaç completat dóna lloc a
        una connexió.


        La sol·licitud més petita és `{}` més el que vulguis. Valors per
        defecte: `mode` connect, `access` one_time, `data` només comptes,
        `history_days` 90, `ownership.compare` none, `segment` any, `duplicates`
        reuse, `allow_one_time_fallback` false i, per a l'accés continu, un
        consentiment tan llarg com permeti el banc.


        La resposta conté la cotització: el preu queda fixat a l'enllaç i es
        cobra tal com s'ha cotitzat. La clau d'API mai arriba a un navegador ni
        a una aplicació: només s'hi envia la `url`.


        Confirma tu mateix el resultat amb `get_link` o amb el webhook
        `bank.link.completed`; no confiïs mai en un id d'enllaç enviat pel
        navegador. Historial: envia `history_from` o `history_days`, però no els
        dos. Quan el banc ho permet, l'accés continu continua funcionant fins
        que acabi el consentiment; la data real figura a cada connexió.


        Cal una clau d'API amb el permís de dades bancàries (`bank-data`), amb
        accés d'escriptura per a aquesta operació, que modifica alguna cosa. Una
        clau amb accés complet no l'inclou: concedeix-lo explícitament en crear
        la clau, o la crida respondrà `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: L'enllaç s'ha creat.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankLink'
              examples:
                Ongoing business connection:
                  summary: Accés continu per a un compte d'empresa a Espanya
                  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: >-
            La sol·licitud s'ha rebutjat abans de cap pantalla. `field` indica
            què cal corregir: `invalid_request` per a un valor fora del seu
            interval o una combinació no permesa, i els codis més específics que
            es mostren aquí.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Bank cannot keep access open:
                  summary: El banc no pot mantenir l'accés obert
                  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: Finestra d'historial ambigua
                  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 redirecció no registrada
                  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: Segment no disponible
                  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: Finestra no disponible
                  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: Sol·licitud no vàlida
                  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: El saldo no cobreix el preu cotitzat. Recarrega i torna-ho a provar.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Insufficient credits:
                  summary: Crèdits insuficients
                  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: >-
            Rebutjada: el teu contracte no té tarifa per a aquest país, o la
            clau no té el permís de dades bancàries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                No contract rate:
                  summary: Sense tarifa contractada
                  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: Dades bancàries no permeses
                  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: El recurs no existeix en aquesta aplicació ni en aquest entorn.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not found:
                  summary: No trobat
                  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: >-
        Clau opcional de seguretat per a reintents que tu tries per a una
        operació, de fins a 255 caràcters (un UUID funciona). Una sol·licitud
        repetida amb la mateixa clau, endpoint, consulta i cos rep la primera
        resposta, amb el mateix codi d'estat i el mateix cos, i no s'executa ni
        es factura una segona vegada. La mateixa clau amb un altre endpoint,
        consulta o cos retorna `409` `idempotency_key_reused`, i mentre la
        primera sol·licitud encara s'està processant, `409`
        `idempotency_key_in_progress` amb `Retry-After`. Una sol·licitud fallida
        (qualsevol `4xx` o `5xx`) no s'emmagatzema, de manera que pots tornar-la
        a enviar amb la mateixa clau. Les claus pertanyen a la teva aplicació,
        tant si crides amb una clau d'API com amb un token d'accés. Consulta
        [Reintents i
        idempotència](/ca/integration/api-errors#reintents-i-idempotència).
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    BankLinkCreateRequest:
      type: object
      description: >-
        Crea un enllaç bancari. La sol·licitud més petita és `{}` més el que
        vulguis: tots els camps tenen un valor per defecte.
      properties:
        mode:
          type: string
          enum:
            - connect
            - renew
          description: >-
            `connect` (per defecte) crea una connexió nova. `renew` necessita
            `connection_id` i reutilitza la configuració d'aquella connexió.
          default: connect
        connection_id:
          type: string
          description: 'La connexió que cal renovar. Només amb `mode: renew`.'
          format: uuid
        access:
          type: string
          enum:
            - one_time
            - ongoing
          description: >-
            `one_time` (per defecte) llegeix les dades una sola vegada.
            `ongoing` manté l'accés obert fins que acaba el consentiment o algú
            el para. Amb `institution_id` definit, un banc que no pot mantenir
            l'accés obert respon `400 ongoing_access_not_available` abans de cap
            pantalla. Sense ell, el selector de bancs només mostra els bancs que
            ho poden fer.
          default: one_time
        country:
          type: string
          description: >-
            Opcional. Sense aquest camp, la persona tria entre els països que la
            teva aplicació ha habilitat. Ha de ser un país que Bank Link
            atengui; qualsevol altre, inclòs `ZZZ`, respon `400 invalid_request`
            amb `field: country`. Un cos de sol·licitud buit continua sent
            vàlid.
          pattern: ^[A-Z]{3}$
        institution_id:
          type: string
          description: >-
            Banc opcional per preseleccionar, de `list_institutions`. Omet el
            selector.
          maxLength: 64
        segment:
          type: string
          enum:
            - personal
            - business
            - any
          description: >-
            Filtra el selector i indica al banc quin inici de sessió ha d'obrir
            allà on el banc els separa. Per defecte, `any`.
          default: any
        data:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: >-
            Què llegir. `accounts` sempre s'inclou: nom, tipus, moneda,
            identificadors i el nom del titular si el banc el comparteix. Per
            defecte `["accounts"]`.
          default:
            - accounts
          maxItems: 3
        history_days:
          type: integer
          description: >-
            Dies d'historial de transaccions que es demanen, d'1 a 365, per
            defecte 90. El banc pot entregar menys: cada compte indica el que ha
            entregat a `history_coverage`. No es pot enviar juntament amb
            `history_from`.
          minimum: 1
          maximum: 365
          default: 90
        history_from:
          type: string
          description: >-
            Data d'inici de l'historial que cal sol·licitar, en lloc de
            `history_days`. No es pot enviar juntament amb `history_days`: si
            s'envien totes dues, la resposta és `400 history_window_ambiguous`.
            Una data anterior a 365 dies, o futura, respon `400
            window_not_available`.
          format: date
        extended_history:
          type: string
          enum:
            - standard
            - allow_extra_auth
          description: >-
            `allow_extra_auth` permet que un banc que demana una confirmació
            addicional alliberi l'historial més antic.
          default: standard
        consent_days:
          type: integer
          description: >-
            Només per a accés continu. Nombre de dies que cal demanar al banc
            que mantingui l'accés obert, 1 o més. Per defecte: el màxim que
            permet el banc. La connexió informa de la data que el banc ha
            concedit realment a `consent.expires_at`. Amb `access: one_time`
            respon `400 invalid_request` amb `field: consent_days`.
          minimum: 1
          maximum: 32767
        ownership:
          $ref: '#/components/schemas/BankLinkOwnershipRequest'
        end_user:
          $ref: '#/components/schemas/BankLinkEndUser'
        redirect_url:
          type: string
          description: >-
            On va el navegador al final, amb `link_id`, `status` i un `state`
            signat (només per mostrar: el webhook i `get_link` són les fonts
            autoritatives). En una aplicació de sandbox, una adreça `http`
            simple de `localhost`, `127.0.0.1` o `[::1]` (qualsevol port i camí,
            sense credencials ni fragment) no necessita registre. Qualsevol
            altra adreça respon `400 redirect_url_not_registered`: encara no
            està disponible el registre d'altres adreces. Sense `redirect_url`,
            la persona acaba a la pàgina de resultats pròpia de Didit.
          format: uri
          maxLength: 2048
        allowed_origins:
          type: array
          items:
            type: string
            format: uri
          description: >-
            Acceptat però no utilitzat avui: reservat per al Bank Link integrat
            de Didit, que encara no s'ha publicat. Orígens HTTPS, fins a 50.
          maxItems: 50
        language:
          type: string
          description: >-
            Codi d'idioma opcional, com `es` o `pt-BR`. Si no, s'usa l'idioma
            del navegador.
          pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})?$
          maxLength: 16
        vendor_data:
          type: string
          description: La vostra referència pròpia, retornada a l'enllaç i a la connexió.
          maxLength: 255
        expires_in:
          type: integer
          description: >-
            Durada de vida de l'enllaç en segons, de 300 a 86400. Per defecte,
            3600.
          minimum: 300
          maximum: 86400
          default: 3600
        duplicates:
          type: string
          enum:
            - reuse
            - allow
          description: >-
            `reuse` (per defecte) completa un enllaç que es resol amb comptes
            que ja comparteixes com una renovació d'aquesta connexió. `allow`
            crea una segona connexió independent.
          default: reuse
        allow_one_time_fallback:
          type: boolean
          description: >-
            Amb `ongoing`, permet que la persona continuï amb una lectura única
            en un banc que no pot mantenir l'accés obert, després de confirmar
            l'accés reduït a la seva pròpia pantalla. El pressupost mostra el
            cost. Només amb `access: ongoing`: amb accés d'un sol ús respon `400
            invalid_request` amb `field: allow_one_time_fallback`.
          default: false
        accept_reduced_grant:
          type: boolean
          description: >-
            Quan el banc o la persona concedeixen menys del que has sol·licitat,
            completa l'enllaç i cobra només els àmbits concedits. En cas
            contrari, l'enllaç acaba com a `failed` amb `reduced_grant` i no es
            cobra res.
          default: false
        sandbox:
          type: object
          description: >-
            Només per a aplicacions de sandbox: tria el client de Didit Test
            Bank. S'ignora en una aplicació en producció.
          properties:
            persona:
              type: string
              enum:
                - personal_basic
                - business_multi
                - long_history
                - pending
                - sparse_fields
                - no_ongoing
              description: >-
                El client del Test Bank: `personal_basic` (un compte corrent
                actual, 60 moviments), `business_multi` (tres comptes d'una
                empresa), `long_history` (un compte amb 400 dies i 1.400
                moviments; una lectura retorna els últims 365 dies, així que
                estableix `history_days` a 365), `pending` (inclou transaccions
                pendents), `sparse_fields` (sense data valor, sense IBAN de la
                contrapart ni referència bancària) o `no_ongoing` (un banc que
                només permet accés puntual: fes servir
                `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: >-
                Acceptat i reservat per al simulador del sandbox: els valors
                avui no canvien res.
    BankLink:
      type: object
      description: >-
        Una execució de Bank Link per a una persona: connectar un banc o renovar
        una connexió. Confirma tu mateix un enllaç amb `get_link`: no confiïs
        mai en un identificador enviat pel navegador.
      properties:
        id:
          type: string
          description: Identificador de l'enllaç.
          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: >-
            Estat de l'enllaç. `completed`, `cancelled`, `expired` i `failed`
            són estats finals.
        url:
          type: string
          description: >-
            La pàgina allotjada a la qual cal enviar la persona. Només es
            retorna en crear l'enllaç; és `null` en lectures posteriors, perquè
            el token no s'emmagatzema.
          nullable: true
          format: uri
        client_token:
          type: string
          description: >-
            El token del Bank Link integrat de Didit, que encara no està
            disponible: obre `url` avui. Només es retorna en crear l'enllaç;
            `null` en lectures posteriors. Té un únic propòsit i és de vida
            curta. No conté dades personals. No el registris mai.
          nullable: true
        expires_at:
          type: string
          description: Quan deixa de funcionar un enllaç no utilitzat.
          format: date-time
        connection_id:
          type: string
          description: >-
            La connexió que aquest enllaç ha creat o renovat, quan `status` és
            `completed`.
          format: uuid
          nullable: true
        check_id:
          type: string
          description: >-
            El resultat de titularitat d'aquest enllaç, quan s'ha sol·licitat
            `ownership.compare` amb un valor diferent de `none`.
          format: uuid
          nullable: true
        reused:
          type: boolean
          description: >-
            `true` quan l'enllaç s'ha completat com a renovació d'una connexió
            existent perquè la persona ja comparteix exactament aquests comptes
            (`duplicates: reuse`). No es cobra res dues vegades.
        error:
          allOf:
            - $ref: '#/components/schemas/BankLinkError'
          nullable: true
          description: >-
            Per què ha fallat l'enllaç, quan `status` és `failed`. En cas
            contrari, `null`.
        quote:
          $ref: '#/components/schemas/BankLinkQuote'
        vendor_data:
          type: string
          description: La vostra referència de la sol·licitud.
          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: >-
        Cos de l'error de cada operació de dades bancàries. Tots els camps hi
        són sempre presents.
      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: >-
            Codi d'error llegible per màquina. Decideix a partir d'aquest codi,
            mai a partir de `message`.
        message:
          type: string
          description: >-
            Explicació en llenguatge senzill per a un desenvolupador. La
            redacció pot canviar; no l'analitzis.
        request_id:
          type: string
          description: >-
            Identificador d'aquesta sol·licitud. Indica'l quan contactis amb el
            suport.
        field:
          type: string
          description: >-
            El camp de la sol·licitud que cal corregir, quan l'error fa
            referència a un sol camp. Altrament, `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: >-
            Què cal fer a continuació, perquè un client pugui actuar sense
            endevinar. `null` quan no hi ha un pas següent estàndard.
          nullable: true
        retry_after:
          type: integer
          description: >-
            Segons a esperar abans de reintentar. S'estableix en els errors de
            límit de freqüència i en els errors temporals; en cas contrari,
            `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: >-
        Comparació opcional del titular del compte amb una persona o una
        empresa.
      properties:
        compare:
          type: string
          enum:
            - none
            - person
            - business
          description: >-
            Amb què es compara el titular del compte. `none` (per defecte) no
            dona cap veredicte i no necessita cap referència. `person` necessita
            `reference_identity` o `session_id`. `business` necessita `business`
            o `business_session_id`. Envia exactament una referència del tipus
            amb què la comparis, i cap amb `none`.
          default: none
        match:
          type: string
          enum:
            - any_holder
            - all_holders
          description: >-
            Si ha de coincidir un sol titular legal o tots els titulars legals.
            Els representants no compten mai.
          default: any_holder
        reference_identity:
          type: object
          description: >-
            Valors subministrats pel client per comparar amb el titular del
            compte. No es poden enviar amb `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: >-
            Una sessió de verificació de Didit completada de la persona amb qui
            comparar. No es pot enviar amb `reference_identity`.
          format: uuid
        business:
          type: object
          description: L'empresa amb què comparar el titular del compte.
          properties:
            legal_name:
              type: string
              maxLength: 255
            registration_id:
              type: string
              maxLength: 128
          required:
            - legal_name
        business_session_id:
          type: string
          description: >-
            Una verificació d'empresa de Didit amb què comparar. No es pot
            enviar amb `business`.
          format: uuid
    BankLinkEndUser:
      type: object
      description: La persona o l'empresa que connecta el compte.
      properties:
        reference:
          type: string
          description: >-
            El vostre propi identificador de la persona o l'empresa. Es pot
            cercar amb `end_user_reference` i serveix per reconèixer una
            connexió repetida.
          maxLength: 255
        email:
          type: string
          description: >-
            Opcional. Quan la ruta bancària necessita una adreça verificada de
            la persona i no n'has enviat cap, Bank Link li la demana. Mai no
            s'utilitza amb finalitats de màrqueting.
          format: email
          maxLength: 254
    BankLinkError:
      type: object
      description: >-
        El motiu pel qual un enllaç ha acabat com a `failed`. No s'ha publicat
        ni cobrat res.
      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: >-
            Per què ha fallat l'enllaç. Un enllaç fallit no és un error HTTP:
            l'enllaç es llegeix amb `status: failed` i aquest objecte. Un enllaç
            de renovació la connexió del qual ha canviat entretant es llegeix
            com `renewal_not_needed` o `renewal_window_expired`.
        message:
          type: string
          description: Explicació en llenguatge senzill per a un desenvolupador.
        conflicts_with:
          type: array
          nullable: true
          items:
            type: string
            format: uuid
          description: >-
            Amb `duplicate_conflict`: els identificadors de les connexions
            actives que se solapen. Renova'n una o crea l'enllaç de nou amb
            `duplicates: allow`.
      required:
        - code
        - message
        - conflicts_with
    BankLinkQuote:
      type: object
      description: >-
        El preu d'un enllaç, fixat en el moment de crear-lo. El preu cobrat és
        el de la cotització. Les lectures no es facturen mai.
      properties:
        id:
          type: string
          description: Identificador del pressupost.
          format: uuid
        lines:
          type: array
          items:
            $ref: '#/components/schemas/BankLinkQuoteLine'
          description: >-
            Els conceptes que cobra aquest enllaç, per als àmbits que
            sol·licita.
        fallback_lines:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/BankLinkQuoteLine'
          description: >-
            El que cobraria una alternativa d'un sol ús, només quan l'enllaç
            s'ha creat amb `allow_one_time_fallback`. Es mostra a la resposta de
            creació i és `null` en cas contrari. Una lectura puntual amb dades
            pot costar més que el primer mes d'accés continu.
        total_usd:
          type: string
          description: >-
            Total de `lines` en USD. El total només pot baixar: amb una
            concessió reduïda, o quan la persona tria un país amb un preu més
            baix.
          pattern: ^-?\d+(\.\d+)?$
        valid_until:
          type: string
          description: >-
            La cotització està fixada a l'enllaç i és vàlida durant tota la vida
            de l'enllaç, per la qual cosa és igual a `expires_at`.
          format: date-time
        scopes:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: Les dades defineixen l'abast de les cotitzacions de preus.
      required:
        - id
        - lines
        - fallback_lines
        - total_usd
        - valid_until
        - scopes
    RateLimitBudgetError:
      type: object
      description: >-
        Només es retorna en un rebuig del pressupost del middleware de límit de
        freqüència. Altres errors 429, inclosos conflictes d'idempotència i
        límits específics de l'endpoint, no garanteixen aquests camps de
        metadades.
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: >-
            Missatge de denegació de pressupost existent, comprensible per a
            humans.
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: >-
            Referència de suport opaca: RL- seguit de 32 caràcters hexadecimals
            en minúscula d'un UUID.
        limit:
          type: integer
          description: Pressupost de l'àmbit superat; és igual a X-RateLimit-Limit.
        remaining:
          type: integer
          minimum: 0
          description: >-
            Pressupost restant, amb un mínim de zero; és igual que
            X-RateLimit-Remaining.
        reset:
          type: integer
          format: int64
          description: >-
            Temps de reinici de la finestra en segons Unix; és igual que
            X-RateLimit-Reset.
        window_seconds:
          type: integer
          description: >-
            Durada de la finestra fixa en segons, no l'espera restant. Respecta
            Retry-After abans de reintentar.
      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: Una línia amb preu d'un pressupost.
      properties:
        meter:
          type: string
          description: >-
            Què es cobra, per exemple `bank_data_connection_month`,
            `bank_verification`.
          example: bank_data_connection_month
        unit:
          type: string
          description: >-
            Què és una unitat, per exemple `connection_month` o
            `completed_sign_in`.
          example: connection_month
        price_usd:
          type: string
          description: >-
            Preu d'una unitat en USD, una cadena decimal amb 4 decimals. Els
            imports dels exemples són il·lustratius; el preu per país es mostra
            a la pàgina de preus.
          pattern: ^-?\d+(\.\d+)?$
          example: '0.9000'
      required:
        - meter
        - unit
        - price_usd
  responses:
    Unauthorized:
      description: No autoritzat
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: Clau d'API no vàlida
              value:
                detail: Invalid API Key.
    RateLimitedWrite:
      description: >-
        S'ha superat el límit compartit d'escriptura de 300 sol·licituds per
        minut per clau d'API. Respecta `Retry-After` abans de tornar a
        intentar-ho.
      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: >-
        Hi ha hagut un error per part de Didit. Qualsevol error inesperat sota
        `/v3/bank/` respon amb el format d'error de Bank, mai amb una pàgina
        HTML: cita el `request_id` quan contactis amb el servei de suport.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: Un error inesperat
              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: >-
        Nombre de segons que cal esperar, arrodonit fins a la finestra següent.
        Present en els rebutjos del pressupost del middleware.
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: >-
        L'àmbit que ha superat el seu pressupost. Present en els rebutjos del
        pressupost del middleware.
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: >-
        Pressupost de l'àmbit superat; és igual al límit del cos. Hi és present
        en les denegacions de pressupost del middleware.
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: >-
        Pressupost restant, amb un mínim de zero; és igual que remaining del
        cos. Hi és present a les denegacions del pressupost del middleware.
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: >-
        Temps de reinici en segons Unix; és igual que reset del cos. Present en
        els rebutjos del pressupost del middleware.
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        La clau d'API de la teva aplicació, des de Developers -> API keys a la
        Business Console. La clau principal té accés complet. Una clau amb nom
        es pot limitar: cap, lectura o escriptura per recurs, limitada a alguns
        fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a
        una data de caducitat. 401 vol dir que la clau és incorrecta, revocada o
        caducada; 403 vol dir que no s'ha enviat cap clau, que la clau no té
        accés a aquest recurs o acció, o que la sol·licitud ve d'una adreça fora
        de la seva llista d'adreces IP; 404 en una ruta de sessió vol dir que la
        sessió queda fora dels fluxos de treball o estats de la clau. Una clau
        sense accés a multimèdia rep les URL d'imatges, vídeos i PDF com a null,
        i una clau sense escriptura de sessions rep els enllaços i els tokens de
        sessió com a null. Vegeu https://docs.didit.me/console/api-keys.

````

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