Page 3

зміни по тасці - https://novaposhta.atlassian.net/browse/APIGW-3450

BasicTracking

get

/shipments/tracking/history

This API method enables you to retrieve the status of a shipment by providing the transportation document number. By specifying the document number in the request, you can obtain information about the current location or status of the shipment, providing clients with real-time updates on the progress of their cargo. 🔸This method works only with the transportation document number (shipment number) and does not support searching by client order numbers or any external identifiers. 🔸BasicTracking provides a simplified tracking response focused on the shipment’s status history and, optionally, its related shipment numbers. Unlike FullTracking, it does not return detailed routing information, parcel-level data, undelivery reasons, return/redirect records, or extended metadata. This method is intended for quick, lightweight status checks.

Authorizations

AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Query parameters

numbers[]stringOptional

Shipment`s numbers. Can accept either a single number or an array of numbers.

Example: SHPL1234567890

extendedstringOptional

Parameter responsible for including in the response an array of objects listing all related shipments.

To receive this data in the response, set the value to 1.

Default: 0Example: 1

Responses

200

Tracking response schema

application/json

401

Unauthorized

application/json

404

The specified resource was not found

application/json

422

Validation error

application/json

503

Connection time-out

application/json

get/shipments/tracking/history

GET /v.1.0/shipments/tracking/history HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "items": [
    {
      "id": "111003",
      "number": "SHPL1234567890",
      "history_tracking": [
        {
          "code": "1",
          "code_name": "Zamówienie zostało utworzone. Poczekaj na wysłanie przesyłki",
          "country_code": "PL",
          "settlement": "Głogów Małopolski",
          "date": "2023-03-10T05:57:09.626014Z"
        }
      ],
      "related_numbers": [
        "SHPL2345678901"
      ]
    }
  ]
}

FullTracking

get

/shipments/tracking

This API method enables you to retrieve the status of a shipment by providing the transportation document number. By specifying the document number in the request, you can obtain information about the current location or status of the shipment, providing clients with real-time updates on the progress of their cargo.

By default, the response contains the following data blocks:

• Current status of the shipment;
• Tracking history;
• Actual tracking history;
• Description of the shipment;
• Extended information about related shipments.

If necessary, additional blocks can be included in the response by passing the appropriate parameters:

• withUndeliveryReason = true - adds an array of objects with information about the reasons for non-delivery of shipments.
• withCreatedOnTheBasis = true - adds an array of objects with information about returns or forwarding associated with the shipment.

🔸FullTracking provides a comprehensive tracking response containing detailed shipment status data, full movement history, parcel descriptions, undelivery reasons, and information about related or derivative shipments. Unlike BasicTracking, it offers extended operational details and is designed for cases requiring full visibility into the shipment’s logistics lifecycle.

Authorizations

AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Query parameters

numbers[]stringOptional

Shipment numbers. Can accept either a single number or an array of numbers.

Example: SHPL1234567890

ids[]integer · int32Optional

Search shipments by transportation document ids. Accepts either a single search id or an array of ids to conduct the search.

Example: 113622

withUndeliveryReasonbooleanOptional

A parameter that controls the inclusion of an array of objects containing information about non-delivery reasons in the response. To receive this data in the response, set the value to true.

Default: falseExample: true

withCreatedOnTheBasisbooleanOptional

Parameter responsible for including in the response an array of objects containing information about related shipments (types: Redirecting, Return, Utilization, Redelivery). To receive this data in the response, set the value to true.

Default: falseExample: true

countryCodestringOptional

Two-letter sender country code according to the ISO 3166-1 Alpha-2 standard. If this parameter is specified, Tracking history and Actual tracking history will be shown only for the specified country. Pattern: ^[A-Z]{2}$

Example: DE

externalstringOptional

Parameter responsible for including in the response an array of objects listing all related shipments, as well as an array containing extended information about those shipments — including the shipment owner’s name, shipment number, and shipment creation date. To receive this data in the response, set the value to 1.

Default: 0Example: 1

trackingByBarcodestringOptional

The system filters aggregated data and returns information only for the specified parcel. This allows tracking the delivery route of a specific parcel within a multi-parcel shipment.

Example: SHRO1452163509

withAllParcelsbooleanOptional

The system aggregates events from all parcel into a single array, grouped by parcel number. This allows tracking the delivery route of each parcel within a multi-parcel shipment.

Default: falseExample: true

Responses

200

Tracking response schema

application/json

alternativeNumbersstring[]Optional

An array of objects containing a list of related shipments.

401

Unauthorized

application/json

404

The specified resource was not found

application/json

422

Validation error

application/json

503

Connection time-out

application/json

get/shipments/tracking

GET /v.1.0/shipments/tracking HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "items": [
    {
      "currentStatus": {
        "number": "SHPL2326420334",
        "createdDate": "2025-07-01T09:18:44.000000Z",
        "scheduledDate": "2025-07-01T15:00:00.000000Z",
        "scheduledDateOriginal": null,
        "adjustedDate": null,
        "closingDate": "2025-07-01T09:20:04.000000Z",
        "statusCode": 9,
        "status": "Delivered 01.07",
        "statusDate": "2025-07-01T09:20:11.299982Z",
        "deliveryType": "Division",
        "deliveryCountry": "DE"
      },
      "detailsTracking": [
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:18:46.000000Z",
          "event": "ArrivalSenderDoors",
          "eventStatus": "passed",
          "countryCode": "NL",
          "code": "5",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "The courier picked up the parcel",
          "postCode1": "1011",
          "postCode2": "1019"
        },
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:18:50.000000Z",
          "event": "Arrival",
          "eventStatus": "passed",
          "countryCode": "NL",
          "code": "5",
          "postCode": "1011AB",
          "divisionName": null,
          "settlementName": "Amsterdam",
          "eventName": "Arrived at branch 2",
          "postCode1": "1011",
          "postCode2": "1019"
        },
        {
          "number": "103-00160415",
          "date": "2025-07-01T09:19:37.000000Z",
          "event": "OrderRedirecting",
          "eventStatus": "passed",
          "code": "104",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "Delivery location has been changed",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": null
        },
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:20:04.000000Z",
          "event": "ReceivedWarehouse",
          "eventStatus": "now",
          "code": "9",
          "postCode": "1011AB",
          "divisionName": "branch 5",
          "settlementName": "Amsterdam",
          "eventName": "Delivered at branch 5",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": "NL"
        }
      ],
      "historyOnlineTracking": [
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:18:46.000000Z",
          "event": "ArrivalSenderDoors",
          "eventStatus": "passed",
          "countryCode": "NL",
          "code": "5",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "The courier picked up the parcel",
          "postCode1": "1011",
          "postCode2": "1019"
        },
        {
          "number": "103-00160415",
          "date": "2025-07-01T09:19:37.000000Z",
          "event": "OrderRedirecting",
          "eventStatus": "passed",
          "code": "104",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "Delivery location has been changed",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": null
        },
        {
          "number": "51499647910100",
          "date": "2025-07-01T09:20:04.000000Z",
          "event": "ReceivedWarehouse",
          "eventStatus": "now",
          "code": "9",
          "postCode": "1011AB",
          "divisionName": "branch 5",
          "settlementName": "Amsterdam",
          "eventName": "Delivered at branch 5",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": "NL"
        }
      ],
      "parcelsDetailsTracking": null,
      "parcelsHistoryOnlineTracking": null,
      "parcels": [
        {
          "number": "SHPL2326420334",
          "rowNumber": null,
          "untied": false,
          "cargoCategoryGroup": "parcel",
          "cargoCategoryId": "",
          "categoryCargoName": "Parcel",
          "parcelDescription": null,
          "insuranceCost": 25,
          "insuranceCostCurrencyCode": "EUR",
          "length": 25,
          "width": 15,
          "height": 18,
          "actualWeight": 5,
          "volumetricWeight": 1.69,
          "lengthCheck": null,
          "widthCheck": null,
          "heightCheck": null,
          "actualWeightCheck": null,
          "volumetricWeightCheck": null
        }
      ],
      "alternativeNumbers": [],
      "alternativeNumbersGW": [],
      "deliveryInfo": null,
      "undeliveryReasons": [
        {
          "reasonName": "Delivery date rescheduling has been agreed with the client",
          "reasonDate": "2025-07-01T09:35:46.000000Z",
          "reasonId": "66a936c6-f223-11dd-a18e-001d92f78697",
          "subtypeOfReasonId": "c30ec884-d9ff-11ed-a361-48df37b92096",
          "subtypeOfReasonName": "Recipient does not respond / Sender rescheduled the date to"
        }
      ],
      "createdOnTheBasis": [
        {
          "number": "51499647910100",
          "type": "Redirecting",
          "createdAt": "2025-07-01T09:19:49.000000Z"
        }
      ]
    }
  ]
}

Базове відстеження

get

/shipments/tracking/history

Цей API-метод дозволяє отримати статус відправлення, вказавши номер транспортного документа. Зазначивши номер документа в запиті, ви можете отримати інформацію про поточне місцезнаходження або статус відправлення, надаючи клієнтам оновлення в режимі реального часу щодо переміщення їхнього вантажу. 🔸Цей метод працює лише з номером транспортного документа (номером відправлення) і не підтримує пошук за номерами замовлень клієнта або будь-якими зовнішніми ідентифікаторами. 🔸Базове відстеження надає спрощену відповідь відстеження, зосереджену на історії статусів відправлення та, за потреби, пов'язаних номерах відправлень. На відміну від Повне відстеження, цей метод не повертає детальну інформацію про маршрут, дані на рівні окремих місць, причини недоставки, записи про повернення/переадресацію або розширені метадані. Цей метод призначений для швидкої та легкої перевірки статусів.

Authorizations

AuthorizationstringRequired

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

Query parameters

numbers[]stringOptional

Номери відправлень. Може приймати як один номер, так і масив номерів.

Example: SHPL1234567890

extendedstringOptional

Параметр, що відповідає за включення до відповіді масиву об'єктів зі списком усіх пов'язаних відправлень.

Щоб отримати ці дані у відповіді, встановіть значення 1.

Default: 0Example: 1

Responses

200

Схема відповіді відстеження

application/json

401

Неавторизований доступ

application/json

404

Вказаний ресурс не знайдено

application/json

422

Помилка валідації

application/json

503

Час очікування з’єднання вичерпано

application/json

get/shipments/tracking/history

GET /v.1.0/shipments/tracking/history HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "items": [
    {
      "id": "111003",
      "number": "SHPL1234567890",
      "history_tracking": [
        {
          "code": "1",
          "code_name": "Zamówienie zostało utworzone. Poczekaj na wysłanie przesyłki",
          "country_code": "PL",
          "settlement": "Głogów Małopolski",
          "date": "2023-03-10T05:57:09.626014Z"
        }
      ],
      "related_numbers": [
        "SHPL2345678901"
      ]
    }
  ]
}

Повне відстеження

get

/shipments/tracking

Цей API-метод дозволяє отримати статус відправлення, вказавши номер транспортного документа. Зазначивши номер документа в запиті, ви можете отримати інформацію про поточне місцезнаходження або статус відправлення, надаючи клієнтам оновлення в режимі реального часу щодо переміщення їхнього вантажу.

За замовчуванням відповідь містить такі блоки даних:

• Поточний статус відправлення;
• Історія відстеження;
• Актуальна історія відстеження;
• Опис відправлення;
• Розширена інформація про пов'язані відправлення.

За потреби до відповіді можна включити додаткові блоки, передавши відповідні параметри:

• withUndeliveryReason = true — додає масив об'єктів з інформацією про причини недоставки відправлень.
• withCreatedOnTheBasis = true — додає масив об'єктів з інформацією про повернення або переадресації, пов'язані з відправленням.

🔸Повне відстеження надає вичерпну відповідь відстеження, що містить детальні дані про статус відправлення, повну історію переміщення, опис місць, причини недоставки та інформацію про пов'язані або похідні відправлення. На відміну від Базового відстеження, воно надає розширені операційні дані та призначене для випадків, коли потрібна повна видимість логістичного життєвого циклу відправлення.

Authorizations

AuthorizationstringRequired

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

Query parameters

numbers[]stringOptional

Номери відправлень. Може приймати як один номер, так і масив номерів.

Example: SHPL1234567890

ids[]integer · int32Optional

Пошук відправлень за ідентифікаторами транспортних документів. Може приймати як один ідентифікатор, так і масив ідентифікаторів для виконання пошуку.

Example: 113622

withUndeliveryReasonbooleanOptional

Параметр, що відповідає за включення до відповіді масиву об'єктів з інформацією про причини недоставки.

Щоб отримати ці дані у відповіді, встановіть значення true.

Default: falseExample: true

withCreatedOnTheBasisbooleanOptional

Параметр, що відповідає за включення до відповіді масиву об'єктів з інформацією про пов'язані відправлення (типи: Redirecting, Return, Utilization, Redelivery).

Щоб отримати ці дані у відповіді, встановіть значення true.

Default: falseExample: true

countryCodestringOptional

Дволітерний код країни відправника відповідно до стандарту ISO 3166-1 Alpha-2.

Якщо цей параметр указано, Історія відстеження та Актуальна історія відстеження відображатимуться лише для зазначеної країни.

Pattern: ^[A-Z]{2}$

Example: DE

externalstringOptional

Параметр, що відповідає за включення до відповіді масиву об'єктів зі списком усіх пов'язаних відправлень, а також масиву, що містить розширену інформацію про ці відправлення — зокрема ім'я власника відправлення, номер відправлення та дату створення відправлення.

Щоб отримати ці дані у відповіді, встановіть значення 1.

Default: 0Example: 1

trackingByBarcodestringOptional

Система фільтрує агреговані дані та повертає інформацію лише для зазначеного місця. Це дозволяє відстежувати маршрут доставки конкретного місця у складі багатомісного відправлення.

Example: SHRO1452163509

withAllParcelsbooleanOptional

Система агрегує події з усіх місць в один масив, згрупований за номером місця. Це дозволяє відстежувати маршрут доставки кожного місця у складі багатомісного відправлення.

Default: falseExample: true

Responses

200

Схема відповіді відстеження

application/json

alternativeNumbersstring[]Optional

Масив об'єктів, що містить список пов'язаних відправлень.

401

Неавторизований доступ

application/json

404

Вказаний ресурс не знайдено

application/json

422

Помилка валідації

application/json

503

Час очікування з’єднання вичерпано

application/json

get/shipments/tracking

GET /v.1.0/shipments/tracking HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "items": [
    {
      "currentStatus": {
        "number": "SHPL2326420334",
        "createdDate": "2025-07-01T09:18:44.000000Z",
        "scheduledDate": "2025-07-01T15:00:00.000000Z",
        "scheduledDateOriginal": null,
        "adjustedDate": null,
        "closingDate": "2025-07-01T09:20:04.000000Z",
        "statusCode": 9,
        "status": "Delivered 01.07",
        "statusDate": "2025-07-01T09:20:11.299982Z",
        "deliveryType": "Division",
        "deliveryCountry": "DE"
      },
      "detailsTracking": [
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:18:46.000000Z",
          "event": "ArrivalSenderDoors",
          "eventStatus": "passed",
          "countryCode": "NL",
          "code": "5",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "The courier picked up the parcel",
          "postCode1": "1011",
          "postCode2": "1019"
        },
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:18:50.000000Z",
          "event": "Arrival",
          "eventStatus": "passed",
          "countryCode": "NL",
          "code": "5",
          "postCode": "1011AB",
          "divisionName": null,
          "settlementName": "Amsterdam",
          "eventName": "Arrived at branch 2",
          "postCode1": "1011",
          "postCode2": "1019"
        },
        {
          "number": "103-00160415",
          "date": "2025-07-01T09:19:37.000000Z",
          "event": "OrderRedirecting",
          "eventStatus": "passed",
          "code": "104",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "Delivery location has been changed",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": null
        },
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:20:04.000000Z",
          "event": "ReceivedWarehouse",
          "eventStatus": "now",
          "code": "9",
          "postCode": "1011AB",
          "divisionName": "branch 5",
          "settlementName": "Amsterdam",
          "eventName": "Delivered at branch 5",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": "NL"
        }
      ],
      "historyOnlineTracking": [
        {
          "number": "SHPL2326420334",
          "date": "2025-07-01T09:18:46.000000Z",
          "event": "ArrivalSenderDoors",
          "eventStatus": "passed",
          "countryCode": "NL",
          "code": "5",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "The courier picked up the parcel",
          "postCode1": "1011",
          "postCode2": "1019"
        },
        {
          "number": "103-00160415",
          "date": "2025-07-01T09:19:37.000000Z",
          "event": "OrderRedirecting",
          "eventStatus": "passed",
          "code": "104",
          "postCode": "1011AB",
          "divisionName": "",
          "settlementName": "",
          "eventName": "Delivery location has been changed",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": null
        },
        {
          "number": "51499647910100",
          "date": "2025-07-01T09:20:04.000000Z",
          "event": "ReceivedWarehouse",
          "eventStatus": "now",
          "code": "9",
          "postCode": "1011AB",
          "divisionName": "branch 5",
          "settlementName": "Amsterdam",
          "eventName": "Delivered at branch 5",
          "postCode1": "1011",
          "postCode2": "1019",
          "countryCode": "NL"
        }
      ],
      "parcelsDetailsTracking": null,
      "parcelsHistoryOnlineTracking": null,
      "parcels": [
        {
          "number": "SHPL2326420334",
          "rowNumber": null,
          "untied": false,
          "cargoCategoryGroup": "parcel",
          "cargoCategoryId": "",
          "categoryCargoName": "Parcel",
          "parcelDescription": null,
          "insuranceCost": 25,
          "insuranceCostCurrencyCode": "EUR",
          "length": 25,
          "width": 15,
          "height": 18,
          "actualWeight": 5,
          "volumetricWeight": 1.69,
          "lengthCheck": null,
          "widthCheck": null,
          "heightCheck": null,
          "actualWeightCheck": null,
          "volumetricWeightCheck": null
        }
      ],
      "alternativeNumbers": [],
      "alternativeNumbersGW": [],
      "deliveryInfo": null,
      "undeliveryReasons": [
        {
          "reasonName": "Delivery date rescheduling has been agreed with the client",
          "reasonDate": "2025-07-01T09:35:46.000000Z",
          "reasonId": "66a936c6-f223-11dd-a18e-001d92f78697",
          "subtypeOfReasonId": "c30ec884-d9ff-11ed-a361-48df37b92096",
          "subtypeOfReasonName": "Recipient does not respond / Sender rescheduled the date to"
        }
      ],
      "createdOnTheBasis": [
        {
          "number": "51499647910100",
          "type": "Redirecting",
          "createdAt": "2025-07-01T09:19:49.000000Z"
        }
      ]
    }
  ]
}

зміни по тасці - https://novaposhta.atlassian.net/browse/APIGW-3446

Create Light Return Shipment

post

/shipments/light-return

Creates a return after the original shipment has been delivered.

ℹ️ Information: To allow this request to work, the account manager must enable the LightReturn setting on the legal entity in the internal Nova Post system. Once this setting is activated, the request will function via API on new delivered shipments. The return can be created only if the parent shipment has the Delivered status and includes the AllowedLightReturn service. The current status of a shipment can be found in the "items" → "statusCode" field of the Find documents method. AllowedLightReturn defines the number of days within which the recipient can initiate a return after the delivery. Internally, the system verifies several conditions before allowing a Light Return shipment to be created:

• The parent shipment status must be one of: Issued (9, 10, 11, 106).
• The system calculates the allowed return period using the following logic: finalDate = toTZ(parentShipment.RecipientDateTime) + returnDays + 1 day where returnDays is taken from the AllowedLightReturn service, and toTZ applies the relevant system time zone (e.g., EU region).
• The return can be created only if the current time (nowTZ) is earlier than finalDate.
• The system also checks that no Light Return has already been created for the same parent shipment.

If all these conditions are met, the return creation request is accepted; otherwise, the system responds with a validation error indicating why the return is not permitted.

How the Light Return Shipment works (Ukraine → Europe)

• The request must include one required parameter — number (the parent shipment number). All other parameters are optional.
• Two return scenarios are supported:

  • Full Return – only the number parameter is required. All shipment data is inherited from the parent shipment.
  • Partial Return – additional shipment data (such as invoice and parcels) can be provided to return only selected goods or update parcel dimensions.
• If optional parameters are not specified, their values are automatically inherited from the parent shipment whenever possible.
• Only Nova Post branches are allowed as return handover locations.
• If the parent delivery was made to an APM (parcel locker), PUDO, or an address, the nearest available Nova Post branch is selected automatically.
• Customers may specify a valid divisionId directly in the request.
• Courier pickup, APMs (parcel lockers), and PUDO cannot be used as return handover locations.

Partial Return

For Partial Returns:

• All values in invoice.items[] must exactly match the corresponding items from the parent shipment.
• Creating new invoice items or modifying existing item values is not allowed.
• The initiating client is responsible for ensuring consistency between amount, cost, and actualWeight.
• To avoid validation errors, it is recommended to copy invoice data directly from the parent shipment.

When the return is created, the system automatically generates a return waybill. For more information on printing the return label, see Print Shipment Documents. For more information on creating a parent shipment, see Create documents.

Authorizations

AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Body

numberstringRequired

The number of the parent shipment for which the return is initiated. This parameter is mandatory to create a return.

Example: SHMD0000000000

divisionIdstringOptional

Identifier of the division that will process the return.

🔹This field is optional.

Example: 1835903

Responses

200

Successfully created Light Return shipment.

application/json

objectOptional

401

Unauthorized request — invalid or missing authentication token.

application/json

403

Parent shipment is missing the AllowedLightReturn parameter.

application/json

404

Parent shipment not found or status not allowed.

application/json

422

Parent shipment not found or status not allowed.

application/json

503

Service unavailable or request timeout.

application/json

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: 27

{
  "number": "SHPL1781477107"
}

{
  "id": "c1e37aba-75d8-11f1-9dff-8c8474c74d21",
  "number": 59500006924365,
  "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": "[e-mail]",
    "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": "[e-mail]",
    "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": "ThirdPerson",
  "payerContractNumber": "GNP000000000",
  "paymentStatus": "NeedPay",
  "currencyCode": "EUR",
  "parcelsAmount": 1,
  "note": "",
  "lockVersion": 1,
  "clientOrder": "",
  "gtid": "20000000000004085495",
  "firstMileDeliveryPartner": "Nova Post",
  "lastMileDeliveryPartner": "Nova Post",
  "parcels": [
    {
      "number": 59500006924365,
      "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": 59500006924365,
        "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": "SHPL51314899441",
      "id": 999999
    },
    "childShipment": null,
    "userMod": "00000000-0000-0000-0000-000000000020",
    "cargoAutoReturnDate": null
  },
  "markingPrinted": true
}

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

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 (номер батьківського відправлення). Усі інші параметри є опціональними.
• Підтримуються два сценарії повернення:

  • Повне повернення — необхідно передати лише параметр number. Усі дані відправлення успадковуються з батьківського відправлення.
  • Часткове повернення — можна передати додаткові дані відправлення (наприклад, invoice та parcels), щоб повернути лише вибрані товари або оновити габарити посилок.
• Якщо опціональні параметри не вказані, їх значення автоматично наслідуються з батьківського відправлення, коли це можливо.
• Як місця передачі відправлення для повернення дозволено використовувати лише відділення Nova Post.
• Якщо батьківське відправлення було доставлене до APM (поштомата), PUDO або за адресою, найближче доступне відділення Nova Post обирається автоматично.
• Клієнт може безпосередньо вказати валідний divisionId у запиті.
• Кур’єрський забір, APM (поштомати) та PUDO не можуть використовуватися як місця передачі відправлення для повернення.

Часткове повернення

Для часткового повернення:

• Усі значення в invoice.items[] повинні повністю відповідати відповідним товарам із батьківського відправлення.
• Створення нових товарних позицій інвойсу або зміна значень існуючих позицій не допускається.
• Клієнт, який ініціює повернення, несе відповідальність за узгодженість значень amount, cost та actualWeight.
• Щоб уникнути помилок валідації, рекомендується копіювати дані інвойсу безпосередньо з батьківського відправлення.

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

Authorizations

AuthorizationstringRequired

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

Body

numberstringRequired

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

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

Example: SHMD0000000000

divisionIdstringOptional

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

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

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

Example: 1835903

Responses

200

Successfully created Light Return shipment.

application/json

objectOptional

401

Unauthorized request — invalid or missing authentication token.

application/json

403

Parent shipment is missing the AllowedLightReturn parameter.

application/json

404

Parent shipment not found or status not allowed.

application/json

422

Parent shipment not found or status not allowed.

application/json

503

Service unavailable or request timeout.

application/json

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: 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": "[e-mail]",
    "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": "[e-mail]",
    "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
}