Управление лимитами

Подробности использования методов API см. в разделе «Руководства по интеграции» → BaaS → «Лимиты».

Взаимодействие через API

Взаимодействие между партнёром и BaaS совершается по защищённому протоколу (HTTPS). Поддерживаются только HTTPS-запросы. HTTP-запросы по нешифрованному каналу не поддерживаются.

Данные в запросах передаются в формате JSON в кодировке UTF-8. В ответах данные возвращаются также в формате JSON в кодировке UTF-8.

URL для вызовов API

https://api-test.qiwi.com - testing окружение;
https://api.qiwi.com - production окружение.

Доступ к API

Схема аутентификации - Bearer. В заголовках запроса передаётся bearer-токен в поле Authorization.

--header "Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******"

Bearer-токен выдается партнёру при интеграции.

Авторизация

За авторизацию отвечает обязательный заголовок запроса QIWI-Client-Token. Подробности см. в разделе «Руководства по интеграции» → BaaS → «Общие принципы и правила» → «Подтверждение операций».

--header "QIWI-Client-Token: fa9c491b7b06c6cf64a0b53fb2b9a91c"

Установка партнёрских лимитов

Запрос → 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***********************' \
  -H 'QIWI-Client-Token: fa9c491b7b06c6cf64a0b53fb2b9a91c' \
  -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».

Получение информации о лимитах

Подробности см. в разделе «Руководства по интеграции» → BaaS → «Лимиты» → «Получение информации о лимитах».

Запрос → 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***********************' \
  -H 'QIWI-Client-Token: fa9c491b7b06c6cf64a0b53fb2b9a91c'

Параметр	Описание	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"
    }
]

Параметр	Тип	Описание
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	Блок с информацией о верхней границе лимита
accumulatedValue	object LimitData	Блок с информацией об израсходованной сумме в рамках лимита
remainingValue	object LimitData	Блок с информацией об остатке в рамках лимита

Подробное описание с примерами см. в разделе «Руководства по интеграции» → BaaS → «Лимиты» → «Свойства лимитов».

Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок 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

См. информацию из раздела «Руководства по интеграции» → BaaS → «Тестирование» → «Работа с ошибками».

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

Код	Описание
openapi.limits.client.not.found	Клиент не найден
openapi.limits.client.blocked	Клиент заблокирован
openapi.limits.ip.address.not.allowed	Запросы с этого IP адреса не разрешены
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	Некорректное значение лимита: например, отрицательное
openapi.limits.client.token.not.found	Не найден активный токен клиента
openapi.limits.client.token.mismatch	Токен, переданный в запросе, не совпадает с выпущенным для клиента токеном
openapi.limits.client.token.header.is.missing	Отсутствует заголовок QIWI-Client-Token, обязательный для продуктов с поддержкой клиентских токенов
openapi.limits.client.token.not.enabled	Поддержка клиентских токенов отключена для продукта

Управление лимитами

Взаимодействие через API

URL для вызовов API

Доступ к API

Авторизация

Установка партнёрских лимитов

Запрос → 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

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