Перейти к содержанию

Протокол

Оглавление

Схема классов

/svg/protos/key/keyapis/invoice/v1/keyapis_invoice_invoice_v1.proto.svg

keyapis/invoice/v1/keyapis_invoice_invoice_v1.proto

Сервис реализует функционал управления выставленными счётами

InvoiceService

Сервис invoices

Название метода Описание Тип запроса Тип ответа
CreateInvoice Метод создания платежа. Создание платежа в своей и внешней платежной системе. Метод доступен для: service keyapis.invoice.v1.CreateInvoiceRequest keyapis.invoice.v1.CreateInvoiceResponse
GetInvoice Метод получения платежа. Для master доступно получение платежа только с user_id из токена. Метод доступен для: admin, service, master keyapis.invoice.v1.GetInvoiceRequest keyapis.invoice.v1.GetInvoiceResponse
PostInvoiceConfirm Метод подтверждения платежа (вызывается со стороны внешней системы). Не требует авторизации keyapis.invoice.v1.PostInvoiceConfirmRequest keyapis.invoice.v1.PostInvoiceConfirmResponse
GetInvoiceList Метод получения списка платежей. Для master доступно получение только собственных платежей, если параметр filter.user_id передан и не совпадает с user_id из токена, возвращается ошибка доступа. Метод доступен для: admin, service, master, ltp_first keyapis.invoice.v1.GetInvoiceListRequest keyapis.invoice.v1.GetInvoiceListResponse
GetInvoiceCount Метод получения количества платежей. Для master в параметр filter.user_id подставляется user_id из токена. Метод доступен для: admin, service, master, ltp_first keyapis.invoice.v1.GetInvoiceCountRequest keyapis.invoice.v1.GetInvoiceCountResponse

CreateInvoiceRequest

Запрос на создание платежа

Поле Описание Тип Признак
user_id Идентификатор пользователя int32 REQUIRED
positions Позиция счета repeated keyapis.invoice.v1.Invoice.Position REQUIRED
pay_interface_type Метод платежа keyapis.invoice.v1.Invoice.PayInterfaceType REQUIRED
payway_type Способ оплаты. По умолчанию: BANK_CARD keyapis.invoice.v1.Invoice.PaywayType
return_url Ссылка для перехода после оплаты. Если не передан подставится значение по умолчанию string
phone_number Номер телефона. Должно быть означено поле phone_number, либо поле email string
email Электронная почта. Должно быть означено поле phone_number, либо поле email string
title Описание платежа. По умолчанию подставляется "Счёт от {DD.MM.YYYY}г." string

CreateInvoiceResponse

Ответ на запрос создание платежа

Поле Описание Тип Признак
error Ошибка валидации optional keyapis.invoice.v1.CreateInvoiceResponse.Error
data Платеж optional keyapis.invoice.v1.Invoice

CreateInvoiceResponse.Error

Ошибка запроса

Поле Описание Тип Признак
validation Ошибка валидации optional keyapis.invoice.v1.ValidationError
missing_user_contacts Должно быть означено поле phone_number, либо поле email optional keyapis.invoice.v1.CreateInvoiceResponse.Error.MissingUserContacts
external Ошибки внешней системы optional keyapis.invoice.v1.Invoice.ExternalError
saving Ошибка сохранения optional keyapis.invoice.v1.Invoice.SavingError

CreateInvoiceResponse.Error.MissingUserContacts

Должно быть означено поле phone_number, либо поле email

GetInvoiceCountRequest

Запрос на получение количества платежей

Поле Описание Тип Признак
filter Фильтр keyapis.invoice.v1.InvoiceFilter REQUIRED

GetInvoiceCountResponse

Ответ на запрос получения количества платежей

Поле Описание Тип Признак
data Количество optional int32

GetInvoiceListRequest

Запрос на получение списка платежей

Поле Описание Тип Признак
filter Фильтр keyapis.invoice.v1.InvoiceFilter
paging Пагинация optional keyapis.invoice.v1.InvoicePaging

GetInvoiceListResponse

Ответ на запрос получения списка платежей

Поле Описание Тип Признак
data Платежи repeated keyapis.invoice.v1.Invoice
error Ошибка keyapis.invoice.v1.GetInvoiceListResponse.Error

GetInvoiceListResponse.Error

Ошибка запроса на получение списка платежей

Поле Описание Тип Признак
validation Ошибка валидации optional keyapis.invoice.v1.ValidationError

GetInvoiceRequest

Запрос на получение статуса платежа

Поле Описание Тип Признак
invoice_id Идентификатор платежа в Ключе. # Тип: Guid string REQUIRED

GetInvoiceResponse

Ответ на запрос получения платежа

Поле Описание Тип Признак
error Ошибка optional keyapis.invoice.v1.GetInvoiceResponse.Error
data Платеж optional keyapis.invoice.v1.Invoice

GetInvoiceResponse.Error

Ошибка запроса

Поле Описание Тип Признак
validation Ошибка валидации optional keyapis.invoice.v1.ValidationError

Invoice

Выставленный счёт

Поле Описание Тип Признак
id Идентификатор платежа. # Тип: Guid string REQUIRED
title Описание платежа string REQUIRED
user_id Идентификатор пользователя int32 REQUIRED
invoice_status_type Статус платежа keyapis.invoice.v1.Invoice.InvoiceStatusType REQUIRED
created_at Дата создания платежа. # Тип: DateTime google.protobuf.Timestamp REQUIRED
updated_at Дата обновления платежа. # Тип: DateTime google.protobuf.Timestamp REQUIRED
positions Позиция счета repeated keyapis.invoice.v1.Invoice.Position REQUIRED
pay_interface_type Метод платежа keyapis.invoice.v1.Invoice.PayInterfaceType
payway_type Способ оплаты keyapis.invoice.v1.Invoice.PaywayType
status_changed_at Дата изменения статуса платежа. # Тип: DateTime google.protobuf.Timestamp
paid_at Дата платежа. # Тип: DateTime google.protobuf.Timestamp
pay_url Платежная ссылка string
paid_by_card_masked Маскированный номер карты при платеже string
paid_by_card_espp_id Идентификатор платежного средства в внешней системы string
card_type Тип банковской карты keyapis.invoice.v1.Invoice.CardType
espp_req_status Код ошибки внешней системы int32
espp_req_user_msg Комментарий к статусу платежа из внешней системы string
espp_invoice_id Уникальный номер транзакции в внешней системы string
phone_number Номер телефона string
email Электронная почта string

Invoice.ExternalError

Ошибки внешней системы

Поле Описание Тип Признак
external_system_error Запрос к внешней системе вернул ошибку или прекращен по таймауту optional keyapis.invoice.v1.Invoice.ExternalError.ExternalSystemError

Invoice.ExternalError.ExternalSystemError

Запрос к внешней системе вернул ошибку или прекращен по таймауту

Invoice.Position

Позиция счета

Поле Описание Тип Признак
id Идентификатор позиции. # Тип: Guid string
invoice_id Идентификатор платежа. # Тип: Guid string REQUIRED
title Название позиции string REQUIRED
category Категория позиции (='subscription') string REQUIRED
amount Цена в рублях. Число должно быть больше 0 float REQUIRED
created_at Дата создания позиции платежа. # Тип: DateTime google.protobuf.Timestamp OUTPUT_ONLY
updated_at Дата обновления позиции платежа. # Тип: DateTime google.protobuf.Timestamp OUTPUT_ONLY
mrf_id Идентификатор МРФ int32 REQUIRED
rf_id Идентификатор РФ int32 REQUIRED
instance_id Идентификатор экземпляра оплачиваемой подписки. # Тип: Guid string REQUIRED
offering_id Идентификатор предложения оплачиваемой подписки int32 REQUIRED
due_date_at Срок окончания оплачиваемого периода google.protobuf.Timestamp
svc_type_id Идентификатор получателя платежа string
is_discount Признак скидки bool

Invoice.SavingError

Ошибка сохранения. Эти проверки выполняются при работе с базой данных и сторонними сервисами

Поле Описание Тип Признак
invoice_already_exists У пользователя уже есть платеж со статусом PENDING optional keyapis.invoice.v1.Invoice.SavingError.InvoiceAlreadyExists

Invoice.SavingError.InvoiceAlreadyExists

У пользователя уже есть платеж со статусом PENDING

InvoiceFilter

Фильтр инвойсов

Поле Описание Тип Признак
user_id Идентификатор пользователя int32
invoice_status_type Статус платежа keyapis.invoice.v1.Invoice.InvoiceStatusType

InvoicePaging

Постраничный вывод

Поле Описание Тип Признак
order_by_type Тип значения сортировки. Если значение не передано, то будет взято значение по умолчанию. # По умолчанию: PAID_AT keyapis.invoice.v1.InvoicePaging.OrderByType
direction_type Тип направления сортировки. # По умолчанию: DESC keyapis.invoice.v1.InvoicePaging.DirectionType
limit Количество записей на страницу. Если значение 0 (не передано), то будет взято значение по умолчанию. # Диапазон: 0..100. # По умолчанию: 20 int32
offset Сдвиг. # Диапазон: 0..2147483647 int32

PostInvoiceConfirmRequest

Запрос на подтверждение платежа

Поле Описание Тип Признак
src_pay_id Идентификатор платежа в Ключе string REQUIRED
espp_pay_id Идентификатор платежа во внешней системе string REQUIRED
pay_status Статус платежа из внешней системы int32 REQUIRED
req_type Тип запроса. Должно иметь значение "confirmPayment" string REQUIRED
amount Сумма платежа в минимальных единицах валюты float
currency Код валюты платежа string
pay_method Код способа оплаты string
create_time_at Дата регистрации платежа. # Тип: DateTime google.protobuf.Timestamp
req_note Комментарий или сообщение об ошибке string
req_user_msg Сообщение, отображаемое пользователю string
pay_time_at Время фактической оплаты. Время фактической оплаты на стороне Процессинга. Возвращается, если оплата состоялась google.protobuf.Timestamp
abandon_time_at Время фактической отмены оплаты. Время фактической отмены оплаты на стороне Процессинга. Возвращается, если отмена оплаты состоялась google.protobuf.Timestamp
card Структура с информацией о карте плательщика. Передаётся только при успешном платеже и если указаны способы оплаты payMethod = StoredBankCard либо BankCard keyapis.invoice.v1.PostInvoiceConfirmRequest.Card

PostInvoiceConfirmRequest.Card

Структура с информацией о карте плательщика

Поле Описание Тип Признак
espp_card_id Идентификатор платежного средства во внешней системы. Возвращается в случае успешной привязки БК к УЗ int32
card_num Номер платежного средства. Маскированный номер карты. Например: 123456******7890 string
card_kind Тип банковской карты string
bank_name Банк-эмитент. Наименование банка-эмитента. Процессинг может вернуть значение "НЕ ЗАДАВАЛСЯ". В этом случае рекомендуется не отображать эту информацию для пользователя string

PostInvoiceConfirmResponse

Ответ на запрос подтверждения платежа

Invoice.CardType

Справочник банковских карт

Номер Тип Название
0 CARD_TYPE_UNKNOWN Значение не указано
1 VISA Карта VISA
2 EC_MC Карта EuroCard/MasterCard
3 DCL Карта DinersClub
4 JCB Карта JCB
5 AMEX Карта American Express
6 MIR Платежная система "Мир"

Invoice.InvoiceStatusType

Справочник типов статусов оплаты счёта

Номер Тип Название
0 INVOICE_STATUS_TYPE_UNKNOWN Значение не указано
1 PLANNED Создан, ожидает подтверждения
2 PENDING Ожидает оплаты
3 ERROR Ошибка оплаты
4 PAID Оплачен
5 CANCELLED Отменен

Invoice.PayInterfaceType

Справочник методов платежа

Номер Тип Название
0 PAY_INTERFACE_TYPE_UNKNOWN Значение не указано
1 GUI Оплата через интерфейс предпроцессинга
2 M2M Оплата с использованием ранее созданного способа платежа, настроенного по умолчанию

Invoice.PaywayType

Справочник типов платежных средств

Номер Тип Название
0 PAYWAY_TYPE_UNKNOWN Значение не указано
1 BANK_CARD Банковская карта
2 SBP Сервис быстрых платежей
3 SBER_PAY Связка Сбербанка

InvoicePaging.DirectionType

Справочник типов направлений сортировки.

Тип: byte

Номер Тип Название
0 DIRECTION_TYPE_UNKNOWN Значение не указано
1 DESC От большего к меньшему
2 ASC От меньшего к большему

InvoicePaging.OrderByType

Справочник типов значений сортировки.

Тип: byte

Номер Тип Название
0 ORDER_BY_TYPE_UNKNOWN Значение не указано
1 ID По идентификатору
2 PAID_AT По дате оплаты
3 CREATED_AT По дате создания

Скалярные типы значений

.proto Type Примечание Python Go Ruby C# C++ Java PHP
double float float64 Float double double double float
float float float32 Float float float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int int32 Bignum or Fixnum (as required) int int32 int integer
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int/long int64 Bignum long int64 long integer/string
uint32 Uses variable-length encoding. int/long uint32 Bignum or Fixnum (as required) uint uint32 int integer
uint64 Uses variable-length encoding. int/long uint64 Bignum or Fixnum (as required) ulong uint64 long integer/string
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int int32 Bignum or Fixnum (as required) int int32 int integer
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int/long int64 Bignum long int64 long integer/string
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. int uint32 Bignum or Fixnum (as required) uint uint32 int integer
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. int/long uint64 Bignum ulong uint64 long integer/string
sfixed32 Always four bytes. int int32 Bignum or Fixnum (as required) int int32 int integer
sfixed64 Always eight bytes. int/long int64 Bignum long int64 long integer/string
bool boolean bool TrueClass/FalseClass bool bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. str/unicode string String (UTF-8) string string String string
bytes May contain any arbitrary sequence of bytes. str []byte String (ASCII-8BIT) ByteString string ByteString string