Общая документация по BaaS Gateway API

Краткое описание

Система BaaS (Banking as a Service) Gateway предоставляет банковские услуги, такие как заказ и управление картами, получение микроредита и т.д., с помощью RESTful API. Данная документация содержит общие сведения об авторизации, структуре запросов/ответов и кодах ошибок, применимых ко всем эндпоинтам.

Base URL

Все API-эндпоинты используют общий base URL системы BaaS Gateway Service.

Авторизация

Авторизация и аутентификация обрабатываются внешним сервисом. Все запросы должны содержать данные для авторизации в заголовке Authorization с типом Bearer и JWT-токеном.

Получение JWT-токена

Endpoint: POST /oauth2/token

Headers

Authorization: Basic <consumer-key:consumer-secret (Base64)>
Content-Type: application/json

Примечание: Тип авторизации "Basic", где consumer_key используется как username, а consumer_secret как пароль. Оба параметра предоставляются банком вместе с логином и паролем пользователя.

Структура запроса

№	Name	Requires not-null	Description
1	`grant_type`	+	Тип авторизации, данное поле является константой `"password"`
2	`username`	+	Логин пользователя
3	`password`	+	Пароль пользователя

Пример запроса

{
  "grant_type": "password",
  "username": "test",
  "password": "3344122"
}

Примеры ответов

Пример успешного ответа

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "default",
  "token_type": "Bearer",
  "expires_in": 3600
}

В случае неуспешной авторизации вернётся HTTP статус код 401 (Unauthorized). Причина статуса 401 указывается в заголовке WWW-Authenticate. Данный заголовок не всегда отображает причину, например, в случае ввода случайных символов.

Пример ответа для случайных символов в Bearer Authorization

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="oauth2-resource", error="invalid_token", error_description="The token is malformed or invalid."

Пример ответа для токена с истёкшим сроком действия

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="oauth2-resource", error="invalid_token", error_description="The access token expired"

Общий формат запросов/ответов

Все API в системе BaaS имеют общую структуру запроса/ответа:

Формат запроса

{
  "id": "uuid-string",       // Уникальный идентификатор запроса (UUID)
  "params": {
    // Параметры, специфичные для конкретного эндпоинта (зависят от API)
  }
}

Формат ответа

{
  "id": "uuid-string",       // Тот же ID что и в запросе или новый UUID для операций
  "result": {
    // Данные ответа (зависят от эндпоинта)
  },
  "error": {
    "code": 123,            // Код ошибки (integer)
    "message": "Error description"  // Сообщение об ошибке (string)
  }                         // null когда операция успешна
}

Валидация

Многие API системы BaaS валидируют запросы. В случае если запрос не прошёл валидацию, возвращается ошибка со специальным кодом "4" и причиной ошибки. Причина ошибки, то есть поле "message", может изменяться в зависимости от ошибки, хотя код ошибки в случае ошибки валидации не изменяется.

Пример ошибки валидации

{
  "id": "e20ba72f-bc54-449f-ae13-7458afef64c6",
  "result": null,
  "error": {
    "code": 4,
    "message": "Validation Error. Field: params, message: Field must be not null"
  }
}

Коды ошибок

Коды ошибок указываются в поле "code" внутри объекта "error". Коды ошибок делятся на группы по диапазонам:

1-999 = Системные ошибки
1000-1999 = Бизнес-ошибки

Таблица кодов ошибок

Код	Описание
1	Unknown Error. Please contact support
2	Request contains invalid JSON format
3	Field: {field_name}, value is invalid and can't be parsed. Message: {error_message}
4	Validation Error. Field: {field_name}, message: {field_error}
5	The API doesn't support HTTP method: {not_supported_http_method}. Supported HTTP methods: {supported_http_method_list}
1000	Application not found
1001	Application is in progress
1002	Имеется просрочка в активных кредитах (Скоринг)
1003	Повышенный уровень риска по клиенту (Скоринг)
1004	External service returned null response
1005	External service returned failed response. Response code: %s, message: %s
1006	Service could not send SMS to attach card
1007	Previous SMS code for this request is not expired yet. Please confirm SMS code or wait till it expires
1008	Card is not found by params: %s
1009	SMS code is already expired
1011	Card is already attached

Примечания

Все даты в системе используют формат ISO-8601 (yyyy-MM-dd)
Все даты со временем используют формат ISO-8601 с timezone
Все ID представлены в формате UUID

Детали реализации

API реализован с использованием Spring Boot REST-контроллеров
Валидация выполняется с помощью Jakarta Validation аннотаций
DTO реализованы как Java record для неизменяемости

Реализации

API Документация Заказа Карт