Skip to content

Nova Poshta

A bridge module to the carrier's business account. It keeps no delivery accounting in the bookkeeping sense — its job is to make sure the waybill is created straight from the document, and that its status finds its own way back into the system: "arrived at the branch", "collected", "returned".

The module's nature shows in its composition: eleven of its twelve registers are references downloaded from the Nova Poshta API. Cities, branches, cargo types, packaging, payer types — none of that lives with you, and none of it is entered by hand. Your part is one record with an access key and the sender's details.

The route: from the key to the waybill's status

NP setting (switch the module on, default sender, currency, cash on delivery)
        ↓
Account card "Nova Poshta": API key + who sends and from where
        ↓
Data download service → cities · branches · areas · cargo types · packaging
        ↓
Sales document → the waybill is created (recipient taken from the document)
        ↓
Waybill status update — the service asks the carrier what happened to the parcels
  1. NP setting — one window per company: it switches the module on inside documents and holds what does not belong to a single account — the default account, the currency, the way cash on delivery is passed.
  2. Nova Poshta — the account card: one record equals one API key plus the sender's details. This is where you describe yourself, not your customers.
  3. Nova Poshta under Maintenances (not to be confused with the register of the same name) — the data download service that fills the module's references. Until it has run, the fields in documents have nothing to offer.
  4. Address references: cities → branches (with their types), areas.
  5. Dispatch references: cargo types, packaging, pallets, payer types, and separately for returns — backward delivery cargo types and payers.
  6. Nova Poshta waybill status update — the service walks the waybills of shipments and Waybill (TTN) documents and writes the current status into the document.

What is worth understanding

References are not filled in by hand. The download service brings them and keeps them fresh. The largest is branches: over twenty thousand records in the demo database, loaded in a separate paged stream, and the longest part of the download. "My branch is missing" almost always means a stale download rather than a carrier error.

The account card is you as the sender. On whose behalf, from which city and branch the parcels go, who pays for the delivery. The recipient is taken from the document.

Counterparties come from the carrier's account, not from your database. They hold recipients and third parties — the types the business account stores. Senders live separately: a button on the account card pulls them in.

The split of roles between the setting and the card. The card answers "from where and from whom the parcel goes", the setting answers "which account to use by default and how to handle the money". Confusing them produces parcels from the wrong sender.

A waybill's status lives its own life. It changes on the carrier's side, and the system learns about it only when the update service runs. Put it on a schedule, or your documents will show yesterday's statuses.

There can be several accounts. One record, one key — that is how several senders or several legal entities coexist in one database.

Where to start in a new database

  1. NP setting — switch the module on inside documents.
  2. Account card — the API key from the business account and the sender's details.
  3. The Nova Poshta service — the first data download, the longest; after it the references are populated.
  4. Create a test waybill from a document and check that picking a city and a branch works.
  5. Put Nova Poshta waybill status update on a schedule.

Common tasks

You need Where to go
connect the business account Nova Poshta
switch the module on in documents NP setting
refresh cities and branches Maintenances → Nova Poshta
find out where a parcel is Nova Poshta waybill status update
find a branch NP Warehouses · NP Cities
look at the recipients from the account NP Counterparties
set up cash on delivery NP Setting · NP Types of Payers for Redelivery

Everything in the module

Access references: Nova Poshta · NP counterparties

Address references: NP cities · NP warehouses · NP warehouse types · NP areas

Dispatch references: NP cargo types · NP pack list · NP pallets list · NP types of payers · NP backward delivery cargo types · NP types of payers for redelivery

Settings: NP setting

Maintenance: Nova Poshta (data download) · Nova Poshta waybill status update

Where to look next

  • Sales orders — the recipient and their branch for Nova Poshta delivery (the order's "Nova Poshta" tab). The express waybill itself is created in Nova Poshta by "Create express waybill (NP)" — in the shipment or in a Waybill (TTN) document. The Waybill document is created by "Create a waybill" in the shipment or "Create TTN" in an invoice issued not from an order and with "Update warehouse" ticked; that item sends nothing to Nova Poshta by itself.
  • Stock — the shipment travelling to the customer.
  • Prom · Rozetka — the marketplaces whose orders most often travel by Nova Poshta.