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

Page 1

Create Shipment

post
/shipments

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.

Authorizations
AuthorizationstringRequired

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

Body
statusstring · enumOptional

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.
Possible values:
clientOrderstring · max: 50Optional

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 · max: 255Optional

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.

deliveryTypestringOptional

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*string · enumOptional

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

Possible values:
payerContractNumberstring · min: 2 · max: 20 · nullableOptional

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.

Responses
post
/shipments

Last updated