Управление лимитами пользователя

Последнее обновление: 15-08-2022

В рамках банковской платформы для пользователя установлены законодательные ограничения (лимиты) на пополнение наличными, платежи, переводы и на остаток на балансе. Лимиты зависят от присвоенного пользователю уровня идентификации.

Вы можете:

Установить собственные лимиты на финансовые операции пользователя.
Получить информацию по указанным лимитам пользователя — установленным как партнером, так и банковской платформой.

Установка лимита на расходные операции пользователя

Запрос → PUT

URL /partner/openapi-limits/v1/products/{productId}/clients/{clientId}/rule

Параметры запроса

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

curl https://api.qiwi.com/partner/openapi-limits/v1/products/best-partner/clients/clientUID123/rule \
  -X PUT \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Authorization: Bearer eyJ2ZXJDM5OE***********************' \
  -d '{
    "limitValue" : {
      "type" : "MONEY",
      "value" : "300.00",
      "currency" : "RUB"
    },
    "limitType" : "CUSTOMIZABLE_EXPENSE_OPERATIONS",
    "periodType" : "ON_DAY"
  }'

Параметр	Описание	REGEX	Пример
productId	Обязательный параметр URL запроса. Идентификатор продукта: выдается партнеру при интеграции	^[A-Za-z0-9-]{1,100}$	`Prd-123-DEF-456`
clientId	Обязательный параметр URL запроса. Уникальный идентификатор пользователя в системе партнера	^[A-Za-z0-9-]{1,100}$	`Cnt-123-DEF-456`
limitType	string Обязательный параметр тела запроса. Тип лимита. Поддерживается только `CUSTOMIZABLE_EXPENSE_OPERATIONS`		`CUSTOMIZABLE_EXPENSE_OPERATIONS`
limitValue	object Обязательный параметр тела запроса. Блок с информацией о значении устанавливаемого лимита, в формате LimitData
periodType	string Обязательный параметр тела запроса. Тип периода действия лимитов. Поддерживаются только `ON_DAY` и `ON_MONTH`.		`ON_MONTH`
dateFrom	string Параметр тела запроса. Дата начала периода в формате ISO 8601 ±hh:mm с московской Time Zone. Для установки лимита с текущего момента параметр передавать не нужно.		`2023-08-01T00:00:00+03:00`
dateTill	string Параметр тела запроса. Дата окончания периода в формате ISO 8601 ±hh:mm с московской Time Zone. Для установки лимита на неопределенный срок параметр передавать не нужно.		`2027-08-01T00:00:00+03:00`

Ответ ←

В успешном ответе возвращается HTTP-статус 200 OK. Тело успешного ответа не содержит данных.

Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.

Получение информации по установленным для пользователя лимитам

Метод возвращает список сведений о лимитах, как сервисных, так и установленных партнером для пользователя. Если не указывать явно тип лимита в запросе, возвращаются все действующие лимиты для пользователя.

Запрос → GET

URL /partner/openapi-limits/v1/products/{productId}/clients/{clientId}/limits?limitTypes={limitTypes}

Параметры запроса

curl --location \
  --request GET \
  'https://api.qiwi.com/partner/openapi-limits/v1/products/best-partner/clients/clientUID123/limits' \
  -H 'Authorization: Bearer eyJ2ZXJzaW9uIRDM5OE***********************'

Параметр	Описание	REGEX	Пример
productId	Обязательный параметр URL запроса. Идентификатор продукта: выдается партнеру при интеграции	^[A-Za-z0-9-]{1,100}$	`Prd-123-DEF-456`
clientId	Обязательный параметр URL запроса. Уникальный идентификатор пользователя в системе партнера	^[A-Za-z0-9-]{1,100}$	`Cnt-123-DEF-456`
limitTypes	Параметр URL запроса. Тип лимита. Указывается для фильтрации выборки. Чтобы ограничить выборку сразу несколькими типами, укажите параметр нужное количество раз.		`CUSTOMIZABLE_EXPENSE_OPERATIONS`

Ответ ←

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

[
    {
        "maxValue": {
            "type": "MONEY",
            "value": 3000.00,
            "currency": "RUB"
        },
        "accumulatedValue": {
            "type": "MONEY",
            "value": 9.76,
            "currency": "RUB"
        },
        "remainingValue": {
            "type": "MONEY",
            "value": 2990.24,
            "currency": "RUB"
        },
        "limitPeriod": {
            "periodFrom": "2022-02-03T00:00:00+03:00",
            "periodTill": "2022-02-03T23:59:59+03:00",
            "periodType": "ON_DAY"
        },
        "limitType": "CUSTOMIZABLE_EXPENSE_OPERATIONS"
    },
    {
        "maxValue": {
            "type": "MONEY",
            "value": 200000.00,
            "currency": "RUB"
        },
        "accumulatedValue": {
            "type": "MONEY",
            "value": 9.76,
            "currency": "RUB"
        },
        "remainingValue": {
            "type": "MONEY",
            "value": 199990.24,
            "currency": "RUB"
        },
        "limitPeriod": {
            "periodFrom": "2022-02-01T00:00:00+03:00",
            "periodTill": "2022-02-28T23:59:59+03:00",
            "periodType": "ON_MONTH"
        },
        "limitType": "EXPENSE_OPERATIONS"
    },
    {
        "maxValue": {
            "type": "MONEY",
            "value": 40000.00,
            "currency": "RUB"
        },
        "accumulatedValue": {
            "type": "MONEY",
            "value": 1.57,
            "currency": "RUB"
        },
        "remainingValue": {
            "type": "MONEY",
            "value": 39998.43,
            "currency": "RUB"
        },
        "limitPeriod": {
            "periodFrom": "2022-02-01T00:00:00+03:00",
            "periodTill": "2022-02-28T23:59:59+03:00",
            "periodType": "ON_MONTH"
        },
        "limitType": "CASH_WITHDRAWAL_OPERATIONS"
    },
    {
        "maxValue": {
            "type": "MONEY",
            "value": 5000.00,
            "currency": "RUB"
        },
        "accumulatedValue": {
            "type": "MONEY",
            "value": 1.57,
            "currency": "RUB"
        },
        "remainingValue": {
            "type": "MONEY",
            "value": 4998.43,
            "currency": "RUB"
        },
        "limitPeriod": {
            "periodFrom": "2022-02-03T00:00:00+03:00",
            "periodTill": "2022-02-03T23:59:59+03:00",
            "periodType": "ON_DAY"
        },
        "limitType": "CASH_WITHDRAWAL_OPERATIONS"
    },
    {
        "maxValue": {
            "type": "MONEY",
            "value": 60000.00,
            "currency": "RUB"
        },
        "accumulatedValue": {
            "type": "MONEY",
            "value": 8.22,
            "currency": "RUB"
        },
        "remainingValue": {
            "type": "MONEY",
            "value": 59991.78,
            "currency": "RUB"
        },
        "limitPeriod": {
            "periodType": "LIFETIME"
        },
        "limitType": "BALANCE"
    }
]

В теле успешного ответа возвращается список лимитов, как сервисных, так и установленных партнером для пользователя. Если у пользователя нет счетов, то лимит на допустимый остаток (тип лимита BALANCE) не возвращается. Каждый элемент списка содержит следующие параметры:

Параметр	Тип	Описание
limitType	string	Тип лимита
limitPeriod	object	Блок с информацией о периоде действия лимита
periodType	string	Тип периода действия лимитов
periodFrom	string	Дата начала периода, в формате ISO 8601 ±hh:mm с московской Time Zone
periodTill	string	Дата окончания периода, в формате ISO 8601 ±hh:mm с московской Time Zone
maxValue	object LimitData	Блок с информацией о максимально допустимой сумме операций в рублях за указанный период для этого лимита. Для типа `BALANCE` — информация о максимально допустимой сумме остатка на счете пользователя.
accumulatedValue	object LimitData	Блок с информацией о сумме операций (израсходованная часть) в рублях за указанный период для этого лимита. Для типа лимита `BALANCE` — информация о текущем значении остатка на счете пользователя.
remainingValue	object LimitData	Блок с информацией об оставшейся (неизрасходованной) сумме в рублях за указанный период для этого лимита. Для типа лимита `BALANCE` — информация о максимально допустимой сумме, на которую пользователь может пополнить счет в настоящий момент времени.

Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.

Модели данных API

Класс LimitData

Объект с информацией о значении лимита.

Параметр	Тип	Описание
type	string	Обязательный параметр. Тип данных. Принимает значение `MONEY` (для лимитов, значения которых задаются в денежном выражении, в частности `CUSTOMIZABLE_EXPENSE_OPERATIONS`) или `INT` (для лимитов, значения которых задаются целым числом)
value	number	Обязательный параметр. Для `"type":"MONEY"`: значение с двумя десятичными разрядами. Для `"type":"INT"`: целое число.
currency	string	Валюта, ISO 4217. Только для `"type":"MONEY"`.

Справочники

Типы лимитов

Тип	Описание
BALANCE	Допустимый остаток на счете пользователя
EXPENSE_OPERATIONS	Допустимая сумма платежей и переводов
CASH_WITHDRAWAL_OPERATIONS	Допустимая сумма на снятие наличных с карт
CUSTOMIZABLE_EXPENSE_OPERATIONS	Допустимая сумма на другую операцию

Типы периодов действия лимитов

Тип	Описание
LIFETIME	Все время жизни продукта: для этого типа периода даты начала и окончания периода указывать не нужно.
ON_HOUR	Час
ON_DAY	Календарный день
ON_WEEK	Календарная неделя
ON_MONTH	Календарный месяц
ON_YEAR	Календарный год

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

В разделе описывается структура ответа на неуспешный запрос.

{
  "serviceName" : "openapi-limits",
  "errorCode" : "openapi.limits.unsupported.limit.type",
  "description" : "Undefined error. Please try to make operation later.",
  "userMessage" : "Undefined error. Please try to make operation later.",
  "dateTime" : "2022-08-10T13:42:33.843663+03:00",
  "traceId" : "b213b51102380a77"
}

Параметр	Описание
serviceName	Имя сервиса, который вернул ошибку
errorCode	Код ошибки. См. справочник кодов ошибок
dateTime	Дата и время формирования ответа
traceId	Параметр, необходимый для анализа логов. Его значение также всегда присутствует в заголовке ответа `X-B3-TraceId`
cause	Причина ошибки, опциональный параметр

Справочник кодов ошибок

Код	Описание
openapi.limits.client.not.found	Пользователь не найден
openapi.limits.client.blocked	Пользователь заблокирован
openapi.limits.wrong.date.interval	Пользователь не найден
openapi.limits.wrong.date.interval	Неправильный интервал дат (например, dateFrom позднее dateTill)
openapi.limits.unsupported.limit.type	Неподдерживаемый для установки тип лимита
openapi.limits.unsupported.limit.period	Неподдерживаемый для установки период лимита
openapi.limits.unsupported.limit.value.type	Несоответствие типа значения лимита (limitValue.type) его значению (limitValue.value)
openapi.limits.limit.value.type.mismatch	Несоответствие значения лимита его типу (например, для денежного лимита передано значение с type = INT)
openapi.limits.invalid.limit.value	Некорректное значение лимита (например, отрицательное)

Управление лимитами пользователя

Последнее обновление: 15-08-2022

Установка лимита на расходные операции пользователя

Запрос → PUT

URL /partner/openapi-limits/v1/products/{productId}/clients/{clientId}/rule

HEADERS

Параметры запроса

Ответ ←

Получение информации по установленным для пользователя лимитам

Запрос → GET

URL /partner/openapi-limits/v1/products/{productId}/clients/{clientId}/limits?limitTypes={limitTypes}

HEADERS

Параметры запроса

Ответ ←

Модели данных API

Класс LimitData

Справочники

Типы лимитов

Типы периодов действия лимитов

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

Справочник кодов ошибок