Nova Poshta: setup, waybills and tracking
How to connect Nova Poshta to X10 CRM: the API key, senders, the shipment template, creating waybills from a lead card and in bulk, printing labels and updating lead statuses automatically from tracking.
The Nova Poshta integration removes the dullest part of a manager’s job: no opening the carrier’s cabinet, no copying names, phone numbers and branches by hand, no checking every day whether a parcel has been collected. A waybill is created from the lead card with one click, labels are printed in batches, and lead statuses update themselves as the parcel travels.
What the integration gives you from the store's point of view is on the Nova Poshta in X10 CRM page, and how delivery fits into the whole order cycle on CRM for an online store.
#Step 1. Get the Nova Poshta API key
- 01
Sign in to the Nova Poshta business cabinet
The key is issued for a specific counterparty — the one the shipments will go out from. If you have several legal entities, you need a key for each.
- 02
Create the key in the security section
Find the API keys section in the cabinet settings and create a new key. It is shown once — copy it immediately.
- 03
Check the counterparty’s limits
If the counterparty is not allowed to create express waybills through the API, Nova Poshta will reject the requests even with a valid key. That is resolved with your Nova Poshta account manager, not in the CRM.
#Step 2. Create the integration in the CRM
Open Settings → Integrations → Nova Poshta. If no integration exists yet, the CRM creates an empty one automatically. Fill in the main fields:
Main integration settings
NametextAny name you like. It matters when there are several integrations — for example
Main entityandWholesale entity.API keytextrequiredThe key from the Nova Poshta cabinet. Without it, creating a waybill fails immediately.
ActiveswitchWaybill creation and tracking work only with an active integration. If several are active, the first one created is used.
Who pays for deliverySender / RecipientThe default for every new waybill. For cash-on-delivery goods it is usually
Recipient.Payment controlswitchEnables the Nova Poshta payment control mode for shipments from this integration.
Cargo branches onlyswitchLimits delivery points to cargo branches — needed if you ship oversized items.
#Step 3. Senders and directory synchronisation
The sender is the counterparty the parcel goes out from. Add them in the integration: name, full name and phone. Then be sure to click “Synchronise data”.
Synchronisation pulls the internal identifiers — sender_ref and sender_contact_ref — from Nova Poshta. The CRM takes them only from its own database; it does not look the sender up on the fly while creating a waybill. So without synchronisation no waybill will be created.
#Step 4. Dispatch branches
Add the branch or parcel locker you physically hand parcels over at. The CRM stores its warehouse_ref and city_ref — both are needed for a waybill. Several branches can be added: a warehouse in Kyiv and one in Lviv, for example.
If the shipment template does not name a specific branch, the CRM takes the first one on the list. When you have several warehouses, set the right one explicitly, otherwise parcels will go out from the wrong city.
#Step 5. The shipment template
The template holds the values that are pre-filled into every new waybill, so the manager does not type them each time. Any field can be overridden by hand on a specific waybill.
| Field | Possible values | Default |
|---|---|---|
| Delivery payer | Sender / Recipient | The value from the integration settings |
| Payment method | Cash / NonCash | Cash |
| Cargo type | Parcel, Cargo, Documents, TiresWheels, Pallet | Parcel |
| Service type | WarehouseWarehouse, WarehouseDoors, DoorsWarehouse, DoorsDoors | WarehouseWarehouse; for courier delivery the CRM sets WarehouseDoors itself |
| Contents description | text | “Handmade goods” |
| Declared value | number | 100; if left empty, the lead’s cart total is used |
| Weight, kg | number | 0.5 |
| Number of packages | integer | 1 |
| Dimensions (W × L × H) | numbers, optional | empty |
| Return delivery | on / off + payer + amount | off; payer Sender |
| Default sender and branch | from the lists above | the first active one |
#Creating a waybill from a lead card
In the lead card click to create a waybill, check the pre-filled data and confirm. The CRM creates the recipient in Nova Poshta as a private person and returns the waybill number, which is written into the lead straight away.
What the lead must contain
| Delivery type | Required data |
|---|---|
| Branch or parcel locker | The city and the branch, chosen from the suggestions — the CRM stores not only the names but also the directory city_ref and np_department_ref |
| Courier delivery | City, region, street, house number and the settlement type |
| Any | The recipient’s phone number in the lead |
How the CRM processes recipient data
- The phone number is reduced to digits, and a number starting with
0gets the38prefix:068 123 45 67→380681234567. - The full name is split on spaces: the first word is the surname, the second the first name, the rest the patronymic.
- If the name has only one word, Nova Poshta receives it as the surname and “Customer” is used as the first name. So ask managers to fill in at least a surname and a first name.
- The declared value is rounded to a whole number.
#Bulk waybills and label printing
Filter the leads on the dashboard, select the ones you need and choose the bulk action. This is the main mode of work for a warehouse: a hundred waybills created in one go.
- Bulk waybill creation — the CRM walks through every selected lead. Those with missing data do not stop the process: you get a report listing the leads and the reason for each failure.
- Label printing — a PDF for all the numbers at once. Two formats are available:
100×100for a thermal printer andA4for a regular one. - Courier list — an export for handing the parcels over.
#Automatic tracking: statuses update themselves
The CRM polls Nova Poshta for the status of every waybill and updates the leads. The source of truth is the waybill number stored on the lead; leads without a number are not polled.
Polling schedule
| When | Run times |
|---|---|
| Monday – Friday | 08:00, 10:00, 13:00, 15:00, 17:00, 19:00 |
| Saturday and Sunday | 10:00 and 16:00 |
Up to 100 waybills are sent per request to Nova Poshta, and large volumes are split into batches automatically — there is no limit on the number of leads.
Status mapping
The most valuable part of the integration: you map Nova Poshta status codes onto your own CRM statuses. Leads then move along the pipeline by themselves.
- Mapping — a Nova Poshta status code moves the lead into the CRM status you specify. The classic example: the parcel is collected → the lead moves to “Paid for”.
- Excluded codes — Nova Poshta statuses that should not move a lead at all.
- Statuses to track — polling can be limited to certain CRM statuses so that long-closed leads are not re-checked.
- Day-based rules — if a parcel stays in the same Nova Poshta status for a given number of days, the lead moves into the status you choose. This is how refusals are caught: the parcel has been sitting at the branch for five days → the lead goes to “Not collected”. These rules take priority over ordinary mapping.
Manual synchronisation
If you do not want to wait for the next scheduled run, the Nova Poshta settings have a button to force synchronisation. Handy for checking straight after changing the mapping.
#Errors and what they mean
The CRM returns errors in plain language — the text tells you immediately which setup step was skipped.
| Message | Cause | What to do |
|---|---|---|
| “Nova Poshta API key is not configured” | The key is empty or there is no active integration | Settings → Integrations → Nova Poshta: paste the key and switch “Active” on |
| “No active sender in the Nova Poshta integration” | The sender has not been created or is disabled | Add a sender and mark them active |
| “The active sender has no refs” | Directory synchronisation has not been run | Click “Synchronise data” in the Nova Poshta settings |
| “No dispatch branch configured” | No dispatch warehouse has been added | Add the branch you hand parcels over at |
| “City/branch refs are missing” | The city or branch in the lead was typed as text instead of chosen from the suggestions | Re-select the city and branch in the card from the dropdown |
| “Fields missing for courier delivery…” | The city, region, street, house number or settlement type is missing | Fill in the fields listed in the error |
| “The lead has no recipient phone number” | The phone field is empty | The phone number is mandatory — Nova Poshta will not accept a waybill without it |
| Statuses are not updating | The integration is inactive, or the lead is in a status outside the tracked list | Check that the integration is active and review the list of tracked statuses |
#Permissions
| Action | Permission required |
|---|---|
| Seeing the waybill in a lead and printing labels | leads.ttn.view |
| Creating and editing waybills | leads.ttn.edit |
| Bulk waybill creation | leads.bulk.create_ttn |
| Bulk label printing | leads.bulk.print_np_marking |
| Exporting the courier list | leads.bulk.courier_list |
| Integration settings | Administrator or superadministrator only |
#Launch checklist
- The API key has been obtained in the Nova Poshta cabinet and pasted into the CRM
- The integration is marked active, and only one is
- A sender has been added and directory synchronisation has been run
- The dispatch branch has been added and selected in the template
- The template holds your own contents description, weight and delivery payer
- A test waybill has been created on a real lead and is visible in the Nova Poshta cabinet
- Labels print in the format you need
- Nova Poshta statuses are mapped onto CRM statuses
- Day-based rules are configured to catch refusals
- It has been verified that a status change fires the SMS trigger