Sign in
latestOpenAPI 3.0.02026-08-10234193.3 KB

60e380005037

Shipments

Create Shipment

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: </br> For shipments to or from Moldova and Ukraine, the settlement (city) must be successfully resolved. </br> 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).</br>

🔹Description of control elements:

SCHEMA</br> 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</br> A description that fits into a single line; any text that does not fit remains hidden.
  • Multiline description</br> An expanded description that displays more than one line of text.

EXAMPLE</br> Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.

post/shipments

Request body

status'ReadyToShip'

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.
clientOrderstring

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.

notestring

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.

deliveryTypestring

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.

payerType*'Sender' | 'Recipient' | 'ThirdPerson'

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

payerContractNumberstring nullable

This field is required in the following cases:

  • When the payerType is set to ThirdPerson. 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 payerType is set to Sender or Recipient and 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.

Response

Successfully created shipment.

idstring uuid

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 by ref.
numberstring

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.

scheduledDeliveryDatestring date-time nullable

Estimated delivery date based on routing and service level, subject to change based on logistics and external factors. Date in ISO 8601 format.

statusstring

Current status of the shipment. Initially set to "ReadyToShip" upon creation, indicating it's prepared for dispatch.

costnumber float

Total cost calculated for the delivery services provided, based on shipment size, weight, destination, and service options selected.

parcelsAmountinteger

The total number of parcels included in the shipment. This count helps in logistics planning and tracking.

createdAtstring date-time

The date-time when the shipment record was created in the system. Date in ISO 8601 format.

updatedAtstring date-time

The 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.

deletedAtstring date-time nullable

The date-time when the shipment was canceled or removed from the system. If not canceled, this field is null.