Page 1
Create a Shipment Document. test test test This API method is engineered to streamline the process of generating a shipping document for logistics operations through Nova Post. By submitting key data, such as the originating and destination addresses for the shipment, users can effortlessly create a document detailing the transportation of goods. This method includes optional fields for customs authorities, accommodating shipments that cross borders. The API response will provide the unique identifier of the generated document along with other relevant information.
Settlement validation rules:
For shipments to or from Moldova and Ukraine, the settlement (city) must be successfully resolved.
If the provided city value cannot be matched to a settlement, the request will fail with the error: validation.condition.recipient_settlement_not_defined.
Additional requirement: For shipments that require customs clearance (imports), the client invoice must be uploaded as a file through the POST /shipments/uploads/{id} method (after shipment creation).
🔹Description of control elements:
SCHEMA Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.
Single line description A description that fits into a single line; any text that does not fit remains hidden.
Multiline description An expanded description that displays more than one line of text.
EXAMPLE Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.
Authorization JWT-token with a lifetime of 1 hour in header
Signifies the current status of the transportation document, tracking its progress through the shipping lifecycle. Statuses detail each critical phase:
- Draft: The document is in its preliminary stage, not yet finalized.
- Accepted: Reviewed and accepted, the document is ready for the next steps.
- Issued: The document has been completed and is ready for shipping.
- ReadyToShip: Indicates that the shipment is prepared for transport following the creation of the express waybill. Only this value can be specified when creating a shipment.
- Deleted: The document has been deleted from the system.
- Returned: The shipment has been returned to its sender.
- Utilized: Indicates that the physical goods associated with the transportation document have been disposed of or destroyed and the document is closed.
Represents all potential order identifiers associated with the shipment. These identifiers are set by the customer for internal tracking purposes and are crucial for tracking the shipment throughout its journey. All entered values can be tracked in the shipment's tracking system.
Any additional information or special instructions that pertain to the order can be included here. This could encompass delivery instructions, special handling requests, or other pertinent details that facilitate the handling and processing of the shipment.
Defines the tariff type to be applied to the shipment during creation or update.
standard: Standard international delivery tariff.economy: Economy international delivery tariff.express: Express international delivery tariff.
If the field is not provided, the tariff type is determined automatically according to current business rules, and the existing shipment creation behaviour remains unchanged.
🔹This field is optional.
Identifies who is responsible for the payment of delivery services. The payer type determines which party bears the cost:
- Sender: The party sending the goods pays for the delivery.
- Recipient: The party receiving the goods is responsible for the delivery cost.
- ThirdPerson: A third party, not the sender or recipient, pays for the delivery services. When selecting 'ThirdPerson', the field 'payerContractNumber' must be populated with the contract number of the paying party. For more detailed information, refer to the article on Payment for Delivery Services via Nova Post API. This field is also referenced when generating an invoice.
🔻This field is required
This field is required in the following cases:
- When the
payerTypeis set toThirdPerson. It must contain the payer's contract number. For clients from Ukraine, it is also acceptable to provide the tax identification number (EDRPOU) instead of the contract number. - When the
payerTypeis set toSenderorRecipientand a non-cash payment method is used.
If this field is not provided in the cases described above, the payment method will automatically default to cash.
Ensure that the provided information is accurate, as it is essential for correct payment processing.
For more detailed information, refer to the article on Payment for Delivery Services via Nova Post API.
Successfully created shipment.
A unique identifier assigned to each shipment, facilitating internal operations such as modifications, system searches, and deletion of shipments. The 'id' serves as a key reference for administrative and logistical processes within the delivery system, allowing precise access and management of shipment records.
The format of the id depends on the shipment direction (first/last mile):
- For EU shipments, the value is a numeric shipment ID (e.g.,
754116) used for search operations. - For UA shipments, the value is a UUID reference (e.g.,
56abe014-451c-11f0-a1d5-48df37b921da) used for search byref.
The transportation document number provided to clients for tracking purposes and accessing printed forms. It also facilitates shipment searches within the system, offering a customer-friendly way to monitor shipment progress. While 'number' is used externally for tracking and documentation, it can also serve internal needs similar to 'id' for identifying shipments in certain system operations.
^[A-Z]{4}\d{10}$Estimated delivery date based on routing and service level, subject to change based on logistics and external factors. Date in ISO 8601 format.
2023-04-14T09:00:00ZCurrent status of the shipment. Initially set to "ReadyToShip" upon creation, indicating it's prepared for dispatch.
Total cost calculated for the delivery services provided, based on shipment size, weight, destination, and service options selected.
31.5The total number of parcels included in the shipment. This count helps in logistics planning and tracking.
The date-time when the shipment record was created in the system. Date in ISO 8601 format.
2023-04-11T10:42:05ZThe last date-time when the shipment record was updated. Helps in tracking changes and updates made to the shipment details.Date in ISO 8601 format.
2023-04-11T10:42:05ZThe date-time when the shipment was canceled or removed from the system. If not canceled, this field is null.
Unauthorized
The specified resource was not found
Validation error
Connection time-out
POST /v.1.0/shipments HTTP/1.1
Host: api-stage.novapost.pl/
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 882
{
"status": "ReadyToShip",
"clientOrder": "",
"note": "",
"payerType": "Sender",
"invoice": null,
"services": [],
"parcels": [
{
"cargoCategory": "parcel",
"number": null,
"parcelDescription": "parcel for redirect test",
"insuranceCost": 100,
"rowNumber": 1,
"width": 200,
"length": 350,
"height": 100,
"actualWeight": 2000,
"volumetricWeight": 2000
},
{
"cargoCategory": "parcel",
"number": null,
"parcelDescription": "parcel for redirect test",
"insuranceCost": 100,
"rowNumber": 2,
"width": 200,
"length": 350,
"height": 100,
"actualWeight": 2000,
"volumetricWeight": 2000
}
],
"sender": {
"companyTin": "",
"companyName": "",
"phone": "380007654321",
"email": "sender@test.com",
"name": "Maks Tester",
"countryCode": "CZ",
"divisionId": 1834581,
"addressParts": {},
"ioss": null
},
"recipient": {
"companyTin": "",
"companyName": "",
"phone": "380001234567",
"email": "recipient@test.com",
"name": "Chuck Norris",
"countryCode": "PL",
"divisionId": 27255,
"addressParts": {}
}
}{
"id": 113677,
"number": "SHLT4009860665",
"scheduledDeliveryDate": "2023-04-14T09:00:00.000000Z",
"status": "ReadyToShip",
"cost": 31,
"parcelsAmount": 1,
"createdAt": "2023-04-11T10:42:05.543380Z",
"updatedAt": "2023-04-11T10:42:05.543380Z",
"deletedAt": null
}Last updated