Nova Post API

Globe Pickup Points integrates with Nova Post, enabling order export and shipping label printing directly from Shopify for parcels sent from an EU country. With this integration, you can:

• Export orders to Nova Post directly from Shopify
• Print shipping labels within Shopify
• Ship to a Nova Post branch, parcel locker or PUDO point selected at checkout, or to the customer’s address
• Send parcels to Ukraine, Moldova and the United Kingdom with a customs invoice built from the order
• Collect cash on delivery on the routes where Nova Post offers it

Beta

This integration is in beta: if something does not work as described, contact help@appfleece.com.

---

Enabling Nova Post API integration

1. In your Shopify admin, open Globe Pickup Points and go to Shipping labels. Click Add carrier and select Nova Post.
2. Enter your API key. Create it in my.novapost.com under Integrations, API keys, signed in as the authorised representative named in your Nova Post contract.
3. Select the Environment: Production for real shipments, Development for Nova Post’s test environment. A production key works only with Production, a test key only with Development.
4. Enter your Contract number. Shipments are paid by you as the sender, and Nova Post bills them to this contract. If you have a separate contract for international shipping, enter it in International contract number. Globe then uses it for parcels to another country.
5. Enter your Company ID (tax ID): the tax ID of the organisation in your Nova Post contract, for example IČO, NIP or Steuernummer. It must be an organisation your API key was created for.
6. Fill in Sender company name, Sender name (the contact person shown on the label), Sender phone (a full international number, for example +420777123456), Sender email and Sender country. The sender country must be in the EU.
7. Set how your parcels reach Nova Post:
   • At a branch: enter Nova Post branch for handing over parcels, either the branch number as Nova Post shows it (for example 14/1) or the division ID.
   • By courier from your address: leave the branch empty and fill in Sender street, Sender house number, Sender ZIP and Sender city. The house number can also be written in Sender street.
8. Enter Default length in millimeters, Default width in millimeters and Default height in millimeters. Nova Post requires length, width and height on every parcel and uses them for the volumetric weight. Globe sends these values for all parcels.
9. If you offer cash on delivery, fill in the COD settings described in Cash on delivery (COD).
10. Under Show advanced settings, you can set Customs terms (Incoterms), Sender EORI number, Default content description, Default HS code and Default weight (kg). The customs settings are described in Customs and international shipments.
11. Configure Automatically fulfill orders, Automatically tag orders with tracking number and Custom tag after export as needed.
12. In Shipping methods, assign your Shopify shipping methods to the Nova Post services described in Service types. Shipping methods can be assigned for the 27 EU countries, Ukraine, Moldova and the United Kingdom.

---

Exporting and printing labels

You can export orders to Nova Post and print shipping labels directly from Shopify, either in bulk or individually. See Creating shipping labels for the general workflow.

Before the first order is sent, Globe checks the settings and signs in to Nova Post with your API key. If a setting is missing or the key is refused, no order is sent. Globe also checks each order for data Nova Post would refuse, such as a missing phone number or house number. An order that fails these checks is not sent, so you can fix it and export it again.

Each order is sent as one shipment with one parcel:

• Weight — the order weight, rounded to 10 g (at least 10 g)
• Dimensions — the default length, width and height from the settings
• Insurance value — the Declared value, by default the order total, in the order currency
• Contents — the Content description, or the product titles of the order when it is empty

You can change the weight, declared value, COD amount, HS code and content description of a shipment under Advanced when creating the label.

Nova Post returns a shipment number such as SHCZ0123456789. Globe stores it as the tracking number and downloads the label from Nova Post each time you print. The tracking link opens https://novapost.com/en-<country>/tracking/<shipment number>/ for the country in the shipment number (for example en-pl for SHPL…), or en-cz when that country has no tracking page. If Automatically fulfill orders is enabled, the fulfillment is created with the shipment number, the carrier name Nova Post and this link.

If Nova Post does not answer in time or the connection breaks off, the shipment may exist at Nova Post although Globe has no number for it. Globe then marks the order with a note to check my.novapost.com before creating the label again, and stops the batch before the next order. The orders that were not sent can be exported again safely.

Globe does not cancel shipments at Nova Post. To cancel a shipment, delete it in my.novapost.com.

---

Service types

When mapping shipping methods or creating a label, choose one of these services:

Service	Delivery
Nova Post (branch or parcel locker if selected, otherwise address)	To the Nova Post branch, parcel locker or PUDO point the customer selected at checkout. An order without a pickup point goes to the customer’s address.
Nova Post courier (address)	Always to the customer’s shipping address, also when the order has a pickup point.
Nova Post branch or parcel locker	To the Nova Post branch, parcel locker or PUDO point on the order. An order without one is refused.

With both services that deliver to a point, a pickup point from another carrier’s network is refused rather than sent to the customer’s address. Choose a Nova Post point with the Modify pickup point action, or create the label with Nova Post courier (address).

---

Pickup points vs. address delivery

The services that deliver to a point send the parcel to the Nova Post branch, parcel locker or PUDO point the customer selected at checkout. Globe sends the Nova Post ID of that point, so the point has to come from the Nova Post network in the Globe pickup point selector. To offer Nova Post points at checkout, add Nova Post as a pickup point carrier — see Adding pickup point carriers. Nova Post branches that another carrier lists in its own network, for example Packeta or Boxpi, carry that carrier’s IDs and are refused.

Nova Post has no branches, parcel lockers or PUDO points in Bulgaria, Croatia, Cyprus, Greece, Malta and Slovenia. Parcels to these countries can only go to the customer’s address.

For address delivery, Nova Post needs the street and the house number in separate fields. Globe takes the house number from the first address line (Vinohradská 12/34, 12 rue de la Paix) or from the start of the second line, and sends a flat number written after the house number (byt 4, m. 5, Apt 2B) as the flat. An address without a house number, street, city or postcode is refused.

Nova Post requires the recipient’s phone number on every shipment, including branches and parcel lockers. A number without a country code is read as a number of the destination country. Nova Post refuses a recipient in Poland without a Polish number (+48) and a recipient in Ukraine without a Ukrainian number (+380).

---

Customs and international shipments

Parcels that leave the EU (to Ukraine, Moldova or the United Kingdom) need a customs invoice. Globe fills in Nova Post’s own commercial invoice from the order. You can print it with the label (see Label printing).

The invoice carries the total value of the goods, the order currency, the export reason Selling and the Customs terms (Incoterms) from the settings: DAP (customer pays import duties), the default, or DDP (you pay import duties). Each product line that ships and has a price becomes one item with:

• the product title from Shopify, as the item name and as its English name (Nova Post expects that name in English)
• quantity and unit price
• the HS code from the product in Shopify, or else the HS code set when creating the label or the Default HS code
• the country of origin from the product, when it is set
• a share of the parcel weight by product weight, so that the item weights add up to the parcel weight as Nova Post requires

HS codes need at least 6 digits. Nova Post accepts 8 to 10 digits, so Globe fills a 6-digit code up with zeros (610910 becomes 61091000). Parcels to Moldova get exactly 10 digits. When no product line qualifies, Globe declares the whole parcel as one item with the content description (or Goods), the order value and the HS code set when creating the label or the Default HS code.

Nova Post declares goods under HS 210690 (food preparations such as dietary supplements) and HS 630900 (worn clothing) in kilograms. Globe converts these items to kilograms from the product weight. A parcel can contain only one such item, and at most 10 kg of it.

Parcels leaving the EU also need the customer’s email address on the order. Parcels to Ukraine need a Sender name in Latin letters: accents are fine, Cyrillic or Greek letters are not. The Sender EORI number is optional and recommended for parcels leaving the EU.

---

Cash on delivery (COD)

Nova Post collects cash on delivery within Czechia, Poland and Germany, and from Czechia, Poland, Germany and Slovakia to Ukraine. Nova Post has to enable cash on delivery on your contract (a COD agreement).

When the order’s payment method is cash on delivery, Globe adds Nova Post’s COD service with the outstanding amount of the order. You can change the amount in COD amount when creating the label.

Fill in these settings:

• IBAN for cash on delivery — the account Nova Post pays the collected money to. The payout goes to the company in Company ID (tax ID).
• COD agreement number — the number of your COD agreement. Leave it empty if you have only one contract.
• Who pays the COD fee — Sender (you), the default, or Recipient. It must match your COD agreement.

Globe sends cash on delivery only when the order is in the currency of your sender country: CZK from Czechia, PLN from Poland, EUR from Germany and Slovakia. A COD order on a route Nova Post does not collect on, in another currency or without a valid IBAN is refused before anything is created.

---

Label printing

Globe downloads the labels from Nova Post as PDF when you print. Two print options are available:

Print option	What is printed
10x15 or 10x10 cm (size set by Nova Post)	The shipment label. Nova Post sets the size for each shipment: 100 × 150 mm or 100 × 100 mm.
Label + commercial invoice A4 (parcels leaving the EU)	The label, followed by Nova Post’s commercial invoice on A4 for every parcel that left the EU. Parcels within the EU get the label only.

When you print several shipments, Globe joins their documents into one PDF in the order of the shipments. Position on paper is always 1.

---

Troubleshooting

Issue	Resolution
”Nova Post settings are incomplete”	The message lists the missing settings. Fill them in on the carrier account and save.
”Globe creates Nova Post labels for senders in the EU”	Set Sender country to the EU country you ship from.
”The sender phone must be a full international number”	Enter Sender phone with the country code, for example +420777123456.
”The sender address needs a house number”	Enter Sender house number, or set Nova Post branch for handing over parcels.
”Nova Post did not accept the API key” or “Nova Post says the API key is not active”	Check the API key and the Environment: a production key works only with Production, a test key only with Development. An inactive key must be activated in my.novapost.com or by your Nova Post manager.
”Access to the company is forbidden by API key” or “Nova Post refused the request for this API key”	Company ID (tax ID) must be an organisation your API key was created for. Check the key in my.novapost.com.
”Recipient phone number is missing”, “Nova Post needs a Polish phone number (+48)” or “…a Ukrainian phone number (+380)“	Add the customer’s phone number with the country code to the order’s shipping address. Recipients in Poland need a Polish number, recipients in Ukraine a Ukrainian one.
”Nova Post needs the house number in its own field” or “the shipping address needs a street, city and postcode”	Complete the order’s shipping address, including the house number.
”Nova Post does not know the recipient’s city”	Check the city name in the shipping address.
”Order … has no weight”	Set the product weights in Shopify, enter the weight when creating the label, or set Default weight (kg) in the advanced settings.
”has no Nova Post branch or parcel locker”, “is not a Nova Post branch or parcel locker” or “is not a Nova Post division id”	Choose a Nova Post branch or parcel locker with the Modify pickup point action, or create the label with Nova Post courier (address) to ship to the customer’s address.
”parcels to Ukraine need the sender name in Latin letters”	Change Sender name to Latin letters.
”Nova Post needs the customer’s e-mail for parcels leaving the EU”	Add the customer’s email address to the order.
”parcels leaving the EU need an HS code”	Add the HS code to the product in Shopify, or set a Default HS code in the advanced settings.
Goods under HS 210690 or 630900 refused	Nova Post takes one such item per parcel, at most 10 kg, and needs its weight. Add the product weight in Shopify, or split the goods into more parcels in my.novapost.com.
Cash on delivery refused for the route or currency	Nova Post collects cash on delivery only on the routes and in the currencies listed in Cash on delivery (COD). Use another carrier for the order, or set the COD amount to 0 when creating the label.
”no valid IBAN for the collected money” or “Nova Post refused the cash on delivery bank account”	Check IBAN for cash on delivery and COD agreement number in the settings.
”Nova Post did not answer in time”, “did not confirm the shipment” or “The connection to Nova Post broke off”	The shipment may exist. Check my.novapost.com before creating the label again.
”Globe could not connect to Nova Post”, “the Nova Post login did not answer” or “Nova Post is limiting requests right now”	Nothing was created. Try again in a minute.
”Do not create the label again”	Nova Post created the shipment, but Globe could not save it. Print the label in my.novapost.com, or delete the shipment there before creating a new one.
”Globe stopped before sending order …”	An earlier order in the batch got no usable answer or could not be saved. Nothing was created for this order, so its label can be created again.
Other messages starting with “Nova Post:“	The text comes from Nova Post’s validation and names the field it refused. Fix the order or the settings and export again.
”Error printing Nova Post labels”	The details show the shipment number and Nova Post’s reason, for example Shipment not found. Check the shipment in my.novapost.com.