Документация PBF Checker API Подать заявку

Содержание

Вступление

API интерфейс используется для того, чтобы интегрировать возможности сервиса PBF Checker API в личный проект клиента. API предназначен для разработчиков и сопровождается детальной документацией.

Описание

PBF Checker API работает по протоколу HTTP и представляет собой набор методов, с помощью которых совершаются запросы и возвращаются ответы для каждой операции. Все ответы приходят в виде JSON структур.

Основной URL

Все ссылки на запросы к API в данной документации включают обязательный основной URL:

https://api.pbf.Qoldau.kz/swagger/index.html

Авторизация

Процесс авторизации возможен при наличии персонального ключа (токена), которым в дальнейшем должен быть подписан каждый запрос к API.
Обратите внимание, что полученный ключ действителен в течение 24 часов. По истечении срока действия ключа (24 часа) необходимо отправить повторный запрос на получение ключа.
Токен можно получить только при наличии уникального идентификатора доступа(access ID).

Чтобы получить уникальный идентификатор доступа, нужно подать заявку на получение доступа к API по ссылке:
Подать заявку

Для получения токена отправляется POST запрос по ссылке:

https://api.pbf.Qoldau.kz/api/Authentication/GetAccessToken
{ "accessId": "string" }

Вместо “string” ставим Access ID в формате GUID полученный после подачи заявки.

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

{ "token": "eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwidHlwIjoiSldUIn0.GjtFMKgXBY5JWLR3MCXC0a1iHH4DNxihC2jzTYYOKyAdZD-Qxl96iQ.R8dB9M-XV7s3ICtmVWXRmw.x6K2hOM1iUGcoNXQMOK_1lnsjat_JWyAI96B4Jb8_Y5qZrAMTW_hysYIcYtQxjLYh9ujZ2FFIEE168PGj144yPjQzZ7cBYElY6VZOe9WWSZZBX64Vix4Vy6SDjzLAGWDotSuEsW9szb3hokNrwtAx35LF8A4zG7beZsyNch5qJubpErt_UgYI6xER_8eWJcVMX2oLT8SMjvWMRMaBfx93FqhI-QW9mdAaH4AQEzYD3Exb9IXz4ycgLKLEZxu6HCGHQ_0kFcwfSSvJpIdoT_izDjz7CiNdozoRZYbKVdO1sOxd6uYLKS6IfKZqJrsk6aLd8LttHEhF3_DKxFgJkSEB7_Kps7KTN1wZ7Y25cEn0GVyCd7u0pW90zDJlq-qaNmOLbxYuaEEsCpeYyyqThU0jwKjrs067cmWVY1QnQVDRJA28RBT2dTorU9NJ6fuuLWpTyFpT4e370KzzcRz4b6hXR_VjbBV7MYW6XVv9YARBdzjYTX5ANrL2DylnwUsLTrkKIpJnglmLH_b6OaIakj0o1ndYa8Y55XWxzYQuE-Q6Qe-DZ5PttimHpeemomquoiG.p4jerY8f9S1wIfmL3t3tKg", "role": null, "login": null, "displayName": null, "id": null }

Затем авторизируемся с помощью токена

Пример авторизации:

Authorization: Bearer eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwidHlwIjoiSldUIn0.GjtFMKgXBY5JWLR3MCXC0a1iHH4DNxihC2jzTYYOKyAdZD-Qxl96iQ.R8dB9M-XV7s3ICtmVWXRmw.x6K2hOM1iUGcoNXQMOK_1lnsjat_JWyAI96B4Jb8_Y5qZrAMTW_hysYIcYtQxjLYh9ujZ2FFIEE168PGj144yPjQzZ7cBYElY6VZOe9WWSZZBX64Vix4Vy6SDjzLAGWDotSuEsW9szb3hokNrwtAx35LF8A4zG7beZsyNch5qJubpErt_UgYI6xER_8eWJcVMX2oLT8SMjvWMRMaBfx93FqhI-QW9mdAaH4AQEzYD3Exb9IXz4ycgLKLEZxu6HCGHQ_0kFcwfSSvJpIdoT_izDjz7CiNdozoRZYbKVdO1sOxd6uYLKS6IfKZqJrsk6aLd8LttHEhF3_DKxFgJkSEB7_Kps7KTN1wZ7Y25cEn0GVyCd7u0pW90zDJlq-qaNmOLbxYuaEEsCpeYyyqThU0jwKjrs067cmWVY1QnQVDRJA28RBT2dTorU9NJ6fuuLWpTyFpT4e370KzzcRz4b6hXR_VjbBV7MYW6XVv9YARBdzjYTX5ANrL2DylnwUsLTrkKIpJnglmLH_b6OaIakj0o1ndYa8Y55XWxzYQuE-Q6Qe-DZ5PttimHpeemomquoiG.p4jerY8f9S1wIfmL3t3tKg

Проверка Учетно-контрольных марок

После авторизации становится доступна функция проверки учетно-контрольных марок. Проверка производится путем отправления POST запроса по ссылке:

https://api.pbf.Qoldau.kz/api/Checker/CheckCode

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

{
"usid": "string",
"series": "string",
"number": "string",
"udid": "string",
"checkerData": {
    "prescriptionId": "string",
    "checkedOrgBin": "string",
    "checkedOrgName": "string",
    "checkedAddress": "string"
},
"location": [0,0]
}

Описание полей:

Название Описание Формат
usid Уникальный идентификатор УКМ, содержащий данные закодированные в PDF 417 или DataMatrix. (Uniqued Stamp IDentificator) DataMatrix(новые марки): AA000000000 XXXXXXX PDF-417(старые марки): U01f930a16f54bd4464bd3913fe30ef2971000039edd23a
series Серия марки Data matrix(латиница): AA PDF-417(киррилица): ВГ
number Номер марки 9 цифр: 000000001
udid Уникальный идентификатор устройства (Uniqued Device Identificator) nbf9673t8688t868t9e3308t6btbdd82ecpc8cbd
udid Уникальный идентификатор устройства (Uniqued Device Identificator) nbf9673t8688t868t9e3308t6btbdd82ecpc8cbd
checkerData Поля не обязательно к заполнению -
location Место проверки, по геолокации 54.97158, 73.38318

Пример запроса при сканировании УКМ с кодом DataMatrix: 

{
"usid": "AA000000001 XXXXXXX", - пример
"series": "",
"number": "",
"udid": "", - указывается уникальный номер устройства
"checkerData": {
    "prescriptionId": "string",
    "checkedOrgBin": "string",
    "checkedOrgName": "string",
    "checkedAddress": "string"
},
"location": [
    0 - указывается место проверки УКМ, по геолокации
]
}

Пример запроса при сканировании УКМ с кодом PDF-417: 

{
"usid": " U01f930a16f54bd4464bd3913fe30ef2971000039edd23a", - пример
"series": "",
"number": "",
"udid": "", - указывается уникальный номер устройства
"checkerData": {
    "prescriptionId": "string",
    "checkedOrgBin": "string",
    "checkedOrgName": "string",
    "checkedAddress": "string"
},
"location": [
    0 - указывается место проверки УКМ, по геолокации
]
}

Пример запроса при проверке по серии и номеру УКМ c DataMatrix: 

{
"usid": "",
"series": "АА", - пример
"number": "000000001", - пример
"udid": "", - указывается уникальный номер устройства
"checkerData": {
    "prescriptionId": "string",
    "checkedOrgBin": "string",
    "checkedOrgName": "string",
    "checkedAddress": "string"
},
"location": [
    0 - указывается место проверки УКМ, по геолокации
]
}

Пример запроса при проверке по серии и номеру УКМ c PDF-417: 

{
"usid": "",
"series": "ВБ", - пример
"number": "000000001", - пример
"udid": "", - указывается уникальный номер устройства
"checkerData": {
    "prescriptionId": "string",
    "checkedOrgBin": "string",
    "checkedOrgName": "string",
    "checkedAddress": "string"
},
"location": [
    0 - указывается место проверки УКМ, по геолокации
]
}

Пример ответа по вышеотправленным запросам: 

{
"items": [
    {
    "isVerified": false,
    "series": "AA",
    "number": "000000001",
    "regionCode": null,
    "regionName": null,
    "organization": "Кокшетауские минеральные воды",
    "productGroup": "Водка",
    "productName": "Водка \"Синяя гора легкая\"",
    "productId": 195215,
    "volume": 0.45,
    "stampProducedDateStart": null,
    "stampProducedDate": "2019-08-31",
    "stampReceivedDate": "2019-08-09",
    "stampReturnDate": null,
    "degree": 38,
    "status": "Получен производителем или импортером"
    }
],
"errors": null
}

Описание полей полученного ответа:

Название Описание
isVerified является проверочным полем для запросов. При направлении запроса при сканировании DataMatrix самой API проводится проверка на наличие шифрованного кода. При его наличии показывается – true. В случае других запросов по серии и марке, сканировании PDF-417 будет показываться – false. Проверочные для остальных видом запросов будут добавлены позднее
series Серия марки
number Номер марки
regionCode поле не обязательно
organization организация получившая марку
productGroup информация о виде алкогольной продукции
productName информация о наименовании алкогольной продукции
productId идентификационный номер продукта в базе
volume информация о объеме алкогольной продукции
stampProducedDateStart период розлива алкогольной продукции
stampProducedDate период розлива алкогольной продукции
stampReceivedDate дата получения марки
stampReturnDate дата возврата марки
degree информация о крепости алкогольной продукции
status статус выданной накладной. В поле статус отображаются два вида статуса: Номер отсутствует в БД и Получен производителем или импортером.