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

Відстеження відправлення

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

get
/shipments/tracking/history

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

Authorizations
AuthorizationstringRequired

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

Query parameters
numbers[]stringOptional

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

Example: SHPL1234567890
extendedstringOptional

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

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

Default: 0Example: 1
Responses
200

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

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

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

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"
        }
      ]
    }
  ]
}
ПопередняДрук документів
НаступнаProof of delivery

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