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

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

  • Сервис - совокупность аппаратно-программных средств на сайте 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: В запросе должны присутствовать следующие заголовки (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 адреса в списке заблокированных сервис удалит запись.

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

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

Блокирование IP адреса производится при условии попыток подбора Пароля документа или иных действиях, которые можно расценить как попытку несанкционированного доступа к данным. Для разблокировки 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

Наверх