Кур'єрська доставка

Створити заявку на кур’єрський забір

post

/pickups

Цей метод дозволяє бізнес-клієнтам створити нову заявку на кур’єрський забір by specifying essential parameters such as the pickup address, parcel type, and additional details.

Initial Status (Draft): The pickup request is created in the Draft status, which allows clients to add all necessary shipments to the request.

Transition to Created: Once all shipments are added, clients must use the "Update pickup request status" method to change the status to Created. This indicates that the pickup is finalized and ready for processing by the courier service.

Time Intervals: To include a specific time interval for the pickup, clients should retrieve available time intervals using the corresponding method. This ensures that the requested pickup time aligns with the courier's schedule and availability.

This method is available to business clients in EU countries where Nova Post operates.

🔹Опис елементів керування:

SCHEMA

Відображає повну технічну структуру запиту або відповіді, включаючи назви полів, типи даних, обов’язкові поля, допустимі значення та правила валідації.

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Показує готовий приклад JSON із правильно сформованими значеннями для демонстрації того, як має виглядати валідний запит або відповідь.

Authorizations

AuthorizationstringRequired

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

Body

notestring · max: 255Optional

Optional notes or instructions for the courier.

servicesstring[] · nullableOptional

List of additional services that can be included in the pickup request. This functionality is currently under development.

phonestring · min: 8 · max: 14Optional

The contact phone number of the sender, required to allow the courier to reach out if necessary.

emailstring · nullableOptional

While not mandatory, providing an email is recommended as a backup contact method in case the phone number is incorrect or for additional notifications regarding the pickup.

fullNamestring · max: 100Optional

Full name of the client sending the parcel, essential for identifying the sender and ensuring accurate handling of the pickup.

companyTinstring · min: 2 · max: 20Optional

The tax identification number (TIN) of a legal entity.

companyNamestring · min: 2 · max: 255Optional

Name of the company requesting the pickup.

countryCodestringOptional

ISO Alpha-2 code for the pickup location.

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

pickedTimeFromstring · date-time · nullableOptional

Start of the pickup time window, selected from available time intervals provided by the method that returns available time slots. If no time slot is specified, the courier will schedule the pickup at their discretion.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$

pickedTimeTostring · date-time · nullableOptional

End of the pickup time window, selected from available time intervals provided by the method that returns available time slots. If no time slot is specified, the courier will schedule the pickup at their discretion.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$

Responses

201

Pickup request created successfully

application/json

401

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

application/json

404

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

application/json

422

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

application/json

503

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

application/json

post

/pickups

POST /v.1.0/pickups HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 492

{
  "note": "Test pickup request",
  "services": [],
  "phone": "420123456789",
  "email": "test@example.cz",
  "fullName": "Test User",
  "companyTin": "CZ12345678",
  "companyName": "Test Company CZ",
  "countryCode": "CZ",
  "addressParts": {
    "city": "Prague",
    "region": "Prague",
    "street": "Václavské náměstí",
    "postCode": "11000",
    "building": "1",
    "flat": "10",
    "block": "2",
    "note": "Information about building entrance for courier access"
  },
  "pickedTimeFrom": "2024-12-01T15:00:00.000000Z",
  "pickedTimeTo": "2024-12-01T18:00:00.000000Z"
}

{
  "id": 28813,
  "number": "PUCZ0000002671",
  "status": "Draft",
  "statusDateTime": "2024-12-01T13:55:57.350277Z",
  "source": "clientapi",
  "executor": null,
  "companyTin": "CZ12345678",
  "companyName": "Test Company CZ",
  "fullName": "Test User",
  "phone": "420123456789",
  "email": "test@example.cz",
  "countryCode": "CZ",
  "createdByUser": "96c9000-00000000-0000-000a12aed5d9",
  "deliveryPartner": null,
  "lockVersion": 1,
  "divisionId": null,
  "settlementId": 142473,
  "cityDistrict": null,
  "address": {
    "string": "11000, Czech Republic, Prague, Prague, Václavské náměstí, 1, 2, 10, Information about building entrance for courier access",
    "latitude": 50.080316,
    "longitude": 14.428728
  },
  "addressParts": {
    "postCode": "11000",
    "building": "1",
    "street": "Václavské náměstí",
    "city": "Prague",
    "region": "Prague",
    "flat": "10",
    "note": "Information about building entrance for courier access",
    "block": "2"
  },
  "pickedTimeFrom": "2024-12-01T15:00:00.000000Z",
  "pickedTimeTo": "2024-12-01T18:00:00.000000Z",
  "note": "Test pickup request",
  "currencyCode": "CZK",
  "externalId": null,
  "shipments": [],
  "services": [],
  "statuses": [
    {
      "id": 109777,
      "pickupId": 28813,
      "status": "Draft",
      "dateTime": "2024-12-01T13:55:57.350277Z",
      "note": null,
      "user": "96c9000-00000000-0000-000a12aed5d9",
      "createdAt": "2024-12-01T13:55:57.350861Z",
      "updatedAt": "2024-12-01T13:55:57.350861Z",
      "deletedAt": null
    }
  ],
  "createdAt": "2024-12-01T13:55:57.350861Z",
  "updatedAt": "2024-12-01T13:55:57.350861Z",
  "deletedAt": null
}

Оновити заявку на кур’єрський забір

put

/pickups/{id}

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

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

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

Path parameters

idinteger · min: 1Required

Unique identifier of the pickup request to be updated.

Body

notestring · max: 255Optional

Optional notes or instructions for the courier.

servicesstring[] · nullableOptional

List of additional services that can be included in the pickup request. This functionality is currently under development.

phonestring · min: 8 · max: 14Optional

The contact phone number of the sender, required to allow the courier to reach out if necessary.

emailstring · nullableOptional

While not mandatory, providing an email is recommended as a backup contact method in case the phone number is incorrect or for additional notifications regarding the pickup.

fullNamestring · max: 100Optional

Full name of the client sending the parcel, essential for identifying the sender and ensuring accurate handling of the pickup.

companyTinstring · min: 2 · max: 20Optional

The tax identification number (TIN) of a legal entity.

companyNamestring · min: 2 · max: 255Optional

Name of the company requesting the pickup.

lockVersioninteger · min: 1Optional

Version number for concurrency control to avoid conflicting updates. When using this method and making updates, the value of this parameter must be incremented by 1 for each subsequent change.

countryCodestringOptional

ISO Alpha-2 code for the pickup location.

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

pickedTimeFromstring · date-time · nullableOptional

Start of the pickup time window, selected from available time intervals provided by the method that returns available time slots.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$

pickedTimeTostring · date-time · nullableOptional

End of the pickup time window, selected from available time intervals provided by the method that returns available time slots.

Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$

Responses

200

Pickup request updated successfully.

application/json

401

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

application/json

404

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

application/json

422

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

application/json

503

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

application/json

put

/pickups/{id}

PUT /v.1.0/pickups/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 500

{
  "note": "Update note for the pickup",
  "services": [],
  "phone": "420123456789",
  "email": "test@example.cz",
  "fullName": "Updated Test User",
  "companyTin": "CZ98765432",
  "companyName": "Updated Test Company CZ",
  "lockVersion": 2,
  "countryCode": "CZ",
  "addressParts": {
    "city": "Prague",
    "region": "Prague",
    "street": "Národní",
    "postCode": "11000",
    "building": "9",
    "flat": "2",
    "block": "1",
    "note": "Updated building entrance information"
  },
  "pickedTimeFrom": "2024-12-02T14:00:00.000000Z",
  "pickedTimeTo": "2024-12-02T18:00:00.000000Z"
}

{
  "id": 28813,
  "number": "PUCZ0000002671",
  "status": "Draft",
  "lockVersion": 2,
  "note": "Na Rizdvo Sobi",
  "pickedTimeFrom": "2024-12-02T14:00:00.000000Z",
  "pickedTimeTo": "2024-12-02T18:00:00.000000Z",
  "addressParts": {
    "city": "Prague",
    "region": "Prague",
    "street": "Národní",
    "postCode": "11000",
    "building": "9",
    "flat": "2",
    "block": "1",
    "note": "Updated building entrance information"
  },
  "statuses": [
    {
      "id": 109777,
      "status": "Draft",
      "dateTime": "2024-11-13T18:52:57.350277Z",
      "createdAt": "2024-11-13T18:52:57.350861Z",
      "updatedAt": "2024-12-02T14:10:00.000000Z"
    }
  ]
}

Додати відправлення до заявки на кур’єрський забір

post

/pickups/{id}/shipments

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

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

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

Path parameters

idinteger · min: 1Required

Unique identifier of the pickup request to which shipments are being added.

Body

Responses

200

Shipments successfully added to the pickup request.

application/json

401

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

application/json

404

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

application/json

422

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

application/json

503

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

application/json

post

/pickups/{id}/shipments

POST /v.1.0/pickups/{id}/shipments HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "shipments": [
    {
      "shipmentId": 370681
    }
  ]
}

{
  "shipments": [
    {
      "id": 31951,
      "pickupId": 28814,
      "shipmentId": 370681,
      "status": "Added",
      "note": null,
      "deliveryPartners": [],
      "createdAt": "2024-11-13T20:20:06.772369Z",
      "updatedAt": "2024-11-13T20:20:29.125274Z",
      "deletedAt": null
    }
  ]
}

Оновити статус заявки на забір

put

/pickups/{id}/status

Цей метод дозволяє оновлювати статус наявної заявки на кур’єрський забір. Цей метод спеціально розроблений для переведення заявки на виклик кур'єра зі статусу Draft у статус Created.

Поки заявка перебуває у статусі Draft, вона залишається на підготовчому етапі, під час якого можна додати всі необхідні відправлення. Щойно статус оновлюється на Created, система управління відправленнями розпізнає виклик кур'єра як завершений і готовий до обробки кур'єрською службою.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

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

Path parameters

idinteger · min: 1Required

The unique identifier of the pickup request.

Body

statusstring · enumRequired

This field is used to update the status of a pickup request to indicate that the pickup request is finalized and ready for processing by the shipment management system.

Possible values:

lockVersioninteger · min: 1Required

Version number for concurrency control to avoid conflicting updates. When using this method and making updates, the value of this parameter must be incremented by 1 for each subsequent change.

notestring · max: 255Optional

A required note or comment providing additional information about the reason for the status update. This field must be filled when changing the status to ensure proper tracking and context.

Responses

200

Status updated successfully

application/json

401

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

application/json

404

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

application/json

422

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

application/json

503

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

application/json

put

/pickups/{id}/status

PUT /v.1.0/pickups/{id}/status HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 103

{
  "status": "Created",
  "lockVersion": 2,
  "note": "Pickup request finalized and ready for courier assignment"
}

{
  "success": true
}

Видалити заявку на виклик кур'єра

delete

/pickups/{id}

Цей метод дозволяє бізнес-клієнтам повністю видалити існуючу заявку на виклик кур'єра. При видаленні заявки на виклик кур'єра вона позначається в системі як видалена, а також фіксується дата та час видалення. Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Нова Пошта.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

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

Path parameters

idinteger · min: 1Required

Unique identifier of the pickup request to be deleted.

Responses

200

Pickup request deleted successfully.

application/json

401

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

application/json

404

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

application/json

422

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

application/json

503

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

application/json

delete

/pickups/{id}

DELETE /v.1.0/pickups/{id} HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Accept: */*

{
  "deletedAt": "2024-11-13T20:29:47.285749Z"
}

Отримати список заявок на кур’єрський забір

get

/pickups

Цей метод дозволяє бізнес-клієнтам отримати список усіх створених ними заявок на кур’єрський забір. Клієнти можуть фільтрувати список за окремими параметрами, наприклад за ID забору або номером заявки. Цей метод доступний для бізнес-клієнтів у країнах ЄС, де працює Nova Post.

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

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

Query parameters

numbers[]stringOptional

Search pickups by document number. Can accept either a single search number or an array of numbers for conducting the search.

Example: PUCZ0000002671

ids[]integer · int32Optional

A list of pickup request IDs to search. Can accept either a single search number or an array of numbers for conducting the search.

Example: 28813

limitinteger · int32Optional

Max number of items to return on page.

Default: 15Example: 1

pageinteger · int32Optional

Number of page to return.

Example: 1

Responses

200

List of courier pickup requests retrieved successfully.

application/json

401

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

application/json

404

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

application/json

422

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

application/json

503

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

application/json

get

/pickups

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

{
  "current_page": 1,
  "last_page": 1,
  "per_page": 15,
  "total": 1,
  "items": [
    {
      "id": "28813",
      "number": "PUPL0000013342",
      "versionTracking": null,
      "status": "Draft",
      "statusDateTime": "2024-12-20T09:01:56.927000Z",
      "createdAt": "2024-12-20T09:01:56.928000Z",
      "updatedAt": "2024-12-20T11:58:08.731000Z",
      "deletedAt": null,
      "lastPublishedAt": "2024-12-20T11:58:08.000000Z",
      "lastUpdatedAt": "2024-12-20T11:58:08.831311Z",
      "source": "clientapi",
      "executor": null,
      "companyTin": "",
      "companyName": null,
      "fullName": "Chulkov Ihor",
      "phone": "380001234567",
      "email": "i.s.chulkov@gmail.com",
      "country": "Poland",
      "countryCode": "PL",
      "createdByUser": "84dbbfac-3508-11ee-a361-48df37b92096",
      "deliveryPartner": null,
      "lockVersion": 2,
      "divisionId": null,
      "settlementId": 22326,
      "settlementExternalId": null,
      "settlementName": "Warsaw",
      "cityDistrict": null,
      "cityDistrictExternalId": null,
      "address": {
        "postCode": "17890",
        "region": "Warszawa County",
        "city": "Warszawa",
        "street": "15 Sierpnia",
        "building": "1",
        "block": "",
        "flat": "",
        "note": "",
        "address": "17890, Polska, Województwo mazowieckie, Warszawa County, Warszawa, 15 Sierpnia, 1, , , ",
        "addressId": null,
        "latitude": 52.3264159,
        "longitude": 20.9854961,
        "timeZoneId": 367,
        "timeZone": "Europe/Warsaw"
      },
      "addressParts": {
        "postCode": "17890",
        "region": "Warszawa County",
        "city": "Warszawa",
        "street": "15 Sierpnia",
        "building": "1",
        "block": "",
        "flat": "",
        "note": "Information about building entrance for courier access"
      },
      "pickedTimeFrom": "2024-12-01T15:00:00.000000Z",
      "pickedTimeTo": "2024-12-01T18:00:00.000000Z",
      "note": "Test pickup request",
      "currencyCode": "CZK",
      "shipments": [],
      "services": [],
      "statuses": [
        {
          "id": 109777,
          "pickupId": 28813,
          "status": "Draft",
          "dateTime": "2024-12-01T13:55:57.350277Z",
          "note": null,
          "user": "d389d1ec-2078-4b62-8bc0-696c72a52a65",
          "createdAt": "2025-01-22T07:58:52.388849Z",
          "updatedAt": "2025-01-22T07:58:52.388849Z",
          "deletedAt": null
        }
      ]
    }
  ]
}

Видалити відправлення із заявки на забір

delete

/pickups/{id}/shipments

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

🔹Опис елементів керування:

SCHEMA

Single line description Опис, що вміщується в один рядок; текст, який не поміщається, залишається прихованим.
Multiline description Розширений опис, що відображає більше одного рядка тексту.

EXAMPLE

Authorizations

AuthorizationstringRequired

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

Path parameters

idinteger · min: 1Required

The unique identifier of the pickup request.

Body

Responses

200

Shipments removed successfully

application/json

401

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

application/json

404

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

application/json

422

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

application/json

503

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

application/json

delete

/pickups/{id}/shipments

DELETE /v.1.0/pickups/{id}/shipments HTTP/1.1
Host: api-stage.novapost.com/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "shipments": [
    {
      "shipmentId": 370681
    }
  ]
}

{
  "shipments": [
    {
      "deletedAt": "2024-11-13T20:22:56.818679Z"
    }
  ]
}

ПопередняРеєстри НаступнаWebhooks

Останнє оновлення 1 день тому