Відправлення
Цей API-метод дозволяє отримати список транспортних документів (відправлень), які ви створили. Використовуючи цей метод, ви можете отримати доступ до транспортних документів, що належать вам або вашому обліковому запису. Відповідь міститиме деталі кожного відправлення, такі як ідентифікатор відправлення, номер, отримувач, деталі вантажу та іншу релевантну інформацію.
JWT-токен авторизації зі строком дії 1 годину у заголовку
Пошук відправлень за номером транспортного документа. Може приймати як один номер для пошуку, так і масив номерів.
SHPL6145344878Пошук відправлень за ідентифікаторами транспортних документів.
113622Максимальна кількість елементів на сторінці.
15Example: 1Номер сторінки для повернення.
1Прапорець, що показує, чи включено відправлення до реєстру. Лише для європейських посилок.
trueНомер реєстру, який містить усі відправлення. Лише для європейських посилок.
CRPL0000004855Ідентифікатор відділення, з якого здійснюється відправлення.
12shipments
Поточна сторінка.
Загальна кількість сторінок.
Поточний ліміт об’єктів на сторінці.
Загальна кількість знайдених об’єктів.
Неавторизований доступ
Вказаний ресурс не знайдено
Помилка валідації
Час очікування з’єднання вичерпано
GET /v.1.0/shipments HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
{
"current_page": 1,
"last_page": 438,
"per_page": 1,
"total": 438,
"from": 1,
"to": 1,
"items": [
{
"id": "860344",
"version": 1,
"number": "SHPL9719840000",
"dateTime": "2023-11-01T10:49:39.965000Z",
"scheduledDeliveryDate": "2023-11-05T16:00:00.000000Z",
"closingDate": null,
"createdAt": "2023-11-01T10:49:41.860000Z",
"updatedAt": "2023-11-01T10:49:41.860000Z",
"deletedAt": null,
"userCreate": "6e1ad1af-6595-44ba-ba3c-a748f6c10000",
"status": "ReadyToShip",
"gtid": "2000000000000439545",
"paymentStatus": "NeedPay",
"currencyCode": "PLN",
"parcelsAmount": 1,
"note": "",
"payerType": "Sender",
"payerContractId": null,
"payerContractNumber": null,
"postomatCellReservation": "",
"postomatOrderRef": "",
"firstDayStorage": null,
"cargoAutoReturnDate": null,
"marketplacePartner": "",
"registerNumber": "",
"customerNote": "",
"creationDateNote": "",
"sender": {
"companyId": null,
"companyTin": "",
"companyName": null,
"phone": "48993450000",
"email": "example@mail.pl",
"name": "LastName Name",
"countryCode": "PL",
"settlementId": "22326",
"cityId": null,
"address": "02144, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Sasanki, 12, , 1, ",
"addressParts": {
"city": "Warszawa",
"region": "Warszawa County",
"street": "Sasanki",
"post_code": "02144",
"building": "12",
"flat": "1",
"block": "",
"note": ""
},
"divisionId": "",
"divisionCategory": "",
"archive": false
},
"recipient": {
"companyId": null,
"companyTin": "",
"companyName": null,
"phone": "380991230000",
"email": "example@mail.com",
"name": "LastName Name",
"countryCode": "UA",
"settlementId": "127808",
"cityId": null,
"address": "36023, Україна,Полтавська область,,місто Полтава,Відділення №11 (до 30 кг на одне місце): вул. Героїв АТО, 79,,,",
"addressParts": {
"city": "місто Полтава",
"region": "Полтавська область",
"street": "Відділення №11 (до 30 кг на одне місце): вул. Героїв АТО",
"post_code": "36023",
"building": "79",
"flat": "",
"block": "",
"note": ""
},
"divisionId": "11664",
"divisionCategory": "PostBranch",
"archive": false
},
"parcels": [
{
"number": "SHPL9719840000",
"row_number": 1,
"untied": false,
"cargo_category_id": "2",
"cargo_category_group": "Parcel",
"parcel_description": "Example",
"insurance_cost": 30,
"length": 350,
"width": 200,
"height": 100,
"actual_weight": 2000,
"volumetric_weight": 1750,
"length_check": null,
"width_check": null,
"height_check": null,
"actual_weight_check": null,
"volumetric_weight_check": null
}
],
"services": [
{
"id": 2068473,
"shipment_parcel_row_number": null,
"service_id": "5637144594",
"service_type": "MainService",
"service_name": "Delivery/pickup by courier",
"parcel_number": "",
"payer_type": "Sender",
"amount": 1,
"price": 10,
"discount": 0,
"cost": 10,
"cost_before_check": null,
"payment_status": "NeedPay",
"additional_parameters": {
"cod": null,
"date": null,
"from": null,
"to": null,
"string": null,
"fullName": null,
"phone": null
}
},
{
"id": 2068474,
"shipment_parcel_row_number": 1,
"service_id": "5637144588",
"service_type": "InternationalServices",
"service_name": "Parcel international delivery (small)",
"parcel_number": "1",
"payer_type": "Sender",
"amount": 1,
"price": 45,
"discount": 0,
"cost": 45,
"cost_before_check": null,
"payment_status": "NeedPay",
"additional_parameters": {
"cod": null,
"date": null,
"from": null,
"to": null,
"string": null,
"fullName": null,
"phone": null
}
}
],
"onlineTracking": {
"tracking_status_code": 1,
"tracking_update_date": "2023-11-01T10:49:42.167337Z",
"short_description": "ECN created",
"long_description": "Waiting for your parcel to ship",
"info": "",
"label": "orange"
},
"tracking": [
{
"number": "SHPL9719840000",
"date": "2023-11-01T10:49:41.860000Z",
"division": "",
"settlement": "22326",
"event": "CreateID",
"event_status": "now",
"code": "1",
"division_name": "",
"settlement_name": "Warsaw",
"event_name": "Waybill prepared, waiting for the parcel"
}
],
"totalWeight": 2,
"totalInsuranceCost": 30,
"totalCost": 55,
"invoice": {
"customerNumber": "INV-001",
"customerCreatedAt": "2023-11-01T10:00:00.000000Z",
"type": "Invoice",
"incoterm": "DAP",
"exportReason": "Selling",
"cost": 30,
"currency": "EUR",
"payerFeesCustoms": "Recipient",
"items": [
{
"id": "1",
"hsCode": "84701000",
"name": "Calculator",
"nameEng": "Calculator",
"material": "plastic",
"materialEng": "plastic",
"madeInCountryCode": "PL",
"producerAndModel": "Casio JR15",
"actualWeight": 2000,
"measurementCode": "pieces",
"amount": 1,
"cost": 30
}
]
}
}
]
}Цей API-метод дозволяє оновити створений раніше транспортний документ шляхом передачі ідентифікатора документа та повного набору оновлених даних. Під час виконання запиту попередня версія документа замінюється новими даними із запиту. Відповідь зазвичай містить інформацію про успішність операції оновлення, а також може містити деталі зміненого документа.
Обмеження оновлення:
Дані відправлення можуть бути оновлені лише тоді, коли відправлення перебуває у статусі
ReadyToShip.Оновлення дозволені лише якщо ярлик (лейбл) відправлення ще не був надрукований.
Якщо відправлення не перебуває у статусі
ReadyToShipабо ярлик уже був надрукований, запит на оновлення буде відхилено з помилкою валідації.
JWT-токен авторизації зі строком дії 1 годину у заголовку
Ідентифікатор транспортного документа.
113677Визначає поточний статус транспортного документа, відображаючи його рух у межах життєвого циклу відправлення. Статуси описують ключові етапи:
Draft: Документ перебуває на етапі створення та ще не завершений.Accepted: Документ перевірено та прийнято, готовий до наступних кроків.Issued: Документ сформовано та підготовлено до відправлення.ReadyToShip: Вказує, що відправлення готове до транспортування після створення експрес-накладної. Лише це значення може бути вказане при створенні відправлення.Deleted: Документ видалено із системи.Returned: Відправлення повернено відправнику.Utilized: Вказує, що фізичний вантаж, пов’язаний із транспортним документом, утилізовано або знищено, а документ закрито.
Представляє всі можливі ідентифікатори замовлення, пов’язані з відправленням. Ці ідентифікатори встановлюються клієнтом для внутрішнього обліку та є важливими для відстеження відправлення протягом усього його маршруту. Усі введені значення можуть використовуватись у системі відстеження відправлення.
Додаткова інформація або спеціальні інструкції щодо замовлення. Може включати інструкції з доставки, особливі вимоги до обробки або інші важливі деталі, що полегшують обробку та виконання відправлення.
Визначає тип тарифу, який буде застосовано до відправлення під час створення або оновлення.
standard: Стандартний тариф на міжнародну доставку.economy: Економний тариф на міжнародну доставку.express: Експрес-тариф на міжнародну доставку.
Якщо поле не передано, тип тарифу визначається автоматично відповідно до поточних бізнес-правил, і поведінка оновлення відправлення залишається без змін.
🔹Це поле є необов’язковим.
Визначає, хто відповідає за оплату послуг доставки. Тип платника визначає сторону, яка несе витрати:
Sender: Відправник оплачує доставку.Recipient: Отримувач оплачує доставку.ThirdPerson: Третя сторона (не відправник і не отримувач) оплачує послуги доставки. У разі виборуThirdPersonполеpayerContractNumberповинно містити номер договору платника. Детальніше див. у статті Оплата послуг доставки через API Nova Post.
Номер договору платника. Обов’язковий, якщо payerType = ThirdPerson. Для клієнтів з України також допускається використання коду ЄДРПОУ замість номера договору. Поле також обов’язкове, якщо платником є відправник при безготівковій оплаті. Якщо значення не надано, за замовчуванням застосовується готівковий спосіб оплати. Коректність даних є критично важливою для обробки платежу. Більш детальну інформацію можна знайти у статті Оплата послуг доставки через API Nova Post.
Відправлення успішно оновлено. Ця відповідь підтверджує, що дані зазначеного транспортного документа були змінені відповідно до переданих вхідних параметрів.
Унікальний ідентифікатор, призначений кожному відправленню, який використовується для внутрішніх операцій, таких як внесення змін, пошук у системі та видалення відправлень. Поле id слугує основним ідентифікатором для адміністративних і логістичних процесів у системі доставки, забезпечуючи точний доступ до записів про відправлення та керування ними.
Номер транспортного документа, який надається клієнтам для відстеження відправлення та доступу до друкованих форм. Також використовується для пошуку відправлення в системі, забезпечуючи зручний для клієнта спосіб контролю його статусу. Хоча поле number використовується переважно для зовнішнього відстеження та документації, у певних системних операціях воно також може використовуватися для внутрішньої ідентифікації відправлення аналогічно до поля id.
^[A-Z]{4}\d{10}$Орієнтовна дата доставки, розрахована на основі маршруту та рівня сервісу. Може змінюватися залежно від логістичних та зовнішніх факторів.
Поточний статус відправлення. Після створення початково встановлюється значення ReadyToShip, що означає готовність відправлення до відправки.
Загальна вартість розрахованих послуг доставки, що визначається на основі розміру, ваги, пункту призначення та вибраних сервісів.
32.5Загальна кількість місць у відправленні. Це значення використовується для логістичного планування та відстеження.
Дата й час створення запису про відправлення в системі.
Дата й час останнього оновлення запису про відправлення. Використовується для відстеження змін і оновлень, внесених до даних відправлення.
Дата й час скасування або видалення відправлення із системи. Якщо відправлення не було скасовано, це поле містить значення null.
Неавторизований доступ
Вказаний ресурс не знайдено
Помилка валідації
Час очікування з’єднання вичерпано
PUT /v.1.0/shipments/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1537
{
"status": "ReadyToShip",
"clientOrder": "string",
"note": "string",
"payerType": "Sender",
"payerContractNumber": null,
"invoice": {
"incoterm": "DAP",
"exportReason": "Selling",
"cost": 20,
"currency": "UAH",
"payerFeesCustoms": "Sender",
"items": [
{
"customerId": 25227,
"name": "Обладнання та електрика/Складське обладнання: Калькулятори",
"nameEng": "Hardware and Electrical/Storage Equipment: Calculators",
"measurementCode": "pieces",
"hsCode": "84701000",
"producerAndModel": "Casio JR15",
"amount": 1,
"cost": 20
}
]
},
"parcels": [
{
"cargoCategory": "parcel",
"parcelDescription": "Clothes",
"insuranceCost": 20,
"rowNumber": 1,
"untied": false,
"width": 200,
"length": 350,
"height": 100,
"actualWeight": 2000
},
{
"cargoCategory": "parcel",
"parcelDescription": "Clothes",
"insuranceCost": 15,
"rowNumber": 2,
"untied": false,
"width": 215,
"length": 345,
"height": 110,
"actualWeight": 2000
},
{
"cargoCategory": "parcel",
"parcelDescription": "Clothes",
"insuranceCost": 20,
"rowNumber": 3,
"untied": true,
"width": 190,
"length": 340,
"height": 120,
"actualWeight": 2000
}
],
"sender": {
"companyTin": "",
"companyName": "",
"phone": 48993453453,
"email": "example@mail.pl",
"name": "Surname Name",
"ioss": null,
"countryCode": "LT",
"divisionNumber": null,
"addressParts": {
"city": "Vilnius",
"region": "Vilniaus apskritis",
"street": "Žalgirio g",
"postCode": "12546",
"building": "92",
"flat": "",
"block": "",
"note": ""
}
},
"recipient": {
"companyTin": "",
"companyName": "",
"phone": 380001234567,
"email": "example@mail.com",
"name": "Surname Name",
"countryCode": "UA",
"divisionNumber": "32521/1",
"addressParts": {}
}
}{
"id": 113677,
"number": "SHLT4009860665",
"scheduledDeliveryDate": "2023-04-14T09:00:00.000000Z",
"status": "ReadyToShip",
"cost": 31,
"parcelsAmount": 1,
"createdAt": "2023-04-11T10:42:05.543380Z",
"updatedAt": "2023-04-11T10:42:05.543380Z",
"deletedAt": null
}Цей метод дозволяє видалити транспортний документ на підставі його унікального ідентифікатора (ID). Для успішного видалення документа із системи запит повинен містити його ID. Відповідь міститиме інформацію про успішність виконання операції.
Особливості реалізації для різних регіонів:
1. Європа:
Метод насамперед очікує унікальний ID (Ref ID) документа.
Додатково підтримується видалення за номером відправлення (наприклад,
SHPL0123456789).
2. Україна:
Видалення підтримується лише за Ref ID (унікальним ідентифікатором документа).
Видалення за номером відправлення (наприклад, номером експрес-накладної) не підтримується.
JWT-токен авторизації зі строком дії 1 годину у заголовку
ID транспортного документа (відправлення).
{"summary":"International shipment","value":456931}Відправлення
Дата й час видалення документа.
Неавторизований доступ
Вказаний ресурс не знайдено
Помилка валідації
Час очікування з’єднання вичерпано
DELETE /v.1.0/shipments/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*
{ "deletedAt": "2023-04-18T11:47:19.290462Z" } Останнє оновлення