Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Легке повернення для міжнародних відправлень у межах Європи

Створення відправлення для легкого повернення

post
/shipments/light-return

Створює відправлення для повернення після доставки початкового замовлення. Цей метод дозволяє клієнтам створити відправлення повернення після доставки — незалежно від того, хто здійснював останню милю (Нова Пошта або партнер).

Підтримуваний напрямок відправлення:

  • Європа → Європа (включно з Молдова → Румунія)

ℹ️ Інформація: Щоб цей запит працював, менеджер з обслуговування клієнта повинен увімкнути налаштування 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 (номер батьківського відправлення). Усі інші параметри є опціональними.

  • Якщо опціональні параметри не вказані, їх значення автоматично наслідуються з батьківського відправлення, коли це можливо.

  • Клієнт може передати відправлення повернення у відділенні Nova Post або скористатися кур’єрським забором.

  • Якщо батьківське відправлення було доставлене до поштомата, PUDO або за адресою, найближче доступне відділення Nova Post обирається автоматично.

  • Клієнт може безпосередньо вказати валідне відділення у запиті.

  • Поштомати та PUDO не можуть використовуватися як місця передачі відправлення для повернення.

Після створення повернення система автоматично генерує накладну повернення. Детальніше про друк етикетки повернення дивіться у Друк транспортних документів. Детальніше про створення батьківського відправлення дивіться у Створення Відправлення.

Authorizations
AuthorizationstringRequired

JWT-токен авторизації зі строком дії 1 годину у заголовку

Body
numberstringRequired

Номер батьківського відправлення, для якого ініціюється повернення.

Цей параметр є обов’язковим для створення повернення.

Example: SHMD0000000000
divisionIdstringOptional

Ідентифікатор відділення, яке буде обробляти повернення.

🔹Поле підтримується тимчасово для забезпечення зворотної сумісності (legacy).

🔹Це поле є опціональним.

Example: 1835903
payerTypestring · enumOptional

Визначає, хто сплачує за відправлення для повернення.

🔹Якщо не вказано, за замовчуванням використовується значення Recipient.

🔹Підтримується лише для відправлень легкого повернення за напрямком Європа → Європа.

Possible values:
payerContractNumberstringOptional

Номер договору платника.

Правила:

  • Обов’язковий, якщо payerType = ThirdPerson.
  • Необов’язковий для Sender (не підтримується для MD → RO).
  • Необов’язковий для Recipient, якщо батьківське відправлення було оформлене з оплатою за договором.
Responses
200

Successfully created Light Return shipment.

application/json
objectOptional
post/shipments/light-return
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: 67

{
  "number": "SHMD0000000000",
  "sender": {
    "senderPhone": "490000000000"
  }
}
{
  "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
}
ПопередняПовернення
НаступнаЛегке повернення для міжнародних відправлень з України до Європи

Останнє оновлення