Легке повернення для міжнародних відправлень з України до Європи
Створює відправлення для повернення після доставки початкового замовлення.
ℹ️ Інформація:
Щоб цей запит працював, менеджер з обслуговування клієнта повинен увімкнути налаштування LightReturn для юридичної особи у внутрішній системі Nova Post.
Після активації цього налаштування запит працюватиме через API для нових доставлених відправлень. Повернення може бути створене лише якщо батьківське відправлення має статус Delivered та містить послугу AllowedLightReturn.
Поточний статус відправлення можна знайти у полі "items" → "statusCode" методу Список відправлень.
AllowedLightReturn визначає кількість днів, протягом яких отримувач може ініціювати повернення після доставки. Внутрішньо система перевіряє кілька умов перед тим, як дозволити створення відправлення легкого повернення:
Статус батьківського відправлення має бути одним із:
Issued (9, 10, 11, 106).Система обчислює дозволений період повернення за такою логікою:
finalDate = toTZ(parentShipment.RecipientDateTime) + returnDays + 1 dayде returnDays береться з послуги AllowedLightReturn, а toTZ застосовує відповідний часовий пояс системи (наприклад, регіон ЄС).Повернення може бути створене лише якщо поточний час (nowTZ) є меншим за finalDate.
Система також перевіряє, що для цього ж батьківського відправлення ще не було створено легке повернення.
Якщо всі ці умови виконані, запит на створення повернення приймається; в іншому випадку система повертає помилку валідації з поясненням причини відмови.
Як працює відправлення легкого повернення (Україна → Європа)
Запит повинен містити один обов’язковий параметр —
number(номер батьківського відправлення). Усі інші параметри є опціональними.Підтримуються два сценарії повернення:
Повне повернення — необхідно передати лише параметр
number. Усі дані відправлення успадковуються з батьківського відправлення.Часткове повернення — можна передати додаткові дані відправлення (наприклад,
invoiceтаparcels), щоб повернути лише вибрані товари або оновити габарити посилок.
Якщо опціональні параметри не вказані, їх значення автоматично наслідуються з батьківського відправлення, коли це можливо.
Як місця передачі відправлення для повернення дозволено використовувати лише відділення Nova Post.
Якщо батьківське відправлення було доставлене до APM (поштомата), PUDO або за адресою, найближче доступне відділення Nova Post обирається автоматично.
Клієнт може безпосередньо вказати валідний
divisionIdу запиті.Кур’єрський забір, APM (поштомати) та PUDO не можуть використовуватися як місця передачі відправлення для повернення.
Часткове повернення
Для часткового повернення:
Усі значення в
invoice.items[]повинні повністю відповідати відповідним товарам із батьківського відправлення.Створення нових товарних позицій інвойсу або зміна значень існуючих позицій не допускається.
Клієнт, який ініціює повернення, несе відповідальність за узгодженість значень
amount,costтаactualWeight.Щоб уникнути помилок валідації, рекомендується копіювати дані інвойсу безпосередньо з батьківського відправлення.
Після створення повернення система автоматично генерує накладну повернення. Детальніше про друк етикетки повернення дивіться у Друк транспортних документів. Детальніше про створення батьківського відправлення дивіться у Створення Відправлення.
JWT-токен авторизації зі строком дії 1 годину у заголовку
Номер батьківського відправлення, для якого ініціюється повернення.
Цей параметр є обов’язковим для створення повернення.
SHMD0000000000Ідентифікатор відділення, яке буде обробляти повернення.
🔹Поле підтримується тимчасово для забезпечення зворотної сумісності (legacy).
🔹Це поле є опціональним.
1835903Successfully created Light Return shipment.
Unauthorized request — invalid or missing authentication token.
Parent shipment is missing the AllowedLightReturn parameter.
Parent shipment not found or status not allowed.
Parent shipment not found or status not allowed.
Service unavailable or request timeout.
POST /v.1.0/shipments/light-return HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 27
{
"number": "SHPL1781477107"
}{
"id": 1000000,
"number": "SHPL0000000000",
"dateTime": "2025-01-01T10:00:00.000000Z",
"scheduledDeliveryDate": "2025-01-02T10:00:00.000000Z",
"actualDeliveryDate": "2025-01-01T10:00:01.000000Z",
"closingDate": null,
"status": "ReadyToShip",
"statusDateTime": "2025-01-01T10:00:01.000000Z",
"createdByUser": "00000000-0000-0000-0000-000000000000",
"acceptedByUser": null,
"createdOnDivisionId": null,
"lastModifiedByUser": "00000000-0000-0000-0000-000000000000",
"firstLogisticDivisionId": 100001,
"lastLogisticDivisionId": 100002,
"sender": {
"eoriCode": null,
"companyTin": "",
"companyName": "",
"phone": "380000000000",
"email": "sender@example.com",
"name": "Sender name",
"countryCode": "PL",
"settlementId": 10000,
"address": {
"string": "00-000, Polska, Warszawa, Default Street, 1",
"latitude": 52.2297,
"longitude": 21.0122
},
"addressParts": {
"postCode": "00-000",
"building": "1",
"street": "Default Street",
"city": "Warszawa",
"region": "Mazowieckie",
"flat": "1",
"note": "Default note",
"block": "A"
},
"divisionId": 1000001,
"cityDistrict": "Default District",
"registrationAddress": "Polska, Warszawa, Default Street, 1",
"registrationAddressParts": {
"city": "Warszawa",
"street": "Default Street",
"building": "1",
"postCode": "00-000"
},
"cid": "00000000-0000-0000-0000-000000000001"
},
"recipient": {
"eoriCode": "CZ1234567890",
"companyTin": "CZ0000000000",
"companyName": "Default Recipient Company",
"phone": "420000000000",
"email": "recipient@example.com",
"name": "Default Recipient",
"countryCode": "CZ",
"settlementId": 20000,
"address": {
"string": "100-00, Česko, Praha, Default Street, 10",
"latitude": 50.0755,
"longitude": 14.4378
},
"addressParts": {
"postCode": "100-00",
"building": "10",
"street": "Default Street",
"city": "Praha",
"region": "Praha",
"flat": "2",
"note": "Default address note",
"block": "B"
},
"divisionId": 2000001,
"cityDistrict": "Default District",
"registrationAddress": "Česko, Praha, Default Street, 10",
"registrationAddressParts": {
"city": "Praha",
"street": "Default Street",
"building": "10",
"postCode": "100-00"
},
"cid": "00000000-0000-0000-0000-000000000002"
},
"payerType": "Recipient",
"payerContractNumber": "GNP000000000",
"paymentStatus": "ContractAfterPayment",
"currencyCode": "EUR",
"parcelsAmount": 1,
"note": "",
"lockVersion": 1,
"clientOrder": "",
"gtid": "0000000000000000001",
"firstMileDeliveryPartner": "Nova Post",
"lastMileDeliveryPartner": "Nova Post",
"parcels": [
{
"number": "SHPL0000000000",
"rowNumber": 1,
"untied": false,
"status": "ReadyToShip",
"pricingType": "parcel",
"cargoCategoryId": 1,
"parcelDescription": "Default parcel",
"insuranceCost": 100,
"length": 20,
"width": 15,
"height": 10,
"actualWeight": 500,
"volumetricWeight": 600,
"recipient": null
}
],
"services": [
{
"id": 100001,
"shipmentId": 1000000,
"shipmentParcelRowNumber": 1,
"serviceId": 5000001,
"serviceCode": "LightReturn",
"type": "SystemManual",
"countryCode": "CZ",
"routeId": 100,
"amount": 1,
"contractNumber": "GNPCZ-00000000",
"payerType": "Recipient",
"paymentStatus": "ContractAfterPayment",
"divisionId": 2000001,
"price": 50,
"discount": 0,
"cost": 50,
"user": "00000000-0000-0000-0000-000000000010",
"shipmentLockVersion": 1,
"additionalParameters": {
"divisionId": 2000001,
"addressParts": {
"city": "Praha",
"region": "Praha",
"street": "Default Street",
"postCode": "100-00",
"building": "10",
"flat": "2",
"note": "",
"block": ""
},
"cod": null,
"backwardDelivery": null,
"partner": null,
"sameDay": false,
"longStorageDays": 0,
"recipientPhoneAlternative": null,
"quantity": 1,
"date": "2025-01-01T00:00:00.000000Z",
"from": "Praha",
"to": "Warszawa",
"string": "SHCZ0000000000",
"fullName": "Default Sender",
"phone": "380000000000"
},
"currencyCode": "EUR",
"createdAt": "2025-01-01T10:00:00.000000Z",
"updatedAt": "2025-01-01T10:00:00.000000Z",
"executionAt": null
}
],
"deliveryPartners": [
{
"partnerCode": "NP",
"name": "Nova Post",
"country": "CZ"
}
],
"shipmentAttachments": [
{
"id": 1,
"fileName": "invoice.pdf",
"fileType": "pdf",
"uploadedAt": "2025-01-01T10:01:00.000000Z"
}
],
"createdAt": "2025-01-01T10:00:00.000000Z",
"updatedAt": "2025-01-01T10:05:00.000000Z",
"deletedAt": null,
"invoice": {
"number": "INV00000001",
"date": "2025-01-01T00:00:00.000000Z",
"totalAmount": 150,
"currencyCode": "EUR"
},
"currentRouteId": 100,
"additionalParameters": {
"promoCode": "DEFAULTPROMO",
"sourceApplication": "clientapi",
"preferredDeliveryDate": "2025-01-02T00:00:00.000000Z",
"invoiceInspection": false,
"parentShipment": {
"number": "SHCZ0000000000",
"id": 999999
},
"childShipment": null,
"userMod": "00000000-0000-0000-0000-000000000020",
"cargoAutoReturnDate": null
},
"markingPrinted": true
}Останнє оновлення