Техническая документация

Понятия и определения

Работа с сервисом

В общем случае настройка работы с сервисом заключается в добавлении двух реквезитов к накладной: НомерПровБай, ПарольПровБай для выгрузки документов в сервис. А также реквизит КодПровБай в справочнике продукции для однозначной идентификации продукции при загрузке из сервиса. Выгрузка и загрузка производится в формате json или xml.

Загрузка информации в сервис

Для осуществления загрузки данных в сервис prov.by необходимо отправить POST запрос на адрес https://api.prov.by/AddDoc/{DocType}.

DocType: В запросе должны присутствовать следующие заголовки (headers):

Тело запроса должно содержать данные, которые будут загружены в сервис, в формате типа документа (ТН, ТТН и т.д.).
При отправке в формате xml используются следующие схемы: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"

При получении запроса на загрузку информации, сервис проверяет валидность Персонального ключа клиента, отсутствие IP адреса, с которого пришел запрос, в базе заблокированных адресов и разрешение на использование сервиса клиентом. Если проверка пройдена успешно, то сервис шифрует тело запроса сгенерированным паролем и сохраняет информацию в своей базе данных. При поступлении запроса на добавление с указанием заголовков Number и DocPass будет осуществлено обновление данных. Если документ не будет найден, то будет создан новый документ. При успешном сохранении данных, в ответ на POST запрос, сервис возвращает JSON строку, содержащую сгенерированный номер документа и пароль для доступа к нему, а также MD5 hash последовательность тела запроса.

Выгрузка информации из сервиса

Для осуществления выгрузки информации из сервиса prov.by необходимо отправить GET запрос на адрес https://api.prov.by/{Number}. Где Number - уникальный номер документа присвоенный сервисом при загрузке данных. В запросе должны присутствовать следующие заголовки (headers): В случае валидной проверки Пароля документа, Персонального ключа клиента, а также при отсутсnвии IP адреса в списке заблокированных, сервис вернет расшифрованную строку с данными.

Удаление информации из сервиса

Для осуществления удаления информации из сервиса prov.by необходимо отправить DELETE запрос на адрес https://api.prov.by/{Number}. Где Number - уникальный номер документа присвоенный сервисом при загрузке данных. В запросе должны присутствовать следующие заголовки (headers):

В случае валидной проверки Пароля документа, Персонального ключа клиента, а также при отсутсnвии IP адреса в списке заблокированных сервис удалит запись.

Проект prov.by является open source проектом.

Блокирование IP адреса

Блокирование IP адреса производится при условии попыток подбора Пароля документа или иных действиях, которые можно расценить как попытку несанкционированного доступа к данным. Для разблокировки IP адреса отправьте сообщение посредством формы обратной связи на странице "Контакты", с обязательным указанием заблокированного IP адреса.

Примеры документов

ТТН


{
"Number": "0143605",
"Date": "2019-12-31T09:37:33",
"Seller": {
"Name": "ООО \"Поставщик\"",
"RegNumber": "111111111 ",
"Addres": "220000 Минск",
"Phone": "+375",
"RegCountry3Code": "BLR",
"WebSite": "",
"Email": ""
},
"Buyer": {
"Name": "ООО \"Покупатель\"",
"RegNumber": "222222222",
"Addres": "220000 Минск",
"Phone": "",
"RegCountry3Code": "BLR"
},
"VehicleOwner": null,
"ShipingCustomenr": {
"Name": "ООО \"Заказчик транспорта\"",
"RegNumber": "333333333",
"Addres": "220000",
"Phone": "",
"RegCountry3Code": "BLR"
},
"CargoSender": null,
"CargoRecipient": null,
"Contract": {
"Number": "17-12",
"Date": "2019-12-17T00:00:00"
},
"Currency": {
"StrCode": "BYN",
"DigitCode": 933,
"Name": "Белорусский рубль"
},
"Coment": "",
"ShipAllow": "Иванова Ольга Александровна",
"ShipMaker": "кладовщиу, Петров Иван Васильевич",
"CargoTaker": "Алешин С.А.",
"CargoTook": "водитель, Алешин С.А.",
"Vehicle": "ГАЗ 3302",
"VehicleDriver": "Алешин С.А.",
"VehicleAddon": "",
"VehicleSheet": "25 от 31.12.2019",
"LoadPlace": "Минск ул. Загрузочная, 1",
"UnloadPlace": "Минск, ул. Разгрузочная, 1",
"AuthLetter": {
"Number": "384",
"Date": "2019-12-30T00:00:00",
"ExpDate": null,
"Fio": "водителю Алешину С.А.",
"Doc": "Паспорт",
"Letter": ""
},
"Table": [
{
"RowNumber": 1,
"Product": {
"Name": "Товар 1",
"IsService": false,
"Unit": {
"Name": "Штука",
"OKEIcode": 796,
"CIcode": ""
},
"Codes": [
{
"Name": "Code1C",
"Value": "00-00000490"
},
{
"Name": "EAN13",
"Value": ""
},
{
"Name": "EAN8",
"Value": ""
},
{
"Name": "TNVD",
"Value": ""
},
{
"Name": "OKED",
"Value": ""
}
]
},
"Unit": {
"Name": "Штука",
"OKEIcode": 796,
"CIcode": ""
},
"Quantity": 1,
"Price": 128,
"VAT": 20,
"VATAmount": 25.6,
"Amount": 153.6,
"IsTare": false,
"InPlaceQty": 1,
"Brutto": 25,
"Coment": null,
"Contract": null
}
],
"PackList": null
}