Протокол¶
Оглавление¶
-
keyapis/rfidregistry/v1/keyapis_rfidregistry_record_v1.proto
- DeleteRecordResponse
- DeleteRecordResponse.Error
- GetRecordCountRequest
- GetRecordCountResponse
- GetRecordCountResponse.Error
- GetRecordListRequest
- GetRecordListResponse
- GetRecordListResponse.Error
- GetRecordRequest
- GetRecordResponse
- PostRecordRequest
- PostRecordResponse
- PostRecordResponse.Error
- Record
- Record.AesKeyConfiguration
- Record.DataCell
- Record.SavingError
- Record.SavingError.AlreadyLinked
- Record.SavingError.Conflict
- Record.SavingError.OwnedByAnotherUser
- Record.SavingError.StatusTypeRestricted
- Record.SavingError.UidExist
- Record.Trailer
- RecordFilter
- RecordPaging
- Record.IdentificationMethodType
- Record.RfidType
- Record.StatusType
- RecordPaging.DirectionType
- RecordPaging.OrderByType
Схема классов¶
keyapis/rfidregistry/v1/keyapis_rfidregistry_record_v1.proto¶
Сервис реализует функционал регистрации в системе RFID-ключей. Только зарегистрированные RFID-ключи доступны для активации пользователям
RecordService¶
Сервис реестра ключей
| Название метода | Описание | Тип запроса | Тип ответа |
|---|---|---|---|
| PostRecord | Метод сохранения записи. Нельзя отвязать ключ, который привязал кто-то другой. Разрешения: rfidregistry:record:save. Метод доступен для: Token: seller, employee, application, service, device_admin, ltp_first, admin, master, owner, mrf, bti, manager, external_seller. При наличии разрешений | keyapis.rfidregistry.v1.PostRecordRequest | keyapis.rfidregistry.v1.PostRecordResponse |
| GetRecord | Метод получения записи. Разрешения: rfidregistry:record:card. Метод доступен для: Token: seller, employee, application, service, device_admin, ltp_first, admin, master, owner, mrf, bti, manager, external_seller. При наличии разрешений | keyapis.rfidregistry.v1.GetRecordRequest | keyapis.rfidregistry.v1.GetRecordResponse |
| GetRecordList | Метод получения списка записей. Разрешения: rfidregistry:record:list. Метод доступен для: Token: seller, employee, application, service, device_admin, ltp_first, admin, master, owner, mrf, bti, manager, external_seller. При наличии разрешений | keyapis.rfidregistry.v1.GetRecordListRequest | keyapis.rfidregistry.v1.GetRecordListResponse stream |
| GetRecordCount | Метод получения количества записей. Разрешения: rfidregistry:record:list. Метод доступен для: Token: seller, employee, application, service, device_admin, ltp_first, admin, master, owner, mrf, bti, manager, external_seller. При наличии разрешений | keyapis.rfidregistry.v1.GetRecordCountRequest | keyapis.rfidregistry.v1.GetRecordCountResponse |
| DeleteRecord | Метод удаления записи. Можно удалять только свои записи. Нельзя удалить ключ, если его использует кто-то другой. Разрешения: rfidregistry:record:remove. Метод доступен для: Token: seller, employee, application, service, device_admin, ltp_first, admin, master, owner, mrf, bti, manager, external_seller. При наличии разрешений | keyapis.rfidregistry.v1.DeleteRecordRequest | keyapis.rfidregistry.v1.DeleteRecordResponse |
DeleteRecordRequest¶
Запрос удаления записи из реестра. Можно удалить только свои записи
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| id | Идентификатор записи. # Тип: Guid | string | REQUIRED |
DeleteRecordResponse¶
Ответ на запрос удаления записи из реестра
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| error | Ошибка | optional keyapis.rfidregistry.v1.DeleteRecordResponse.Error |
DeleteRecordResponse.Error¶
Ошибка удаления записи
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| validation | Ошибка валидации | optional keyapis.rfidregistry.v1.ValidationError |
GetRecordCountRequest¶
Запрос получения количества записей
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| filter | Фильтр | keyapis.rfidregistry.v1.RecordFilter |
GetRecordCountResponse¶
Ответ на запрос получения количества записей
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| data | Всего записей | optional int32 | |
| error | Ошибка | optional keyapis.rfidregistry.v1.GetRecordCountResponse.Error |
GetRecordCountResponse.Error¶
Ошибка запроса получения количества записей
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| validation | Ошибка фильтрации записей | optional keyapis.rfidregistry.v1.ValidationError |
GetRecordListRequest¶
Запрос получения списка
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| filter | Фильтр | keyapis.rfidregistry.v1.RecordFilter | |
| paging | Пагинация | optional keyapis.rfidregistry.v1.RecordPaging |
GetRecordListResponse¶
Ответ на запрос получения списка записей
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| data | Запись | optional keyapis.rfidregistry.v1.Record | |
| error | Ошибка | optional keyapis.rfidregistry.v1.GetRecordListResponse.Error |
GetRecordListResponse.Error¶
Ошибка запроса получения списка записей
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| validation | Ошибка фильтрации записей | optional keyapis.rfidregistry.v1.ValidationError |
GetRecordRequest¶
Запрос получения записи
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| id | Идентификатор. # Тип: Guid | string | REQUIRED |
GetRecordResponse¶
Ответ на запрос получения записи
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| data | Запись | optional keyapis.rfidregistry.v1.Record |
PostRecordRequest¶
Запрос сохранения записи
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| data | Запись | keyapis.rfidregistry.v1.Record | REQUIRED |
PostRecordResponse¶
Ответ на запрос сохранения записи
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| data | Запись | optional keyapis.rfidregistry.v1.Record | |
| error | Ошибка | optional keyapis.rfidregistry.v1.PostRecordResponse.Error |
PostRecordResponse.Error¶
Ошибка запроса сохранения записи
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| validation | Ошибка валидации | optional keyapis.rfidregistry.v1.ValidationError | |
| saving | Ошибка сохранения записи | optional keyapis.rfidregistry.v1.Record.SavingError |
Record¶
Запись.
Описание модели¶
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| id | Идентификатор. Если не передан создаётся сервером. # Тип: Guid | string | |
| rfid_type | Тип ключа | keyapis.rfidregistry.v1.Record.RfidType | REQUIRED |
| encryption_type | Тип шифрования ключа. Максимально поддерживаемый ключом тип шифрования | keyapis.rfidregistry.v1.Record.EncryptionType | REQUIRED |
| uid | Номер ключа. Указывается при создании. # Диапазон: 1..14 | string | REQUIRED |
| status_type | Тип статуса ключа | keyapis.rfidregistry.v1.Record.StatusType | REQUIRED |
| new_at | Дата перевода в статус "Новый". # Тип: DateTime | google.protobuf.Timestamp | OUTPUT_ONLY |
| shipped_at | Дата перевода в статус "Отгружен". # Тип: DateTime | google.protobuf.Timestamp | OUTPUT_ONLY |
| defect_at | Дата перевода в статус "Брак". # Тип: DateTime | google.protobuf.Timestamp | OUTPUT_ONLY |
| in_use_at | Дата перевода в статус "Использован". # Тип: DateTime | google.protobuf.Timestamp | OUTPUT_ONLY |
| in_use_rfid_id | Идентификатор привязанного ключа. Заполняется при переводе в статус "Использован". # Диапазон: 0..16 | google.protobuf.StringValue | |
| data_cells | Содержимое ячеек ключа | repeated keyapis.rfidregistry.v1.Record.DataCell | |
| resource_owner_id | Идентификатор владельца. Заполняется сервером. # Диапазон: 0..255 | string | OUTPUT_ONLY |
| package_info_box | Номер коробки. # Диапазон: 1..2147483647 | int32 | |
| package_info_place | Номер места в коробке. # Диапазон: 1..2147483647 | int32 | |
| changed_at | Дата последнего изменения. Заполняется и обновляется сервером. Заполняется при создании и изменении. Является версией объекта. # Тип: DateTime | google.protobuf.Timestamp | OUTPUT_ONLY |
| aes_key_configurations | Конфигурации шифрования ключа | repeated keyapis.rfidregistry.v1.Record.AesKeyConfiguration | |
| trailers | Контрольные суммы. Нужны для ключей SL1 и SL3 | repeated keyapis.rfidregistry.v1.Record.Trailer | |
| order_number | Номер заказа. # Диапазон: 0..256 | string | REQUIRED |
| order_at | Дата заказа. # Тип: DateTime | google.protobuf.Timestamp | REQUIRED |
| in_use_resource_owner_id | Владелец привязанного ключа. Заполняется сервером, значение берётся из токена при использовании ключа. # Диапазон: 0..255 | google.protobuf.StringValue | OUTPUT_ONLY |
| is_deleted | Признак, удалена ли запись | bool | OUTPUT_ONLY |
| deleted_at | Дата удаления. # Тип: DateTime | google.protobuf.Timestamp | OUTPUT_ONLY |
| vendor_name | Производитель. # Диапазон: 3..100 | google.protobuf.StringValue | |
| identification_method_type | Метод идентификации | keyapis.rfidregistry.v1.Record.IdentificationMethodType |
Record.AesKeyConfiguration¶
Конфигурация шифрования ключа
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| address | Адрес. # Паттерн: /^[A-Za-z0-9=]+$/ | string | REQUIRED |
| data | Данные. # Паттерн: /^[A-Za-z0-9=]+$/ | string | REQUIRED |
Record.DataCell¶
Содержимое ячейки ключа
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| section | Сектор. # Диапазон: 0..127 | int32 | REQUIRED |
| block | Блок. # Диапазон: 0..127 | int32 | REQUIRED |
| data | Данные. # Паттерн: /^[A-Za-z0-9=]+$/ | string | REQUIRED |
Record.SavingError¶
Ошибка сохранения записи. Эти проверки выполняются при работе с базой данных и сторонними сервисами
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| status_type_restricted | Перевод статуса запрещён | optional keyapis.rfidregistry.v1.Record.SavingError.StatusTypeRestricted | |
| uid_exist | Запись уже существует | optional keyapis.rfidregistry.v1.Record.SavingError.UidExist | |
| owned_by_another_user | Вы не владелец | optional keyapis.rfidregistry.v1.Record.SavingError.OwnedByAnotherUser | |
| already_linked | Ключ уже использован | optional keyapis.rfidregistry.v1.Record.SavingError.AlreadyLinked | |
| conflict | Конфликт версий | optional keyapis.rfidregistry.v1.Record.SavingError.Conflict |
Record.SavingError.AlreadyLinked¶
Причины: - Такой ключ уже привязан к другой записи
Record.SavingError.Conflict¶
Причины: - В базе хранится более новая версия записи, значения changed_at отличаются
Record.SavingError.OwnedByAnotherUser¶
Причины: - Запись принадлежит другому пользователю
Record.SavingError.StatusTypeRestricted¶
Причины: - Недопустимый перевод статуса. - Не переданы обязательные поля https://openapi-key.deploy.rtkit.dev/keyapis_rfidregistry_v1/#таблица-обязательности-передачи-полей-в-request
Record.SavingError.UidExist¶
Причины: - Ключ уже существует
Record.Trailer¶
Контрольная сумма
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| sector | Сектор. # Диапазон: 0..15 | int32 | REQUIRED |
| key_a | Ключ А. # Диапазон: 1..256 | string | REQUIRED |
| key_b | Ключ Б. # Диапазон: 1..256 | string | REQUIRED |
| access_mask | Маска доступа. # Диапазон: 1..512 | string | REQUIRED |
RecordFilter¶
Фильтр записей
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| rfid_types | По типам ключей | repeated keyapis.rfidregistry.v1.Record.RfidType | |
| encryption_types | По типам шифрования | repeated keyapis.rfidregistry.v1.Record.EncryptionType | |
| uids | По номерам ключей | repeated string | |
| status_types | По типам статуса | repeated keyapis.rfidregistry.v1.Record.StatusType | |
| in_use_rfid_ids | По номерам привязанных ключей | repeated string | |
| resource_owner_ids | По владельцам | repeated string | |
| order_numbers | По номерам заказа | repeated string | |
| in_use_resource_owner_ids | По владельцам привязанных ключей | repeated string | |
| is_deleted | По удалённым записям. По умолчанию: false | google.protobuf.BoolValue | |
| text | По тексту. Если значение не передано то поиск по нему не производится. # Диапазон: 3..64. # Поиск производится по полям: # - Номер заказа; # - Производитель | google.protobuf.StringValue | |
| start_shipped_at | Дата отгрузки от | google.protobuf.Timestamp | |
| end_shipped_at | Дата отгрузки до | google.protobuf.Timestamp | |
| package_info_boxes | По номеру коробки | repeated int32 | |
| package_info_places | По номеру места в коробке | repeated int32 | |
| identification_method_types | По методу идентификации | repeated keyapis.rfidregistry.v1.Record.IdentificationMethodType |
RecordPaging¶
Пагинация записей
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| order_by_type | Тип значения сортировки. Если значение не передано, то будет взято значение по умолчанию. # По умолчанию: NEW_AT | keyapis.rfidregistry.v1.RecordPaging.OrderByType | |
| direction_type | Тип направления сортировки. # По умолчанию: DESC | keyapis.rfidregistry.v1.RecordPaging.DirectionType | |
| limit | Количество записей на страницу. Если значение 0 (не передано), то будет взято значение по умолчанию. # Диапазон: 0..100. # По умолчанию: 20 | int32 | |
| offset | Сдвиг. # Диапазон: 0..2147483647 | int32 |
ValidationError¶
Ошибки валидации. Эти проверки выполняются до обращения в базу данных
| Поле | Описание | Тип | Признак |
|---|---|---|---|
| path | Путь к полю в формате наименования прото | string | REQUIRED |
| message | Валидационное сообщение | string | REQUIRED |
Record.EncryptionType¶
Справочник типов шифрования ключа.
Тип: byte¶
| Номер | Тип | Название |
|---|---|---|
| 0 | ENCRYPTION_TYPE_UNKNOWN | Значение не указано |
| 1 | SL0 | Без шифрования |
| 2 | SL1 | С шифрованием, копируемый |
| 3 | SL3 | С шифрованием, не копируемый |
Record.IdentificationMethodType¶
Справочник методов идентификации.
Тип: byte¶
| Номер | Тип | Название |
|---|---|---|
| 0 | IDENTIFICATION_METHOD_TYPE_UNKNOWN | Значение не указано |
| 1 | MIFARE | Значение Mifare |
| 2 | BLE | Значение Bluetooth low energy |
| 3 | UHF | Значение Ultra high frequency |
| 4 | EM_MARINE | Значение em-marine |
Record.RfidType¶
Справочник типов ключей.
Тип: byte¶
| Номер | Тип | Название |
|---|---|---|
| 0 | RFID_TYPE_UNKNOWN | Значение не указано |
| 1 | FOB | Брелок |
| 2 | CARD | Карта |
| 3 | BAND | Браслет |
| 4 | STICKER | Стикер |
| 5 | ACTIVE_TAG | Активная метка |
Record.StatusType¶
Справочник типов статусов ключа.
Тип: byte¶
| Номер | Тип | Название |
|---|---|---|
| 0 | STATUS_TYPE_UNKNOWN | Значение не указано |
| 1 | NEW | Новый |
| 2 | SHIPPED | Отгружен |
| 3 | DEFECT | Брак |
| 4 | IN_USE | Использован |
RecordPaging.DirectionType¶
Справочник типов направлений сортировки.
Тип: byte¶
| Номер | Тип | Название |
|---|---|---|
| 0 | DIRECTION_TYPE_UNKNOWN | Значение не указано |
| 1 | DESC | От большего к меньшему |
| 2 | ASC | От меньшего к большему |
RecordPaging.OrderByType¶
Справочник типов значений сортировки.
Тип: byte¶
| Номер | Тип | Название |
|---|---|---|
| 0 | ORDER_BY_TYPE_UNKNOWN | Значение не указано |
| 1 | NEW_AT | По дате перевода в статус new (дате создания) |
| 2 | CHANGED_AT | По времени изменения |
| 3 | ORDER_AT | По времени заказа |
| 4 | ORDER_NUMBER | По номеру заказа |
| 5 | RANK | По рангу для поиска по тексту. Применяется когда передано поле для поиска по тексту. В случае если текстовое поле не передано, применяется значение по умолчанию |
Скалярные типы значений¶
| .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 |