> ## 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 crear un enlace bancario: conectar o renovar un banco

> El endpoint de Didit para crear un enlace bancario inicia una ejecución en tu servidor y devuelve la URL alojada donde se conecta el banco.

Didit's endpoint para crear un Bank Link inicia una ejecución de Bank Link en tu servidor, para conectar un banco o renovar una conexión, y devuelve la `url` alojada.

Todos los campos tienen un valor por defecto, así que la solicitud más sencilla es `{}` más lo que quieras enviar.

Guarda el `id` devuelto junto a tu usuario y confirma el resultado por tu cuenta con [Obtener un enlace bancario](https://docs.didit.me/es/standalone-apis/bank-link-get.md) o con el webhook `bank.link.completed`.

Consulta la [guía de inicio rápido](https://docs.didit.me/es/core-technology/bank-verification/quickstart.md) y [Bank Link](https://docs.didit.me/es/core-technology/bank-verification/bank-link.md).


## OpenAPI

````yaml es/openapi-25.json POST /v3/bank/links/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de verificación de identidad. Autentícate con el encabezado x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      Bank Link, conexiones, cuentas, saldos, transacciones, instituciones y
      cobertura. Los datos bancarios están disponibles para aplicaciones de
      sandbox. Las llamadas de una aplicación de producción responden `404`
      hasta que se anuncie el acceso en producción. En sandbox no se cobra nada.
      Una llamada hecha con una clave de API necesita una clave que tenga el
      permiso de datos bancarios (`bank-data`): lectura para las consultas,
      escritura para las operaciones que cambian algo. La verificación de cuenta
      es la excepción: necesita acceso de escritura a las sesiones, o acceso
      completo, y no el permiso de datos bancarios. Los datos bancarios no
      forman parte del acceso completo: una clave con acceso completo es
      rechazada, y la llamada responde `403 bank_data_access_denied` hasta que
      crees una clave que tenga el permiso. Los datos bancarios sin procesar
      (cuentas, saldos, transacciones y el flujo de cambios) también rechazan
      una solicitud que no incluya una clave de API.


      Cualquier rechazo bajo `/v3/bank/`, salvo el de la verificación de cuenta,
      tiene el mismo cuerpo JSON (`code`, `message`, `request_id`, `field`,
      `next_action`, `retry_after`). Una ruta que no es una operación, un ID que
      no es un UUID o un subrecurso desconocido responde `404 not_found` para
      todos los métodos, y cualquier error inesperado responde `500
      internal_error` con un `request_id`. Cuando los datos bancarios no están
      disponibles, todas las operaciones responden el `404` estándar de la
      plataforma, igual que lo hace una ruta desconocida.
paths:
  /v3/bank/links/:
    post:
      tags:
        - Bank Data
      summary: Crear un enlace bancario
      description: >-
        Crea un enlace bancario: una ejecución del flujo en la que una persona
        conecta un banco o renueva una conexión. Envíale la `url`. El
        `client_token` es para el Bank Link integrado de Didit, que todavía no
        está disponible: abre la `url` hoy. Un enlace completado genera una
        conexión.


        La solicitud más sencilla es `{}` más lo que quieras indicar. Valores
        por defecto: `mode` connect, `access` one_time, `data` solo cuentas,
        `history_days` 90, `ownership.compare` none, `segment` any, `duplicates`
        reuse, `allow_one_time_fallback` false y, para el acceso continuo, un
        consentimiento con la duración que permita el banco.


        La respuesta incluye la cotización: el precio queda fijado al enlace y
        se cobra según lo cotizado. La clave de API nunca llega a un navegador
        ni a una aplicación: solo llega la `url`.


        Confirma el resultado tú mismo con `get_link` o con el webhook
        `bank.link.completed`; nunca confíes en un id de enlace enviado desde el
        navegador. Historial: envía `history_from` o `history_days`, pero no
        ambos. Cuando el banco lo permite, el acceso continuo sigue funcionando
        hasta que termine el consentimiento; la fecha real figura en cada
        conexión.


        Requiere una clave de API con el permiso de datos bancarios
        (`bank-data`): escritura para esta operación, que modifica algo. Una
        clave con acceso completo no lo incluye: concédelo explícitamente al
        crear la clave, o la llamada responde `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: El enlace fue creado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankLink'
              examples:
                Ongoing business connection:
                  summary: Acceso continuo para una cuenta empresarial en España
                  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 solicitud se rechazó antes de mostrar cualquier pantalla. `field`
            indica qué corregir: `invalid_request` para un valor fuera de su
            rango o una combinación no permitida, y los códigos más específicos
            que se muestran aquí.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Bank cannot keep access open:
                  summary: El banco no puede mantener el acceso abierto
                  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: Ventana de 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ón 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: Segmento 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: Ventana 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: Solicitud 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 cubre el precio cotizado. Recarga y vuelve a intentarlo.
          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: >-
            Rechazado: tu contrato no tiene tarifa para este país, o la clave no
            tiene el permiso de datos bancarios.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                No contract rate:
                  summary: Sin tarifa contratada
                  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: Datos bancarios no 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: El recurso no existe en esta aplicación ni en este entorno.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not found:
                  summary: No 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: >-
        Clave opcional que eliges para garantizar la seguridad de los reintentos
        en una operación, de hasta 255 caracteres (puede usarse un UUID). Una
        solicitud repetida con la misma clave, endpoint, parámetros de consulta
        y cuerpo recibe la primera respuesta, con el mismo código de estado y el
        mismo cuerpo, y no se ejecuta ni se factura de nuevo. La misma clave con
        otro endpoint, otros parámetros de consulta o un cuerpo distinto
        devuelve `409` `idempotency_key_reused`. Si la primera solicitud sigue
        en curso, devuelve `409` `idempotency_key_in_progress` con
        `Retry-After`. Una solicitud fallida (cualquier `4xx` o `5xx`) no se
        almacena, así que puedes volver a enviarla con la misma clave. Las
        claves pertenecen a tu aplicación, tanto si llamas con una clave de API
        como con un token de acceso. Consulta [Reintentos e
        idempotencia](/es/integration/api-errors#reintentos-e-idempotencia).
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    BankLinkCreateRequest:
      type: object
      description: >-
        Crea un enlace bancario. La solicitud más sencilla es `{}` más lo que
        quieras indicar: todos los campos tienen un valor por defecto.
      properties:
        mode:
          type: string
          enum:
            - connect
            - renew
          description: >-
            `connect` (predeterminado) crea una conexión nueva. `renew` requiere
            `connection_id` y reutiliza la configuración de esa conexión.
          default: connect
        connection_id:
          type: string
          description: 'La conexión que se va a renovar. Solo con `mode: renew`.'
          format: uuid
        access:
          type: string
          enum:
            - one_time
            - ongoing
          description: >-
            `one_time` (predeterminado) lee los datos una sola vez. `ongoing`
            mantiene el acceso abierto hasta que termine el consentimiento o
            alguien lo detenga. Con `institution_id` definido, un banco que no
            puede mantener el acceso abierto responde `400
            ongoing_access_not_available` antes de mostrar ninguna pantalla. Sin
            él, el selector de bancos solo muestra los que sí pueden.
          default: one_time
        country:
          type: string
          description: >-
            Opcional. Sin este campo, la persona elige entre los países que
            habilitó tu aplicación. Debe ser un país que Bank Link atienda;
            cualquier otro, incluido `ZZZ`, responde `400 invalid_request` con
            `field: country`. Un cuerpo de solicitud vacío sigue siendo válido.
          pattern: ^[A-Z]{3}$
        institution_id:
          type: string
          description: >-
            Banco opcional que preseleccionar, de `list_institutions`. Omite el
            selector.
          maxLength: 64
        segment:
          type: string
          enum:
            - personal
            - business
            - any
          description: >-
            Filtra el selector e indica al banco qué inicio de sesión abrir
            cuando el banco separa los inicios de sesión. Valor por defecto
            `any`.
          default: any
        data:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: >-
            Qué leer. `accounts` se incluye siempre: nombre, tipo, moneda,
            identificadores y el nombre del titular cuando el banco lo comparte.
            Valor por defecto `["accounts"]`.
          default:
            - accounts
          maxItems: 3
        history_days:
          type: integer
          description: >-
            Días de historial de transacciones que solicitar, de 1 a 365; por
            defecto, 90. El banco puede entregar menos: cada cuenta indica lo
            que entregó en `history_coverage`. No puede enviarse junto con
            `history_from`.
          minimum: 1
          maximum: 365
          default: 90
        history_from:
          type: string
          description: >-
            Fecha de inicio del historial que quieres solicitar, en lugar de
            `history_days`. No se puede enviar junto con `history_days`: si se
            envían ambos, responde `400 history_window_ambiguous`. Una fecha de
            hace más de 365 días, o futura, responde `400 window_not_available`.
          format: date
        extended_history:
          type: string
          enum:
            - standard
            - allow_extra_auth
          description: >-
            `allow_extra_auth` permite que un banco que pide una confirmación
            adicional libere el historial anterior.
          default: standard
        consent_days:
          type: integer
          description: >-
            Solo para monitorización continua. Cuántos días pedir al banco que
            mantenga abierto el acceso, 1 o más. Por defecto: el máximo que
            permita el banco. La conexión indica en `consent.expires_at` la
            fecha que el banco concedió realmente. Con `access: one_time`
            responde `400 invalid_request` con `field: consent_days`.
          minimum: 1
          maximum: 32767
        ownership:
          $ref: '#/components/schemas/BankLinkOwnershipRequest'
        end_user:
          $ref: '#/components/schemas/BankLinkEndUser'
        redirect_url:
          type: string
          description: >-
            Adónde va el navegador al final, con `link_id`, `status` y un
            `state` firmado (solo para mostrar: el webhook y `get_link` son la
            fuente de verdad). En una aplicación de sandbox, una dirección
            `http` simple de `localhost`, `127.0.0.1` o `[::1]` (cualquier
            puerto y ruta, sin credenciales ni fragmento) no requiere registro.
            Cualquier otra dirección responde `400 redirect_url_not_registered`:
            el registro de otras direcciones todavía no está disponible. Sin
            `redirect_url`, la persona termina en la propia página de resultados
            de Didit.
          format: uri
          maxLength: 2048
        allowed_origins:
          type: array
          items:
            type: string
            format: uri
          description: >-
            Aceptado, pero hoy no se usa: reservado para Bank Link integrado de
            Didit, que aún no se ha publicado. Orígenes HTTPS, hasta 50.
          maxItems: 50
        language:
          type: string
          description: >-
            Código de idioma opcional, como `es` o `pt-BR`. Si no se indica, se
            usa el idioma del navegador.
          pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})?$
          maxLength: 16
        vendor_data:
          type: string
          description: Su propia referencia, devuelta en el enlace y en la conexión.
          maxLength: 255
        expires_in:
          type: integer
          description: Duración del enlace en segundos, de 300 a 86400. Por defecto, 3600.
          minimum: 300
          maximum: 86400
          default: 3600
        duplicates:
          type: string
          enum:
            - reuse
            - allow
          description: >-
            `reuse` (predeterminado) completa un enlace que resuelve a cuentas
            que ya compartes como una renovación de esa conexión. `allow` crea
            una segunda conexión independiente.
          default: reuse
        allow_one_time_fallback:
          type: boolean
          description: >-
            Con `ongoing`, permite que la persona continúe con una lectura única
            en un banco que no puede mantener el acceso abierto, tras confirmar
            el acceso reducido en su propia pantalla. La cotización muestra lo
            que cuesta. Solo con `access: ongoing`: con acceso único responde
            `400 invalid_request` con `field: allow_one_time_fallback`.
          default: false
        accept_reduced_grant:
          type: boolean
          description: >-
            Cuando el banco o la persona concede menos de lo que solicitaste,
            completa el enlace y cobra solo los alcances concedidos. De lo
            contrario, el enlace termina en `failed` con `reduced_grant` y no se
            cobra nada.
          default: false
        sandbox:
          type: object
          description: >-
            Solo para aplicaciones sandbox: elige el cliente de Didit Test Bank.
            Se ignora en una aplicación en producción.
          properties:
            persona:
              type: string
              enum:
                - personal_basic
                - business_multi
                - long_history
                - pending
                - sparse_fields
                - no_ongoing
              description: >-
                El cliente de Test Bank: `personal_basic` (una cuenta corriente,
                60 movimientos), `business_multi` (tres cuentas de una empresa),
                `long_history` (una cuenta con 400 días y 1400 movimientos; una
                lectura devuelve los últimos 365 días, así que establece
                `history_days` en 365), `pending` (incluye transacciones
                pendientes), `sparse_fields` (sin fecha valor, sin IBAN de
                contraparte y sin referencia bancaria) o `no_ongoing` (un banco
                que solo permite un acceso puntual: usa
                `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: >-
                Aceptado y reservado para el simulador de sandbox: por ahora,
                los valores no cambian nada.
    BankLink:
      type: object
      description: >-
        Una ejecución de Bank Link para una persona: conectar un banco o renovar
        una conexión. Confirma tú mismo un enlace con `get_link`: nunca confíes
        en un id enviado por el navegador.
      properties:
        id:
          type: string
          description: Identificador del enlace.
          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 del enlace. `completed`, `cancelled`, `expired` y `failed`
            son estados finales.
        url:
          type: string
          description: >-
            La página alojada a la que hay que enviar a la persona. Se devuelve
            solo al crear el enlace; es `null` en las lecturas posteriores,
            porque el token no se almacena.
          nullable: true
          format: uri
        client_token:
          type: string
          description: >-
            El token del Bank Link integrado de Didit, que todavía no está
            disponible: hoy, abre `url`. Se devuelve solo al crear el enlace; en
            lecturas posteriores es `null`. Tiene un único propósito y una vida
            corta. No contiene datos personales. No lo registres nunca en logs.
          nullable: true
        expires_at:
          type: string
          description: Cuándo deja de funcionar un enlace que no se ha canjeado.
          format: date-time
        connection_id:
          type: string
          description: >-
            La conexión que creó o renovó este enlace, una vez que `status` es
            `completed`.
          format: uuid
          nullable: true
        check_id:
          type: string
          description: >-
            El resultado de propiedad de este enlace, cuando se solicitó
            `ownership.compare` distinto de `none`.
          format: uuid
          nullable: true
        reused:
          type: boolean
          description: >-
            `true` cuando el enlace se completó como una renovación de una
            conexión existente porque la persona ya comparte exactamente estas
            cuentas (`duplicates: reuse`). No se cobra dos veces.
        error:
          allOf:
            - $ref: '#/components/schemas/BankLinkError'
          nullable: true
          description: >-
            Por qué falló el enlace, cuando `status` es `failed`. En caso
            contrario, `null`.
        quote:
          $ref: '#/components/schemas/BankLinkQuote'
        vendor_data:
          type: string
          description: Su referencia de la solicitud.
          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: >-
        Cuerpo de error de cada operación de datos bancarios. Todos los campos
        están siempre 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 error legible por máquina. Decide según este valor, nunca
            según `message`.
        message:
          type: string
          description: >-
            Explicación en lenguaje sencillo para un desarrollador. La redacción
            puede cambiar; no la analices.
        request_id:
          type: string
          description: >-
            Identificador de esta solicitud. Cítalo cuando contactes con
            soporte.
        field:
          type: string
          description: >-
            El campo de la solicitud que hay que corregir, cuando el error se
            refiere a un solo campo. En caso contrario, `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é hacer a continuación, para que un cliente pueda actuar sin
            adivinar. `null` cuando no hay un siguiente paso estándar.
          nullable: true
        retry_after:
          type: integer
          description: >-
            Segundos que esperar antes de reintentar. Se establece en errores de
            límite de solicitudes y errores temporales; en otros casos, `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ón opcional del titular de la cuenta con una persona o una
        empresa.
      properties:
        compare:
          type: string
          enum:
            - none
            - person
            - business
          description: >-
            Con qué se compara el titular de la cuenta. `none` (valor por
            defecto) no emite veredicto y no requiere referencia. `person`
            requiere `reference_identity` o `session_id`. `business` requiere
            `business` o `business_session_id`. Envía exactamente una referencia
            del tipo con el que haces la comparación, y ninguna con `none`.
          default: none
        match:
          type: string
          enum:
            - any_holder
            - all_holders
          description: >-
            Si debe coincidir un titular legal o todos los titulares legales.
            Los representantes nunca cuentan.
          default: any_holder
        reference_identity:
          type: object
          description: >-
            Valores enviados por quien llama a la API para compararlos con el
            titular de la cuenta. No se pueden enviar junto con `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 sesión de verificación de Didit completada de la persona con la
            que comparar. No se puede enviar junto con `reference_identity`.
          format: uuid
        business:
          type: object
          description: La empresa que se va a comparar con el titular de la cuenta.
          properties:
            legal_name:
              type: string
              maxLength: 255
            registration_id:
              type: string
              maxLength: 128
          required:
            - legal_name
        business_session_id:
          type: string
          description: >-
            Una verificación de empresa de Didit con la que comparar. No se
            puede enviar junto con `business`.
          format: uuid
    BankLinkEndUser:
      type: object
      description: La persona o empresa que conecta la cuenta.
      properties:
        reference:
          type: string
          description: >-
            Su propio id para la persona o empresa. Se puede buscar con
            `end_user_reference` y sirve para reconocer una conexión repetida.
          maxLength: 255
        email:
          type: string
          description: >-
            Opcional. Cuando la ruta bancaria necesita una dirección verificada
            de la persona y no enviaste una, Bank Link se la pide a la persona.
            Nunca se usa con fines de marketing.
          format: email
          maxLength: 254
    BankLinkError:
      type: object
      description: >-
        El motivo por el que un enlace terminó en `failed`. No se publicó ni se
        cobró nada.
      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: >-
            Por qué falló el enlace. Un enlace fallido no es un error HTTP: el
            enlace se devuelve con `status: failed` y este objeto. Un enlace de
            renovación cuya conexión cambió entretanto devuelve
            `renewal_not_needed` o `renewal_window_expired`.
        message:
          type: string
          description: Explicación en lenguaje sencillo para un desarrollador.
        conflicts_with:
          type: array
          nullable: true
          items:
            type: string
            format: uuid
          description: >-
            Con `duplicate_conflict`: los ids de las conexiones activas que se
            solapan. Renueve una de ellas o cree de nuevo el enlace con
            `duplicates: allow`.
      required:
        - code
        - message
        - conflicts_with
    BankLinkQuote:
      type: object
      description: >-
        El precio de un enlace, fijado al crearlo. El cargo es el de la
        cotización. Las lecturas nunca generan cargos.
      properties:
        id:
          type: string
          description: Identificador de la cotización.
          format: uuid
        lines:
          type: array
          items:
            $ref: '#/components/schemas/BankLinkQuoteLine'
          description: Los conceptos que cobra este enlace, para los ámbitos que solicita.
        fallback_lines:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/BankLinkQuoteLine'
          description: >-
            Lo que cobraría un respaldo de pago único, solo cuando el enlace se
            creó con `allow_one_time_fallback`. Se muestra en la respuesta de
            creación y es `null` en caso contrario. Una lectura única con datos
            puede costar más que un primer mes de acceso continuo.
        total_usd:
          type: string
          description: >-
            Total de `lines` en USD. El total solo puede bajar: con una
            concesión reducida, o cuando la persona elige un país con un precio
            menor.
          pattern: ^-?\d+(\.\d+)?$
        valid_until:
          type: string
          description: >-
            La cotización queda fijada al enlace y es válida durante toda la
            vida del enlace, por lo que es igual a `expires_at`.
          format: date-time
        scopes:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: Los datos acotan los precios de la cotización.
      required:
        - id
        - lines
        - fallback_lines
        - total_usd
        - valid_until
        - scopes
    RateLimitBudgetError:
      type: object
      description: >-
        Se devuelve solo en un rechazo del middleware por exceder el límite de
        solicitudes. Otros errores 429, incluidos los conflictos de idempotencia
        y los límites específicos de cada endpoint, no garantizan estos campos
        de metadatos.
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: Mensaje de rechazo por presupuesto existente y legible para humanos.
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: >-
            Referencia de soporte opaca: RL- seguido de 32 caracteres
            hexadecimales en minúscula de un UUID.
        limit:
          type: integer
          description: Presupuesto del ámbito superado; es igual a X-RateLimit-Limit.
        remaining:
          type: integer
          minimum: 0
          description: >-
            Presupuesto restante, ajustado a cero; es igual a
            X-RateLimit-Remaining.
        reset:
          type: integer
          format: int64
          description: >-
            Hora de reinicio de la ventana en segundos Unix; es igual a
            X-RateLimit-Reset.
        window_seconds:
          type: integer
          description: >-
            Duración de la ventana fija en segundos, no el tiempo restante de
            espera. Respete Retry-After antes 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ínea con precio de una cotización.
      properties:
        meter:
          type: string
          description: >-
            Lo que se cobra, por ejemplo `bank_data_connection_month` o
            `bank_verification`.
          example: bank_data_connection_month
        unit:
          type: string
          description: >-
            Qué es una unidad, por ejemplo `connection_month` o
            `completed_sign_in`.
          example: connection_month
        price_usd:
          type: string
          description: >-
            Precio de una unidad en USD, cadena decimal con 4 decimales. Los
            importes de los ejemplos son ilustrativos; el precio de cada país
            aparece en la página de precios.
          pattern: ^-?\d+(\.\d+)?$
          example: '0.9000'
      required:
        - meter
        - unit
        - price_usd
  responses:
    Unauthorized:
      description: No autorizado
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: Clave de API no válida
              value:
                detail: Invalid API Key.
    RateLimitedWrite:
      description: >-
        Se superó el límite compartido de escritura de 300 solicitudes por
        minuto por clave de API. Respete `Retry-After` antes de reintentar.
      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 ha fallado por parte de Didit. Cualquier error inesperado en
        `/v3/bank/` responde con el formato de error de Bank, nunca con una
        página HTML: incluye `request_id` en tu consulta al soporte.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: Un error 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 de espera, redondeados al alza hasta la siguiente ventana.
        Presente en los rechazos por cuota del middleware.
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: >-
        El ámbito cuya cuota se superó. Presente en los rechazos por cuota del
        middleware.
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: >-
        Presupuesto del ámbito superado; es igual al límite del cuerpo. Presente
        en los rechazos por presupuesto del middleware.
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: >-
        Presupuesto restante, ajustado a cero; es igual a remaining del cuerpo.
        Está presente en los rechazos por presupuesto del middleware.
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: >-
        Tiempo de reinicio en segundos Unix; es igual a reset del cuerpo.
        Presente en los rechazos por cuota del middleware.
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        La clave de API de tu aplicación, desde Developers -> API keys en la
        Business Console. La clave principal tiene acceso completo. Una clave
        con nombre puede tener permisos limitados: ninguno, lectura o escritura
        por recurso, restringida a algunos flujos o solo a sesiones aprobadas, a
        una lista de direcciones IP y a una fecha de caducidad. 401 significa
        que la clave es incorrecta, está revocada o ha caducado; 403 significa
        que no se envió ninguna clave, que la clave no tiene acceso a este
        recurso o acción, o que la solicitud procede de una dirección fuera de
        su lista de IP; 404 en una ruta de sesión significa que la sesión está
        fuera de los flujos o estados de la clave. Una clave sin acceso a
        contenido multimedia recibe las URL de imágenes, vídeos y PDF como null,
        y una clave sin permiso de escritura en sesiones recibe los enlaces y
        tokens de sesión como null. Consulta
        https://docs.didit.me/console/api-keys.

````

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