> ## 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: один институт и его возможности

> Эндпоинт Get an Institution в Didit возвращает один банк с его возможностями и состоянием.

Endpoint Get an Institution от Didit возвращает один банк с его возможностями и состоянием.
Значение, которое никогда не наблюдалось, возвращается как `null`, а не как догадка.


## OpenAPI

````yaml ru/openapi-25.json GET /v3/bank/institutions/{id}/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API верификации личности. Аутентификация через заголовок x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      Bank Link, подключения, счета, балансы, транзакции, учреждения и покрытие.
      Банковские данные доступны для приложений в песочнице. Вызовы из
      приложения в продакшн-среде возвращают `404`, пока доступ к такой среде не
      объявлен. В песочнице ничего не списывается. Вызов, выполненный с
      API-ключом, требует ключа с разрешением на банковские данные
      (`bank-data`): read для чтения, write для операций, которые что-то меняют.
      Проверка счёта является исключением: для неё нужен доступ write к сессиям
      или полный доступ, а не разрешение на банковские данные. Банковские данные
      не входят в полный доступ: ключ с полным доступом отклоняется, и вызов
      возвращает `403 bank_data_access_denied`, пока вы не создадите ключ с этим
      разрешением. Необработанные банковские данные (счета, балансы, транзакции
      и лента изменений) также отклоняют запрос без API-ключа.


      Каждый отказ под `/v3/bank/`, кроме отказа проверки счёта, имеет одно и то
      же тело JSON (`code`, `message`, `request_id`, `field`, `next_action`,
      `retry_after`). Путь, который не является операцией, идентификатор,
      который не является UUID, или неизвестный подресурс возвращают `404
      not_found` для любого метода, а любая непредвиденная ошибка возвращает
      `500 internal_error` с `request_id`. Там, где банковские данные
      недоступны, каждая операция возвращает стандартный `404` платформы, точно
      так же, как неизвестный маршрут.
paths:
  /v3/bank/institutions/{id}/:
    get:
      tags:
        - Bank Data
      summary: Получить финансовое учреждение
      description: >-
        Возвращает один банк и его возможности. Идентификатор является slug
        Didit, как в ответе `list_institutions`.


        Нужен API-ключ с разрешением «Данные банка» (`bank-data`): чтение для
        этой операции. Ключ с полным доступом это разрешение не включает:
        выдайте его явно при создании ключа, иначе вызов вернёт `403
        bank_data_access_denied`.
      operationId: getBankInstitution
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Идентификатор учреждения, например `es-banco-norte`.
      responses:
        '200':
          description: Банк.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankInstitution'
              examples:
                Spanish bank:
                  summary: Испанский банк, который предоставляет постоянный доступ
                  value:
                    id: es-banco-norte
                    name: Banco Norte
                    country: ESP
                    logo_url: https://static.example.com/banks/es-banco-norte.png
                    timezone: Europe/Madrid
                    segments:
                      - personal
                      - business
                    access:
                      - one_time
                      - ongoing
                    ongoing_access: true
                    consent_days_max: 180
                    history_days_max: 365
                    pending_transactions: true
                    pending_linkage: false
                    balance_types:
                      - booked
                      - available
                    transaction_fields:
                      - value_date
                      - counterparty_name
                      - counterparty_iban
                      - remittance
                      - bank_transaction_code
                      - bank_reference
                      - balance_after
                    sign_in: redirect
                    requires_end_user_email: true
                    corporate_accounts: true
                    bank_account_selection: false
                    separate_history_consent: false
                    reconfirmation: false
                    sync_frequency_hours: null
                    health: operational
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BankDataAccessDenied'
        '404':
          description: Ресурс не существует в этом приложении и среде.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not found:
                  summary: Не найдено
                  value:
                    code: not_found
                    message: The resource does not exist.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: null
                    retry_after: null
        '429':
          $ref: '#/components/responses/RateLimitedRead'
        '500':
          $ref: '#/components/responses/BankDataInternalError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            curl
            'https://verification.didit.me/v3/bank/institutions/es-banco-norte/'
            \
              -H 'x-api-key: YOUR_API_KEY'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.bank.get_institution(
                "your-id",
            )
            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.getInstitution("your-id");
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.GetInstitution(ctx, \"your-id\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: |-
            import me.didit.Didit;

            // Reads DIDIT_API_KEY.
            Didit client = new Didit();

            var result = client.bank().getInstitution("your-id");
            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->getInstitution('your-id');
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.bank.get_institution("your-id")
            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.GetInstitutionAsync("your-id");
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    BankInstitution:
      type: object
      description: >-
        Банк и его возможности. Значения берутся из данных о наблюдаемых
        возможностях и обновляются ежедневно. Значение, которое ни разу не
        наблюдалось, равно `null`, а не предположение.
      properties:
        id:
          type: string
          description: Идентификатор банка в Didit, стабильный слаг.
          example: es-banco-norte
        name:
          type: string
        country:
          type: string
          pattern: ^[A-Z]{3}$
        logo_url:
          type: string
          format: uri
          nullable: true
        timezone:
          type: string
          description: Часовой пояс IANA, в котором указаны даты банка.
          nullable: true
        segments:
          type: array
          items:
            type: string
            enum:
              - personal
              - business
        access:
          type: array
          items:
            type: string
            enum:
              - one_time
              - ongoing
          description: >-
            `ongoing` указывается только для банков, где включен постоянный
            доступ.
        ongoing_access:
          type: boolean
          description: Доступен ли постоянный доступ в этом банке.
        consent_days_max:
          type: integer
          description: >-
            Самое длительное согласие, которое разрешает банк, в днях. `null`,
            если не наблюдалось.
          nullable: true
        history_days_max:
          type: integer
          description: >-
            Максимальная глубина истории, которую отдаёт банк, в днях. `null`,
            если не наблюдалась.
          nullable: true
        pending_transactions:
          type: boolean
          nullable: true
          description: Передаёт ли банк ожидающие транзакции.
        pending_linkage:
          type: boolean
          nullable: true
          description: >-
            Связывает ли банк ожидающую транзакцию с проведённой, что и задаёт
            `pending_id`.
        balance_types:
          type: array
          items:
            type: string
            enum:
              - booked
              - available
              - expected
        transaction_fields:
          type: array
          items:
            type: string
          description: >-
            Поля транзакции, которые, как известно, передаёт банк. Все остальные
            поля имеют значение `null`.
        sign_in:
          type: string
          enum:
            - redirect
            - app_approval
            - credentials
            - null
          description: Как пользователь входит в банк.
          nullable: true
        requires_end_user_email:
          type: boolean
          nullable: true
          description: >-
            Требует ли Bank Link подтверждённый адрес электронной почты у
            человека.
        corporate_accounts:
          type: boolean
          nullable: true
          description: Поддерживаются ли счета компаний.
        bank_account_selection:
          type: boolean
          nullable: true
          description: Выбирает ли человек счета в банке, а не в Bank Link.
        separate_history_consent:
          type: boolean
          nullable: true
          description: >-
            Требует ли банк ещё одно подтверждение для предоставления более
            ранних данных истории.
        reconfirmation:
          type: boolean
          nullable: true
          description: Можно ли подтвердить продление на экране Didit без входа в банк.
        sync_frequency_hours:
          type: integer
          description: >-
            Количество часов между автоматическими синхронизациями, если банк
            допускает более частый график. `null` означает ежедневный режим по
            умолчанию.
          nullable: true
        health:
          type: string
          enum:
            - operational
            - degraded
            - down
      required:
        - id
        - name
        - country
        - logo_url
        - timezone
        - segments
        - access
        - ongoing_access
        - consent_days_max
        - history_days_max
        - pending_transactions
        - pending_linkage
        - balance_types
        - transaction_fields
        - sign_in
        - requires_end_user_email
        - corporate_accounts
        - bank_account_selection
        - separate_history_consent
        - reconfirmation
        - sync_frequency_hours
        - health
    BankDataError:
      type: object
      description: >-
        Тело ошибки для каждой операции с банковскими данными. Все поля всегда
        присутствуют.
      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: >-
            Машиночитаемый код ошибки. Ориентируйтесь на него в логике
            обработки, но никогда не на `message`.
        message:
          type: string
          description: >-
            Пояснение простым языком для разработчика. Формулировка может
            измениться; не разбирайте её программно.
        request_id:
          type: string
          description: Идентификатор этого запроса. Укажите его при обращении в поддержку.
        field:
          type: string
          description: >-
            Поле запроса, которое нужно исправить, если ошибка относится к
            одному полю. В остальных случаях `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: >-
            Какие действия выполнить дальше, чтобы клиент мог действовать без
            догадок. `null`, если стандартного следующего шага нет.
          nullable: true
        retry_after:
          type: integer
          description: >-
            Количество секунд ожидания перед повторной попыткой. Задаётся при
            ошибках превышения лимита и при временных ошибках, иначе `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
    RateLimitBudgetError:
      type: object
      description: >-
        Возвращается только при отказе middleware из-за исчерпания бюджета
        лимита запросов. Другие ошибки 429, включая конфликты идемпотентности и
        ограничения конкретного endpoint, не гарантируют эти поля метаданных.
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: Существующее понятное человеку сообщение об отказе по бюджету.
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: >-
            Непрозрачный идентификатор для службы поддержки: RL- и затем 32
            шестнадцатеричных символа UUID в нижнем регистре.
        limit:
          type: integer
          description: Бюджет области, в которой превышен лимит; равен X-RateLimit-Limit.
        remaining:
          type: integer
          minimum: 0
          description: >-
            Оставшийся бюджет, приведённый к нулю; совпадает с
            X-RateLimit-Remaining.
        reset:
          type: integer
          format: int64
          description: Время сброса окна в секундах Unix; равно X-RateLimit-Reset.
        window_seconds:
          type: integer
          description: >-
            Длительность фиксированного окна в секундах, а не оставшееся время
            ожидания. Учитывайте Retry-After перед повторной попыткой.
      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
  responses:
    Unauthorized:
      description: Не авторизован
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: Недействительный API-ключ
              value:
                detail: Invalid API Key.
    BankDataAccessDenied:
      description: >-
        API-ключ не имеет разрешения на доступ к банковским данным (`bank-data`)
        или, для необработанных банковских данных в продакшн-приложении,
        отключена настройка приложения «Bank data in the API». Банковские данные
        не входят в полный доступ: ключ с полным доступом, ключ с ограничением
        на другие ресурсы и запрос без API-ключа (client credentials, для
        необработанных данных) отклоняются с этим ответом, поэтому создайте ключ
        и выдайте разрешение явно. Отказ происходит до любого поиска, поэтому он
        ничего не говорит о том, существует ли объект.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Bank data not allowed:
              summary: Доступ к банковским данным не разрешён
              value:
                code: bank_data_access_denied
                message: >-
                  Bank data calls need an API key that carries the Bank data
                  permission.
                request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                field: null
                next_action: enable_bank_data_access
                retry_after: null
    RateLimitedRead:
      description: >-
        Превышен лимит чтения middleware. Соблюдайте Retry-After перед повторной
        попыткой.
      headers:
        Retry-After:
          $ref: '#/components/headers/BudgetRetryAfter'
        X-RateLimit-Scope:
          $ref: '#/components/headers/BudgetXRateLimitScope'
        X-RateLimit-Limit:
          $ref: '#/components/headers/BudgetXRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/BudgetXRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/BudgetXRateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitBudgetError'
          example:
            detail: >-
              GET request rate limit exceeded. You can make up to 600 requests
              per minute.
            reference: RL-00000000000040008000000000000001
            limit: 600
            remaining: 0
            reset: 1794358860
            window_seconds: 60
    BankDataInternalError:
      description: >-
        Что-то пошло не так на стороне Didit. Любая непредвиденная ошибка в
        `/v3/bank/` возвращается в формате ошибки Bank, а не в виде
        HTML-страницы: укажите `request_id` в обращении в поддержку.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: Непредвиденная ошибка
              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: >-
        Секунды ожидания, округлённые вверх до следующего окна. Присутствует при
        отказах middleware из-за исчерпания бюджета.
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: >-
        Область, бюджет которой превышен. Присутствует при отказах middleware
        из-за исчерпания бюджета.
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: >-
        Бюджет области, в которой превышен лимит; равен лимиту в теле ответа.
        Присутствует при отказах по бюджету промежуточного ПО.
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: >-
        Оставшийся бюджет, приведённый к нулю; совпадает с remaining в теле
        ответа. Присутствует в отказах из-за бюджета middleware.
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: >-
        Время сброса в секундах Unix; равно reset в теле ответа. Присутствует
        при отказах middleware из-за исчерпания бюджета.
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API-ключ вашего приложения берётся в разделе Developers -> API keys в
        Business Console. Основной ключ имеет полный доступ. Именованный ключ
        можно ограничить: доступ для каждого ресурса (нет доступа, только чтение
        или запись), ограничение некоторыми сценариями или одобренными сессиями,
        список IP-адресов и дата истечения срока. Ответ 401 означает, что ключ
        неверный, отозван или истёк. Ответ 403 означает, что ключ не передан, у
        ключа нет доступа к этому ресурсу или действию либо запрос пришёл с
        адреса вне его списка IP. Ответ 404 на маршруте сессии означает, что
        сессия находится вне сценариев или статусов, доступных ключу. Ключ без
        доступа к медиа получает URL изображений, видео и PDF как null, а ключ
        без права записи в сессии получает ссылки и токены сессий как null. См.
        https://docs.didit.me/console/api-keys.

````

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