Вопросы
baas_support@qiwi.com
NAV Navbar
Примеры

CLIENTS API

Последнее обновление: 05-12-2022

API предназначен для управления клиентом и его счётом в рамках продукта BaaS. Подробности см. на explain.qiwi.com.

Используемые в тексте термины описаны в этой статье.

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

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

Авторизация

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

Схема аутентификации - Bearer.

В заголовках запроса передаётся bearer-токен в поле Authorization

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

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

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

Создание клиента

Сценарий создания клиента описан на explain.qiwi.com.

Запрос → PUT

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

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
-d '{
  "clientIpAddress": "255.255.255.255"
}'
Параметр Описание 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
clientIpAddress string
Обязательный параметр тела запроса. IP-адрес клиента, для которого партнёр отправляет запрос
валидный IPv4/IPv6 255.255.255.255, 2001:0db8:85a3:0000:0000:8a2e:0370:7334
createInactive boolean
Признак активности клиента
^true|false$ true

Ответ ←

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

{
    "clientId": "clientUID123",
    "productId": "best-partner",
    "identificationLevel": "NOT_VERIFIED",
    "active": true
}
Параметр Тип Описание
productId string Идентификатор продукта, в рамках которого создан клиент
clientId string Уникальный идентификатор клиента в системе партнёра
identificationLevel string Текущий уровень идентификации клиента
active boolean Признак активности клиента

Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.

Активация клиента

Сценарий активации клиента описан на explain.qiwi.com. Информацию о признаке активности клиента см. здесь.

Запрос → POST

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

Ответ ←

См. ответ на запрос создания клиента.

Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.

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

Метод возвращает информацию о клиенте с указанным идентификатором.

Запрос → GET

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

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
Параметр Описание 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

Ответ ←

См. ответ на запрос создания клиента.

Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.

Создание счёта

Сценарий создания счёта описан на explain.qiwi.com.

Запрос → PUT

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

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/accounts/account1
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
-d '{
  "accountCurrency": "RUB"
}'
Параметр Описание 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
accountId Обязательный параметр URL запроса. Уникальный идентификатор счёта в системе партнёра ^[A-Za-z0-9-]{1,100}$ Acc-123-DEF-456
accountCurrency string
Обязательный параметр тела запроса. Буквенный код валюты создаваемого счёта
  RUB

Коды валют

На текущий момент поддерживаются следующие валюты:

Код Описание
RUB Рубли

Ответ ←

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


{
    "clientId": "clientUID123",
    "productId": "best-partner",
    "accountId": "account1",
    "currency": "RUB",
    "ownFunds": {
        "currency": "RUB",
        "value": 10.12
    }
}
Параметр Тип Описание
productId string Идентификатор продукта, в рамках которого создан клиент
clientId string Уникальный идентификатор клиента в системе партнёра
accountId string Уникальный идентификатор счёта в системе партнёра
currency string Валюта счёта
ownFunds object Money Информация о доступных средствах на счёте клиента. Возвращается в тех случаях, когда баланс ведется в QIWI

Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.

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

Пример использования метода см. на explain.qiwi.com.

Запрос → GET

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

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/accounts/account1
-X GET
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
Параметр Описание 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
accountId Обязательный параметр URL запроса. Уникальный идентификатор счёта в системе партнёра ^[A-Za-z0-9-]{1,100}$ Acc-123-DEF-456

Ответ ←

См. ответ на запрос создания счёта для клиента.

Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.

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

Метод возвращает информацию о всех счетах клиента с указанным идентификатором.

Запрос → GET

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

curl https://api.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/accounts
-X GET
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
Параметр Описание 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

Ответ ←

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

{
    "clientId": "clientUID123",
    "productId": "best-partner",
    "accounts": {
        "account1":{
            "currency": "RUB",
            "ownFunds":{
                "value": 10.12,
                "currency":"RUB"
            }
        },
        "account2":{
            "currency": "EUR",
            "ownFunds":{
                "value": 10.12,
                "currency":"EUR"
            }
        }
    }
}
Параметр Тип Описание
productId string Идентификатор продукта, в рамках которого создан клиент
clientId string Уникальный идентификатор клиента в системе партнёра
accounts object Блок сведений о счетах клиента. Сведения о каждом счёте возвращаются во вложенном блоке с именем, равным уникальному идентификатору этого счёта в системе партнёра
currency string Валюта счёта
ownFunds object Money Информация о доступных средствах на счёте клиента. Возвращается в тех случаях, когда баланс ведется в QIWI

Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.

Отправка данных клиента

Подробности см. на explain.qiwi.com.

Запрос → PATCH

Пример запроса для события установки номера телефона для входа в приложение (SIGN_IN_PHONE_NUMBER_SET)

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/metadata \
	-X PATCH \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******' \
	-d '{ \
	"clientUseCase": "SIGN_IN_PHONE_NUMBER_SET", \
	"phoneNumber" : "79786543210" \
	}'

Пример запроса для события успешного входа в приложение (SUCCESSFUL_SIGN_IN)

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/metadata \
	-X PATCH \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******' \
	-d '{ \
	"clientUseCase": "SUCCESSFUL_SIGN_IN", \
	"signInIp" : "49.76.45.39", \
	"dateTime": "2021-01-20T14:30:00+03:00" \
	}'

Пример запроса для события успешной смена пароля для входа в приложение (SIGN_IN_PASSWORD_CHANGED)

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/metadata \
	-X PATCH \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******' \
	-d '{ \
	"clientUseCase": "SIGN_IN_PASSWORD_CHANGED", \
	"dateTime": "2021-01-20T14:30:00+03:00" \
	}'

Пример запроса для события отправки смс-подтверждения при попытке смены пароля для входа в приложение (SIGN_IN_PASSWORD_CONFIRMATION_SENT)

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/metadata \
	-X PATCH \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******' \
	-d '{ \
	"clientUseCase": "SIGN_IN_PASSWORD_CONFIRMATION_SENT", \
	"dateTime": "2021-01-20T14:30:00+03:00" \
	}'

Пример запроса для события успешной смены PIN-кода для доступа в приложение (SIGN_IN_PIN_CHANGED)

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/metadata \
	-X PATCH \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******' \
	-d '{ \
	"clientUseCase": "SIGN_IN_PIN_CHANGED", \
	"dateTime": "2021-01-20T14:30:00+03:00" \
	}'

Пример запроса для события отправки смс-подтверждения при попытке смены PIN-кода для входа в приложение (SIGN_IN_PIN_CONFIRMATION_SENT)

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/metadata \
	-X PATCH \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******' \
	-d '{ \
	"clientUseCase": "SIGN_IN_PIN_CONFIRMATION_SENT", \
	"dateTime": "2021-01-20T14:30:00+03:00" \
	}'
Параметр Описание
productId Обязательный параметр URL запроса. Идентификатор продукта, в рамках которого создан клиент
clientId Обязательный параметр URL запроса. Уникальный идентификатор клиента в системе партнёра
clientUseCase string
Обязательный параметр тела запроса. Вариант события взаимодействия с клиентом на стороне партнёра. Возможные значения:
SIGN_IN_PHONE_NUMBER_SET — клиент установил номер телефона для входа в приложение
SUCCESSFUL_SIGN_IN — успешный вход в приложение
SIGN_IN_PASSWORD_CHANGED — успешная смена пароля для входа в приложение
SIGN_IN_PASSWORD_CONFIRMATION_SENT — отправка смс-подтверждения при попытке смены пароля для входа в приложение
SIGN_IN_PIN_CHANGED — успешная смена PIN-кода для доступа в приложение
SIGN_IN_PIN_CONFIRMATION_SENT — отправка смс-подтверждения при попытке смены PIN-кода для входа в приложение

В зависимости от типа события, указанного в clientUseCase, в запросе передаются дополнительные поля:

Событие SIGN_IN_PHONE_NUMBER_SET

{
  "clientUseCase": "SIGN_IN_PHONE_NUMBER_SET",
  "phoneNumber" : "79786543210"
}

Событие SUCCESSFUL_SIGN_IN

{
  "clientUseCase": "SUCCESSFUL_SIGN_IN",
  "signInIp" : "49.76.45.39",
  "dateTime": "2021-01-20T14:30:00+03:00"
}

Прочие события

{
  "clientUseCase": "SIGN_IN_PASSWORD_CHANGED",
  "dateTime": "2021-01-20T14:30:00+03:00"
}
Параметр Описание
phoneNumber string
Параметр тела запроса. Номер телефона клиента (без знака +, только числовое значение). Передается только для варианта события SIGN_IN_PHONE_NUMBER_SET
signInIp string
Параметр тела запроса. IP-адрес клиента. Передается только для варианта события SUCCESSFUL_SIGN_IN
dateTime string
Параметр тела запроса. Дата наступления события в формате ГГГГ-ММ-ДДTЧЧ:ММ:СС+TMZ. Передается для всех вариантов событий, кроме SIGN_IN_PHONE_NUMBER_SET

Ответ ←

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

Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.

Добавление контактных данных клиента

Метод добавляет контактные данные в учётную запись клиента с указанным идентификатором.

Запрос → PUT

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

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/contact
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
-d ' {
  "phoneNumber": "79786543210",
  "email": "mary@example.com"
}
'
Параметр Описание 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
phoneNumber string Номер телефона клиента (без знака +, только цифры). \^\d{11,16}$ 79786543210
email string Электронная почта клиента   mary@example.com

Ответ ←

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

{
  "phoneNumber": "79786543210",
  "email": "mary@example.com"
}
Параметр Тип Описание
phoneNumber string Номер телефона клиента
email string Электронная почта клиента

Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.

Получение контактных данных клиента

Метод возвращает контактные данные для клиента с указанным идентификатором.

Запрос → GET

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

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/contact
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
Параметр Описание 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

Ответ ←

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

{
  "phoneNumber": "79786543210",
  "email": "mary@example.com"
}
Параметр Тип Описание
phoneNumber string Номер телефона клиента
email string Электронная почта клиента

Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.

Добавление номера телефона клиента

Метод добавляет номер телефона в учётную запись клиента с указанным идентификатором.

Запрос → PUT

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

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/contact/phone
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
-d ' {
  "value": "79786543210",
}
'
Параметр Описание 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
value string Номер телефона клиента (без знака +, только цифры). \^\d{11,16}$ 79786543210

Ответ ←

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

{
  "value": "79786543210"
}
Параметр Тип Описание
value string Установленный контактный номер телефона

Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.

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

Метод возвращает номер телефона клиента с указанным идентификатором.

Запрос → GET

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

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/contact/phone
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
Параметр Описание 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

Ответ ←

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

{
  "value": "79786543210"
}
Параметр Тип Описание
value string Телефонный номер клиента

Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.

Добавление e-mail клиента

Метод добавляет (или меняет существующий) e-mail клиента с указанным идентификатором.

Запрос → PUT

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

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/contact/email
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
-d ' {
  "value": "mary@example.com"
}'
Параметр Описание 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
value string Адрес электронной почты клиента   mary@example.com

Ответ ←

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

{
  "value": "test@example.com"
}
Параметр Тип Описание
value string Адрес электронной почты клиента

Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.

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

Метод возвращает e-mail клиента с указанным идентификатором.

Запрос → GET

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

curl https://api-test.qiwi.com/partner/openapi-clients/v1/products/best-partner/clients/clientUID123/contact/email
-X GET
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******'
Параметр Описание 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

Ответ ←

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

{
  "value": "test@example.com"
}
Параметр Тип Описание
value string Электронная почта клиента

Структура ответа в случае неуспешной обработки запроса см. в разделе Ошибки.

Уровни идентификации

Описание уровней идентификации см. на explain.qiwi.com.

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

Класс Money

Объект с информацией о сумме денежных средств.

Параметр Обязательность Тип Описание
value number Значение с двумя десятичными разрядами
currency string Валюта, ISO 4217

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

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

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

{
    "serviceName": "openapi-clients",
    "errorCode": "openapi.clients.client.not.found",
    "dateTime": "2020-07-23T20:13:22.290416+03:00",
    "traceId": "67477569e8bc6838"
}
Название Описание
serviceName Имя сервиса, который вернул ошибку
errorCode Код ошибки. См. справочник кодов ошибок
dateTime Дата и время формирование ответа
traceId Параметр, необходимый для анализа логов. Его значение также всегда присутствует в заголовках ответа (response headers) в параметре X-B3-TraceId

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

Код Описание
openapi.clients.product.not.found Продукт не найден
openapi.clients.client.not.found Клиент не найден
openapi.clients.client.blocked Клиент заблокирован
openapi.clients.internal.error В сервисе Clients произошла внутренняя ошибка
openapi.clients.client.already.exists Клиент уже существует
openapi.clients.account.already.exists Счёт уже существует
openapi.clients.account.not.found Счёт клиента не найден
openapi.clients.unsupported.currency Валюта не поддерживается
openapi.clients.unsupported.multiple.accounts.per.currency Возвращается при попытке создания более одного счёта в одной и той же валюте. Для партнёра отдельно настраивается возможность создавать несколько счетов в одной и той же валюте
openapi.clients.client.must.be.in.test.mode Клиент находится в тестовом режиме