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

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

  • Сервис - совокупность аппаратно-программных средств на сайте prov.by для предоставления возможности обмена информацией между клиентами сервиса.
  • Клиенты сервиса - юридические лица или индивидуальные предприниматели, прошедшие регистрацию на главной странице сайта prov.by и ознакомившиеся с договором публичной оферты.
  • Номер документа - Уникальный номер информации, которая загружается в сервис.
  • Формат документа - Формат который соответствует типу документа: ТТН-1, ТН-2, счет на оплату, акт выполненных работ.
  • Пароль документа - Пятизначный символьный пароль на доступ к информации, атоматически генерируемый сервисом.
  • Персональный ключ клиента - Уникальный набор символов, который автоматически генерируется сервисом при регистрации клиента.
  • Загрузка данных - POST запрос, выполненный по https протоколу.
  • Выгрузка данных - GET запрос, выполненный по https протоколу.
  • Удаление данных - DELETE запрос, выполненный по https протоколу.
  • Заблокированный IP адрес - IP адрес, который сервис автоматически заблокировал для использования сервиса.

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

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

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

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

DocType:

Nuget package

В запросе должны присутствовать следующие заголовки (headers):
  • Key (обязательный) - Персональный ключ клиента, полученный при регистрации
  • Number (необязательный) - Номер документа, загружаемого в сервис.
  • DocPass (необязательный) - Пароль документа (если нужно обновить существующий документ).
  • ContentType (необязательный) - application/json. Для xml этот параметр обязателен.
  • Accept (необязательный) - application/json. Для xml этот параметр обязателен.

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

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

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

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

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

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

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

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

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

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

ТТН json


{
"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
}

Акт xml

Наверх