ym88659208ym87991671
Технические требования банка | Документация для разработчиков
Развернуть

Технические требования банка

Обновлено 21 января 2026

При создании спецификации своего сервиса соблюдайте приведенные требования.

Если спецификация не соответствует описанным требованиям, она не пройдет автоматическую валидацию.

Пример спецификации, соответствующей требованиям
openapi: 3.0.0
info:
  title: Пример описания API 
  version: 1.0.0
paths:
  /organization/{organizationId}:
    get:
      tags: 
        - Работа с организациями
      summary: Получить информацию об организации
      operationId: getOrgInfo
      parameters:
        - name: organizationId
          in: path
          description: Уникальный идентификатор организации
          required: true
          schema:
            type: number
            minimum: 1
            maximum: 500
          example: "102"
      responses:
        '200':
          description: ОК 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getOrganizationInfo'
        '400':
          description: Ошибка валидации входных данных
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Требуется авторизация
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Авторизация прошла, но доступ запрещен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Ресурс не найден
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Превышен rate limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Сервис временно недоступен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    delete:
      tags:
        - Работа с организациями
      summary: Удалить организацию
      operationId: deleteOrg
      parameters:
        - name: organizationId
          in: path
          description: Уникальный идентификатор организации
          required: true
          schema:
            type: number
            minimum: 1
            maximum: 500
          example: "78"
      responses:
        '204':
          description: Успешный запрос без содержимого
        '400':
          description: Ошибка валидации входных данных
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Требуется авторизация
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Авторизация прошла, но доступ запрещен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Ресурс не найден
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Превышен rate limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Сервис временно недоступен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
 
  /organization/create:
    post:
      tags: 
        - Работа с организациями
      summary: Создать организацию
      operationId: createOrg
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organizationName:
                  type: string
                  pattern: ^[A-Za-zА-Яа-яее]+$
                  minLength: 1
                  maxLength: 255
                  description: Наименование организации
                  example: "ПАО СБЕРБАНК"
                inn:
                  type: number
                  minLength: 10
                  maxLength: 12
                  description: ИНН организации
                  example: 7707083893
                kpp:
                  type: number
                  minLength: 9
                  maxLength: 9
                  description: КПП организации
                  example: 773601001  
                dateCreate:
                  type: string
                  format: date-time
                  description: Дата и время создания карточки с часовым поясом
                  example: "2025-12-01T18:00:00-05:00"

      responses:
        '201':
          description: Организация успешно создана
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizationId:
                    type: number
                    minimum: 1
                    maximum: 500
                    description: Уникальный идентификатор организации
                    example: 177
                  message:
                    type: string
                    description: Сообщение об успешном создании
                    example: "Organization created successfully"
                example:
                  id: "177"
                  message: "Organization created successfully"
        '204':
          description: Успешный запрос без содержимого
        '400':
          description: Ошибка валидации входных данных
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Требуется авторизация
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Авторизация прошла, но доступ запрещен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Конфликт (например, дубликат)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Ошибка бизнес-логики
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Превышен rate limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Сервис временно недоступен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /organization/change:
    put:
      tags: 
        - Работа с организациями
      summary: Изменить информацию об организации
      operationId: updateOrgInfo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                inn:
                    type: number
                    minLength: 10
                    maxLength: 12
                    description: ИНН организации
                    example: 7707083893
                kpp:
                    type: number
                    minLength: 9
                    maxLength: 9
                    description: КПП организации
                    example: 773601001
                organizationName:
                    type: string
                    pattern: ^[A-Za-zА-Яа-яее]+$
                    minLength: 5
                    maxLength: 255
                    description: Наименование организации
                    example: "ПАО СБЕРБАНК"
                numberOfEmployees:
                    type: number
                    description: Количество сотрудников
                    minimum: 1
                    example: 1000
                isActive:
                    type: boolean
                    description: Активна ли организация
                    example: true
                products:
                    type: array
                    description: Список продуктов
                    maxItems: 10
                    items:
                      type: object
                      properties:
                        productId:
                          type: number
                          description: Идентификатор продукта
                          example: 50085
                          minimum: 5
                        productName:
                          type: string
                          description: Название продукта
                          pattern: ^[A-Za-zА-Яа-яее]+$
                          example: "Продукт 1"                
 
      responses:
        '200':
          description: Организация успешно обновлена
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  message:
                    type: string
                example:
                  id: "10009"
                  message: "Организация успешно обновлена"
        '204':
          description: Успешный запрос без содержимого
        '400':
          description: Ошибка валидации входных данных
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Требуется авторизация
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Авторизация прошла, но доступ запрещен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Конфликт (например, дубликат)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Ошибка бизнес-логики
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Превышен rate limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Сервис временно недоступен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error_code:
          type: string
          description: Код ошибки
          example: "VALIDATION_ERROR"
        message:
          type: string
          description: Описание ошибки
          example: "Ошибка валидации данных"
        details:
          type: array
          description: Подробности ошибки
          maxItems: 100
          items:
            type: object
            properties:
              field:
                type: string
                description: Поле, где произошла ошибка
                example: "company_id"
              issue:
                type: string
                description: Проблема с полем
                example: "Обязательное поле"
              resolution:
                type: string
                description: Рекомендация по исправлению
                example: "Укажите корректный идентификатор"
        request_id:
          type: string
          description: Идентификатор запроса для отладки
          example: "req_123456"
    getOrganizationInfo:
      type: object
      required:
        - inn
        - kpp
        - organizationName
        - numberOfEmployees
        - isActive
      properties:
        inn:
          type: number
          description: ИНН организации
          minLength: 10
          maxLength: 12
          example: "7707083893"
        kpp:
          type: number
          description: КПП организации
          minLength: 9
          maxLength: 9
          example: "773601001"
        organizationName:
          type: string
          description: Название организации
          pattern: ^[A-Za-zА-Яа-яее]+$
          maxLength: 255
          example: "ПАО СБЕРБАНК"
        numberOfEmployees:
          type: number
          description: Количество сотрудников
          minimum: 1
          example: 100
        isActive:
          type: boolean
          description: Активна ли организация
          example: true
        products:
          type: array
          description: Список продуктов
          maxItems: 10
          items:
            type: object
            properties:
              productId:
                type: number
                description: Идентификатор продукта
                minimum: 5
                maximum: 999999
                example: 50085
              productName:
                type: string
                description: Название продукта
                maxLength: 255
                pattern: ^[A-Za-zА-Яа-яее]+$
                example: "Продукт 1"

Безопасность и авторизация

При работе с учетными данными для доступа к сервису (credentials) запрещается:

  • передача по электронной почте;
  • хранение в открытом виде или в репозитории.

Ограничение частоты запросов

Указание RPS необязательно, но поможет для контроля нагрузки на ваши сервера. Лимит задается для каждой компании отдельно.

По умолчанию — не более 5 запросов в секунду.

При превышении лимита должна возвращаться ошибка 429.

Таймаут

API должно отвечать за 15 секунд. Более длительное ожидание потребует отдельного подхода и дополнительного времени на разработку.

Требования к полям

Соблюдайте следующие требования при описании полей.

Строковые поля

При описании полей типа string:

  • Указывайте длину строк с помощью свойств по длине minLength / maxLength.
  • Используйте format со значениями из OpenAPI-спецификации или JSON-Schema-draft-04.7.
  • Ограничивайте длину строк с помощью значений pattern или format.

Если типы не указаны явно модель может сгенерировать некорректный запрос.

Правильно

company_name:
  type: string
  minLength: 1
  maxLength: 255
  pattern: "^[а-яА-Яееa-zA-Z0-9 \\-.,()]*$"
  description: "Название компании"
  example: "ООО Ромашка"

Неправильно

company_name:
  type: string
  description: "Название компании"

Форматы времени

Для контроля часовых поясов, некоторые операции могут быть чувствительны к дате и времени.

Рекомендуется указывать время в соответствии с ISO 8601 вместе с timezone.

created_at:
  type: string
  format: date-time
  description: "Дата и время создания (ISO 8601)"
  example: "2024-01-15T10:30:00+03:00"

Допускается использование Unix timestamp.

timestamp:
  type: integer
  format: int64
  description: "Unix timestamp в секундах"
  example: 1705300200

Массивы

Обязательно указывайте максимальное количество элементов массива maxItems. Это позволит избежать DoS-атак с большими ответами и снизит время отклика при работе с большими датасетами.

Используйте пагинацию, если ваш API возвращает большие списки.

Правильно

items:
  type: array
  maxItems: 100
  description: "Список заказов (max 100 элементов)"
  items:
    $ref: '#/components/schemas/Order'

Неправильно

items:
  type: array
  items:
    $ref: '#/components/schemas/Order'

Типы данных

У всех полей обязательно должен быть явно задано поле type.

Использование произвольных типов запрещено.

Числовые значения

Числовые значения должны содержать допустимый диапазон minimum/maximum и описание формата: int32, int64, float или double.

Правильно

amount:
  type: number
  format: float
  minimum: 0
  maximum: 999999999.99
  description: "Сумма в рублях"
  example: 1500.50

Неправильно

amount:
  type: number

Перечисления

Пример описания перечисления.

status:
  type: string
  enum: ["pending", "processing", "completed", "cancelled"]
  description: "Статус заказа"
  example: "completed"

HTTP-методы и статусы

Ваш API может поддерживать методы GET, POST, PUT и DELETE.

Ниже примеры описания методов в формате OpenAPI-спецификации.

/organization/{organizationId}:
  get:
    tags: 
      - Работа с организациями
    summary: Получить информацию об организации
    operationId: getOrgInfo
    parameters:
      - name: organizationId
        in: path
        description: Уникальный идентификатор организации
        required: true
        schema:
          type: number
          minimum: 1
          maximum: 500
        example: "102"
    responses:
    ...

Требования к статусам и ошибкам

Блок responses должен содержать стандартные HTTP-статусы:

  • 200 — Успешный запрос (используется чаще всего).
  • 201 — Ресурс успешно создан (POST запросы).
  • 204 — Успешный запрос без content (DELETE).
  • 400 — Ошибка валидации входных данных.
  • 401 — Требуется авторизация.
  • 403 — Авторизация прошла, но доступ запрещен.
  • 404 — Ресурс не найден.
  • 409 — Конфликт (например, дубликат).
  • 422 — Ошибка бизнес-логики.
  • 429 — Превышен rate limit.
  • 500 — Внутренняя ошибка сервера.
  • 503 — Сервис временно недоступен.

Формат ошибок:

{
  "error_code": "VALIDATION_ERROR",
  "message": "Ошибка валидации данных",
  "details": [
    {
      "field": "company_id",
      "issue": "Обязательное поле",
      "resolution": "Укажите корректный идентификатор"
    }
  ],
  "request_id": "req_123456"
}

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней

Это полезный материал?
Развернуть
ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей. Вы можете запретить сохранение cookie в настройках своего браузера.