Raiffeisenbank (Russia) Correspondences API

openapi: 3.2.0
info:
  title: Письма Correspondences API
  description: API Входящих писем в банк
  version: 1.0.0
servers:
- url: https://api.raiffeisen.ru/letters
tags:
- name: Correspondences
  description: Переписка
paths:
  /v1/correspondences:
    post:
      summary: Создание переписки
      description: Метод создания переписки
      tags:
      - Correspondences
      operationId: createCorrespondence
      parameters:
      - $ref: '#/components/parameters/AuthorizationHeader'
      - $ref: '#/components/parameters/IdTokenHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExternalCorrespondenceRequest'
            example:
              docExtId: '123456'
              topicId: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
              text: Текст письма
              docData:
                orgName: ООО Компания
                docNumber: '12345'
                docDate: '2021-07-10'
                account: '12345678901234567000'
                bic: '123456789'
                inn: '123412341234'
                kpp: '123456789'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateExternalCorrespondenceResponse'
              example:
                correspondenceId: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
                mailId: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/correspondences/query:
    post:
      summary: Получение списка переписок
      description: Метод получения списка переписок организации с фильтрацией, сортировкой и постраничной навигацией. Письма и вложения в ответе не возвращаются, статус прочтения писем не изменяется.
      tags:
      - Correspondences
      operationId: searchCorrespondences
      parameters:
      - $ref: '#/components/parameters/AuthorizationHeader'
      - $ref: '#/components/parameters/IdTokenHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchCorrespondencesRequest'
            example:
              filter:
                organization:
                  inn: '7707083893'
                directions:
                - TO_BANK
                createdAt:
                  from: '2026-07-01T00:00:00Z'
                  to: '2026-08-01T00:00:00Z'
                accounts:
                - '12345678901234567890'
                statuses:
                - OPEN
              sort:
                field: UPDATED_AT
                direction: DESC
              paging:
                offset: 0
                limit: 50
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCorrespondencesResponse'
              example:
                items:
                - id: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
                  direction: TO_BANK
                  status: OPEN
                  topic:
                    product: Торговое финансирование
                    theme: Заявки
                    clarification: Другие вопросы
                  createdAt: '2026-07-10T06:53:37Z'
                  updatedAt: '2026-07-11T09:15:02Z'
                  account: '12345678901234567890'
                  senderFirstName: Иван
                  senderMiddleName: Иванович
                  senderLastName: Иванов
                paging:
                  offset: 0
                  limit: 50
                  hasNext: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/correspondences/{id}:
    get:
      summary: Получение переписки из банка
      description: Метод получения переписки из банка по идентификатору. Устарел, используйте GET /api/external/v2/correspondences/{id}
      deprecated: true
      tags:
      - Correspondences
      operationId: getCorrespondence
      parameters:
      - name: id
        schema:
          type: string
          format: uuid
          example: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
        description: Идентификатор переписки
        in: path
        required: true
      - $ref: '#/components/parameters/AuthorizationHeader'
      - $ref: '#/components/parameters/IdTokenHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetExternalCorrespondenceResponse'
              example:
                id: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
                status: CLOSED
                topicId: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
                createdAt: '2021-07-10T06:53:37Z'
                updatedAt: '2021-07-10T06:53:37Z'
                account: '123456789'
                senderFirstName: Иван
                senderMiddleName: Иванович
                senderLastName: Иванов
                correspondenceMails:
                - id: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
                  type: TO_BANK
                  text: Текст письма
                  number: 1
                  createdAt: '2021-07-10T06:53:37Z'
                  updatedAt: '2021-07-10T06:53:37Z'
                  senderFirstName: Иван
                  senderMiddleName: Иванович
                  senderLastName: Иванов
                  attachments:
                  - number: 1
                    name: file.txt
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /v2/correspondences/{id}:
    get:
      summary: Получение переписки
      description: Метод получения переписки по идентификатору с поддержкой произвольной тематики и переписок без счета
      tags:
      - Correspondences
      operationId: getCorrespondenceV2
      parameters:
      - name: id
        schema:
          type: string
          format: uuid
          example: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
        description: Идентификатор переписки
        in: path
        required: true
      - $ref: '#/components/parameters/AuthorizationHeader'
      - $ref: '#/components/parameters/IdTokenHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetExternalCorrespondenceV2Response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    ExternalSearchDateTime:
      type: string
      pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
      description: Дата и время в формате ISO 8601, строго UTC (`Z`), без дробной части
      example: '2026-07-10T06:53:37Z'
    DateTimeRange:
      type: object
      description: Диапазон дат. Граница from включается в выборку, граница to — исключается
      example:
        from: '2026-07-01T00:00:00Z'
        to: '2026-08-01T00:00:00Z'
      properties:
        from:
          description: Начало диапазона (включительно)
          $ref: '#/components/schemas/DateTimeWithOffset'
        to:
          description: Конец диапазона (исключительно)
          $ref: '#/components/schemas/DateTimeWithOffset'
    CreateExternalCorrespondenceResponse:
      properties:
        correspondenceId:
          type: string
          format: uuid
          description: Идентификатор переписки
          example: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
        mailId:
          type: string
          format: uuid
          description: Идентификатор первого письма
          example: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
      required:
      - correspondenceId
      - mailId
    GetExternalCorrespondenceResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Идентификатор переписки
          example: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
        status:
          description: Статус переписки
          $ref: '#/components/schemas/ExternalCorrespondenceStatus'
        topicId:
          type: string
          format: uuid
          description: Идентификатор темы переписки
          example: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
        createdAt:
          description: Время создания переписки
          $ref: '#/components/schemas/DateTime'
        updatedAt:
          description: Время обновления переписки
          $ref: '#/components/schemas/DateTime'
        account:
          type: string
          description: Номер счета
          example: '123456789'
        senderFirstName:
          type: string
          description: Имя инициатора
          example: Иван
        senderMiddleName:
          type: string
          description: Отчетсво инициатора
          example: Иванович
        senderLastName:
          type: string
          description: Фамилия инициатора
          example: Иванов
        correspondenceMails:
          type: array
          description: Письма переписки
          example: []
          items:
            $ref: '#/components/schemas/ExternalCorrespondenceMail'
      required:
      - id
      - topicId
      - createdAt
      - updatedAt
      - senderFirstName
      - senderLastName
      - correspondenceMails
    ExternalOrganizationFilter:
      type: object
      description: Идентификатор организации для поиска переписок. Необходимо передать хотя бы одно из полей `inn` или `cnum`. Если переданы оба, они должны относиться к одной организации. КПП допустим только вместе с ИНН/КИО
      example:
        inn: '7707083893'
        kpp: '773601001'
      properties:
        inn:
          type: string
          description: ИНН/КИО организации. Для КИО допустимо 5 цифр, для ИНН — 10 или 12 цифр
          pattern: (0|[0-9]{5})|([0-9]{10})|([0-9]{12})
          maxLength: 12
          example: '7707083893'
        cnum:
          type: string
          description: Внутренний идентификатор организации (CNUM)
          pattern: (.*\S.*|)
          minLength: 1
          example: CB1234567
        kpp:
          type: string
          description: КПП организации. Необязателен, если организация однозначно определяется по ИНН/КИО
          pattern: (.*\S.*|)
          minLength: 1
          example: '773601001'
    ExternalPagingRequest:
      type: object
      description: Параметры постраничной навигации
      example:
        offset: 0
        limit: 50
      properties:
        offset:
          type: integer
          format: int32
          description: Количество пропускаемых записей
          minimum: 0
          default: 0
          example: 0
        limit:
          type: integer
          format: int32
          description: Максимальное количество записей в ответе
          minimum: 1
          maximum: 100
          default: 50
          example: 50
    ErrorResponse:
      type: object
      description: Ошибка обработки запроса
      example:
        message: Validation failed
        error:
          code: BAD_REQUEST
          message: Validation failed
      properties:
        message:
          type: string
          description: Текст ошибки в устаревшем формате, сохранённый для обратной совместимости
          example: Validation failed
        error:
          type: object
          description: Структурированная информация об ошибке
          example:
            code: VALIDATION_ERROR
            message: Validation failed
          properties:
            code:
              type: string
              description: Машиночитаемый код ошибки
              example: VALIDATION_ERROR
            message:
              type: string
              description: Описание ошибки
              example: Validation failed
          required:
          - code
          - message
      required:
      - error
    SearchCorrespondencesResponse:
      type: object
      description: Список переписок
      properties:
        items:
          type: array
          description: Переписки, удовлетворяющие условиям отбора
          example: []
          items:
            $ref: '#/components/schemas/ExternalCorrespondenceCard'
        paging:
          description: Параметры постраничной навигации
          $ref: '#/components/schemas/ExternalPagingResponse'
      required:
      - items
      - paging
    CreateExternalCorrespondenceRequest:
      type: object
      properties:
        docExtId:
          type: string
          description: Идентификатор документа
          example: '123456'
        topicId:
          type: string
          format: uuid
          description: Идентификатор темы письма
          example: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
        text:
          type: string
          description: Текст письма
          minLength: 1
          maxLength: 4000
          pattern: .*(\S|\n).*
          example: Текст письма
        docData:
          $ref: '#/components/schemas/ExternalDocData'
      required:
      - docData
      - docExtId
      - topicId
      - text
    GetExternalCorrespondenceV2Response:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Идентификатор переписки
          example: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
        direction:
          description: Направление переписки
          $ref: '#/components/schemas/ExternalCorrespondenceDirection'
        status:
          description: Статус переписки
          $ref: '#/components/schemas/ExternalCorrespondenceStatus'
        topic:
          $ref: '#/components/schemas/ExternalCorrespondenceTopic'
        createdAt:
          description: Время создания переписки
          $ref: '#/components/schemas/DateTime'
        updatedAt:
          description: Время обновления переписки
          $ref: '#/components/schemas/DateTime'
        account:
          type:
          - string
          - 'null'
          description: Номер счета
          example: '123456789'
        senderFirstName:
          type: string
          description: Имя инициатора
          example: Иван
        senderMiddleName:
          type:
          - string
          - 'null'
          description: Отчество инициатора
          example: Иванович
        senderLastName:
          type: string
          description: Фамилия инициатора
          example: Иванов
        correspondenceMails:
          type: array
          description: Письма переписки
          items:
            $ref: '#/components/schemas/ExternalCorrespondenceMail'
          example: []
      required:
      - id
      - direction
      - status
      - topic
      - createdAt
      - updatedAt
      - account
      - senderFirstName
      - senderMiddleName
      - senderLastName
      - correspondenceMails
    ExternalCorrespondenceTopic:
      type:
      - object
      - 'null'
      description: Названия составляющих тематики переписки; null, если тематические данные не заполнены
      example:
        product: Торговое финансирование
        theme: Заявки
        clarification: Другие вопросы
      properties:
        product:
          type:
          - string
          - 'null'
          description: Продукт
          example: Торговое финансирование
        theme:
          type:
          - string
          - 'null'
          description: Тема
          example: Заявки
        clarification:
          type:
          - string
          - 'null'
          description: Уточнение
          example: Другие вопросы
    SearchCorrespondencesRequest:
      type: object
      description: Запрос на получение списка переписок
      properties:
        filter:
          description: Условия отбора переписок
          $ref: '#/components/schemas/ExternalCorrespondenceFilter'
        sort:
          description: Параметры сортировки. По умолчанию сортировка по времени обновления по убыванию
          $ref: '#/components/schemas/ExternalCorrespondenceSort'
        paging:
          description: Параметры постраничной навигации. По умолчанию offset = 0, limit = 50
          $ref: '#/components/schemas/ExternalPagingRequest'
      required:
      - filter
      - paging
    ExternalCorrespondenceFilter:
      type: object
      description: Условия отбора переписок
      example:
        organization:
          inn: '7707083893'
        directions:
        - TO_BANK
        accounts:
        - '12345678901234567890'
        statuses:
        - OPEN
      properties:
        organization:
          description: Идентификатор организации. Необходимо передать хотя бы одно из полей — ИНН/КИО или CNUM
          $ref: '#/components/schemas/ExternalOrganizationFilter'
        directions:
          type: array
          description: Направления переписок. Пустой список или отсутствие поля — отбираются оба направления
          items:
            $ref: '#/components/schemas/ExternalCorrespondenceDirection'
          example:
          - TO_BANK
        createdAt:
          description: Диапазон времени создания переписки
          $ref: '#/components/schemas/DateTimeRange'
        updatedAt:
          description: Диапазон времени последнего обновления переписки
          $ref: '#/components/schemas/DateTimeRange'
        accounts:
          type: array
          description: Номера счетов. Пустой список или отсутствие поля — фильтрация по счёту не выполняется. При непустом списке переписки без счёта не возвращаются. Если хотя бы один из указанных счетов недоступен пользователю, запрос завершается с ошибкой 403
          items:
            type: string
            example: '12345678901234567890'
          example:
          - '12345678901234567890'
        statuses:
          type: array
          description: Статусы переписок. Пустой список или отсутствие поля — фильтрация по статусу не выполняется
          items:
            $ref: '#/components/schemas/ExternalCorrespondenceStatus'
          example:
          - OPEN
      required:
      - organization
    ExternalDocData:
      type: object
      description: Общие реквизиты платёжного документа ДБО
      example:
        orgName: ООО Компания
        docNumber: '12345'
        docDate: '2021-07-10'
        account: '12345678901234567890'
        bic: '123456789'
        inn: '123412341234'
        kpp: '123456789'
      properties:
        orgName:
          type: string
          description: Наименование организации
          minLength: 1
          maxLength: 160
          example: ООО Компания
        docNumber:
          type: string
          description: Номер документа
          pattern: ([1-9][0-9]{0,5})
          maxLength: 6
          example: '12345'
        docDate:
          description: Дата составления документа
          $ref: '#/components/schemas/Date'
        account:
          type: string
          description: Номер счёта или корр. счёта, 20 цифр
          pattern: ([0-9]{20})
          maxLength: 20
          example: '12345678901234567890'
        bic:
          type: string
          description: БИК, 9 цифр
          pattern: ([0-9]{9})
          maxLength: 9
          example: '123456789'
        inn:
          type: string
          description: ИНН/КИО юридического или физического лица РФ, для КИО допустимо 5 символов, для ИНН 10 или 12 цифр
          pattern: (0|[0-9]{5})|([0-9]{10})|([0-9]{12})
          maxLength: 12
          example: '123412341234'
        kpp:
          type: string
          description: КПП, 9 цифр, 6-я позиция м.б. буква лат. буква 12 цифр
          pattern: (.*\S.*|)
          example: '123456789'
      required:
      - docNumber
      - docDate
      - account
      - bic
      - inn
    ExternalPagingResponse:
      type: object
      description: Параметры постраничной навигации
      example:
        offset: 0
        limit: 50
        hasNext: false
      properties:
        offset:
          type: integer
          format: int32
          description: Количество пропущенных записей
          example: 0
        limit:
          type: integer
          format: int32
          description: Максимальное количество записей в ответе
          example: 50
        hasNext:
          type: boolean
          description: Признак наличия следующей страницы
          example: false
        totalCount:
          type: integer
          format: int64
          description: Общее количество записей, удовлетворяющих условиям отбора
          example: 128
      required:
      - offset
      - limit
      - hasNext
    ExternalMailAttachment:
      type: object
      properties:
        number:
          type: integer
          description: Номер вложения
          example: 1
        name:
          type: string
          description: Название вложения
          example: file.txt
      required:
      - number
      - name
    ExternalCorrespondenceCard:
      type: object
      description: Краткая карточка переписки без писем и вложений
      properties:
        id:
          type: string
          format: uuid
          description: Идентификатор переписки
          example: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
        direction:
          description: Направление переписки
          $ref: '#/components/schemas/ExternalCorrespondenceDirection'
        status:
          description: Статус переписки
          $ref: '#/components/schemas/ExternalCorrespondenceStatus'
        topic:
          $ref: '#/components/schemas/ExternalCorrespondenceTopic'
        createdAt:
          description: Время создания переписки
          $ref: '#/components/schemas/ExternalSearchDateTime'
        updatedAt:
          description: Время последнего обновления переписки
          $ref: '#/components/schemas/ExternalSearchDateTime'
        account:
          type:
          - string
          - 'null'
          description: Номер счёта. Отсутствует, если переписка создана без привязки к счёту
          example: '12345678901234567890'
        senderFirstName:
          type: string
          description: Имя инициатора переписки
          example: Иван
        senderMiddleName:
          type:
          - string
          - 'null'
          description: Отчество инициатора переписки
          example: Иванович
        senderLastName:
          type: string
          description: Фамилия инициатора переписки
          example: Иванов
      required:
      - id
      - direction
      - status
      - topic
      - createdAt
      - updatedAt
      - account
      - senderFirstName
      - senderMiddleName
      - senderLastName
    DateTime:
      type: string
      pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
      description: Дата и время в UTC в формате yyyy-MM-dd'T'HH:mm:ss'Z'
      example: '2021-07-10T06:53:37Z'
    ExternalCorrespondenceDirection:
      type: string
      description: Направление переписки относительно клиента. TO_BANK — от клиента в банк, FROM_BANK — из банка клиенту
      enum:
      - FROM_BANK
      - TO_BANK
      example: TO_BANK
    Date:
      type: string
      pattern: ([0-9]{4})-([0-9]{2})-([0-9]{2})
      description: yyyy-MM-dd
      example: '2021-07-10'
    ExternalCorrespondenceStatus:
      type: string
      description: Статус переписки; промежуточные статусы закрытия относятся к OPEN
      enum:
      - OPEN
      - CLOSED
      example: OPEN
    ExternalMailType:
      type: string
      description: Направление письма относительно клиента
      example: TO_BANK
      enum:
      - TO_BANK
      - FROM_BANK
    ExternalCorrespondenceMail:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Идентификатор письма
          example: bf1d1868-a98e-4ae5-976f-0c4e21e0d510
        type:
          description: Тип письма
          $ref: '#/components/schemas/ExternalMailType'
        text:
          type: string
          description: Текст письма
          example: Текст письма
        number:
          type: integer
          description: Номер письма
          example: 1
        createdAt:
          description: Время создания письма
          $ref: '#/components/schemas/DateTime'
        updatedAt:
          description: Время обновления письма
          $ref: '#/components/schemas/DateTime'
        senderFirstName:
          type: string
          description: Имя отправителя
          example: Иван
        senderMiddleName:
          type: string
          description: Отчетсво отправителя
          example: Иванович
        senderLastName:
          type: string
          description: Фамилия отправителя
          example: Иванов
        attachments:
          type: array
          description: Информация о вложениях
          items:
            $ref: '#/components/schemas/ExternalMailAttachment'
      required:
      - id
      - type
      - text
      - number
      - createdAt
      - updatedAt
      - senderFirstName
      - senderLastName
      - attachments
    ExternalCorrespondenceSort:
      type: object
      description: Параметры сортировки
      example:
        field: UPDATED_AT
        direction: DESC
      properties:
        field:
          type: string
          description: Поле сортировки
          default: UPDATED_AT
          enum:
          - CREATED_AT
          - UPDATED_AT
          example: UPDATED_AT
        direction:
          type: string
          description: Порядок сортировки
          default: DESC
          enum:
          - ASC
          - DESC
          example: DESC
    DateTimeWithOffset:
      type: string
      pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$
      description: Дата и время в формате ISO 8601 с обязательным указанием часового пояса — UTC (`Z`) или смещения (`±hh:mm`). Дробная часть секунды необязательна
      example: '2026-07-10T09:53:37.123456+03:00'
  parameters:
    IdTokenHeader:
      name: Id-Token
      in: header
      description: Идентификационный токен пользователя
      required: true
      schema:
        type: string
        format: byte
        example: SUQgVE9LRU4gRk9SIFRFU1RJTkc=
    AuthorizationHeader:
      name: Authorization
      in: header
      description: Токен доступа
      required: true
      schema:
        type: string
        format: byte
        example: Bearer QXV0aG9yaXphdGlvbiBIZWFkZXIgRm9yIFRlc3Rpbmc=
  responses:
    Unauthorized:
      description: Аутентификация не пройдена
    InternalError:
      description: Внутренняя ошибка