Elbuz connects to the Ukrposhta API: a waybill from the order card, a printed label and the parcel status every 10 minutes — no retyping into Ukrposhta's services.
When you need this:
- You ship with Ukrposhta under a contract — recipient, postcode and amount come from the order; one click per waybill.
- The customer pays on delivery — cash on delivery for the order amount is set if the order is unpaid.
- You have many parcels — bulk waybills from the order list, all parcel statuses in “Shipments”.
Where to start: get the API keys from your Ukrposhta manager → enter them in the Ukrposhta entry in Elbuz.
What Ukrposhta can do in Elbuz
- A waybill from the order — to a branch or an address, with cash on delivery and an SMS to the recipient; one at a time or in bulk.
- Label — a PDF from the order card or from “Shipments”.
- Parcel statuses — every 10 minutes; Elbuz changes the order, delivery and payment status by your code table.
- Parcel state in “Shipments” — on the way, at the branch, received, refused.
Registers, redirection, returns, editing and deleting a waybill, and calling a courier from Elbuz are available among Ukrainian services only for Nova Poshta. For Ukrposhta, these actions are done in its own services.
How to connect Ukrposhta: API keys and sender
Where to get Ukrposhta API keys
Keys are issued by your Ukrposhta manager after you sign a contract — they aren't in the personal account on the website. According to the Ukrposhta API documentation, after the contract you receive an access table:
- Bearer eCom — for creating shipments;
- Bearer StatusTracking — for parcel statuses;
- Counterparty token — the user token;
- Counterparty UUID — the counterparty ID.
You also need a sender UUID — the ID of the sending client with your address in the Ukrposhta system. It is created via the API; ask your manager or Ukrposhta API support (api-support@ukrposhta.ua) for a ready UUID.
The personal account on the Ukrposhta website is a separate service for individuals: shipments created via the API don't show up in it.
Where to enter the keys in Elbuz
Where: External services and integrations → “Delivery” group → the Ukrposhta entry.
- Paste the Bearer eCom into the “Token” field.
- In the “Ukrposhta parameters” block, fill in “Counterparty token” and “Sender UUID”.
- If the manager issued a separate Bearer StatusTracking, enter it in “Tracking token (StatusTracking)”. If the field is empty, statuses are requested with the same “Token”.
- Turn on “Active”.
The “User” and “Password” fields aren't needed for Ukrposhta. A saved key isn't shown: the “Token” field displays dots, and an empty field doesn't erase the key.
1
Token (Bearer eCom)2
Counterparty token3
Tracking token (StatusTracking)4
Order statuses to check5
Sender UUID- Token — the Bearer key issued by Ukrposhta eCom.
- Counterparty token — issued by Ukrposhta when connecting to the API.
- Tracking token (StatusTracking) — used to query parcel statuses.
- Order statuses list — orders in these statuses have their parcel status checked with the delivery service.
- Sender UUID — the sender identifier issued by Ukrposhta.
Delivery statuses: which Ukrposhta codes to enter
Elbuz changes the order status only for orders in the statuses marked in “Order statuses for which to check the parcel status with the delivery service”. What changes to what is set in three windows in the “Notification settings” block: “Order statuses”, “Delivery statuses”, “Payment statuses”.
Elbuz enters the Ukrposhta codes into “Delivery statuses” itself, and “Shipments” shows the parcel state by them. You fill in “Order statuses” and “Payment statuses”, comma-separated. The codes come from the Ukrposhta status tracking documentation:
| Your delivery status | Ukrposhta codes | What they mean |
|---|---|---|
| Awaiting sender | 10100 | Accepted at the branch |
| On the way | 20700, 20800, 20900, 21500 | Sorting center, dispatched, heading to the delivery branch |
| At destination | 21700, 21400, 31400 | Arrived at the delivery branch, held for pickup |
| Delivered | 41000 | Handed over |
| Refused | 31200, 41010 | The parcel is returning to the sender, the return was handed over to you |
1
Code (name) on site (API) column2
At destination3
Delivered4
Refused- Code (name) on site (API) — the Ukrposhta status codes mapped to each delivery status.
- At destination — 21700, 21400, 31400.
- Delivered — 41000.
- Refused — 31200, 41010.
To make orders switch to “Delivered” by themselves, enter 41000 next to “Delivered” in “Order statuses”. Elbuz stops asking about a parcel only when its code is next to “Delivered” or “Partially delivered” in “Delivery statuses”.
Ukrposhta marks a return handed over to you with the delivery code and the reason “to the sender” — Elbuz shows it as 41010, separately from 41000.
How to create a Ukrposhta waybill from an order
Where: order card → “Delivery” section → “Create waybill”. The link is there if the order's delivery type is Ukrposhta; after the form is opened for the first time, it's called “Edit waybill”.
What the form fills in itself and what to check
| Field | Where it comes from |
|---|---|
| Last name, First name, Middle name, Phone, E-Mail | From the order |
| Postcode | The postcode of the branch chosen on your Elbuz CMS website; otherwise, the postcode from the delivery address |
| Region, City, Street | From the delivery address |
| Total weight, kg | The sum of product weights; if empty, 1 kg is sent |
| Declared cost, UAH | The order amount |
| Return delivery (recipient) | “Money” for the order amount, if the order isn't paid and payment is on delivery |
| Delivery payer | “Recipient” if delivery in the order is 0; otherwise “Sender”. The cash-on-delivery fee is paid by the recipient |
“Shipping method” is “Branch” or “Address”. A courier order from an Elbuz CMS website opens the form with “Address” already selected.
For a branch, Ukrposhta takes only the postcode, so check that one. For an address, “Street”, “House” and “Apartment” appear.
1
Shipping method2
Postcode3
Cash on delivery: Money4
SMS notification5
Create waybill- Shipping method — switch between delivering to a branch or to an address.
- Postcode — the recipient's postcode, filled in from the order.
- Cash on delivery (recipient) with Money selected — the amount the recipient pays on receipt.
- SMS notification to the recipient — toggle for sending the recipient an SMS.
- Create waybill — sends the request to Ukrposhta (not pressed in the shot).
The form is saved to the order on every field change: open it next time and you'll see your values.
What happens after “Create waybill”
- Elbuz checks that the Ukrposhta entry has a counterparty token and sender UUID, and the form has a last name, first name, phone, postcode, city and declared cost.
- It creates the recipient's address in Ukrposhta, then the recipient, then the shipment itself.
- It writes the waybill number (barcode) to the order, and the window closes with the message “Waybill created, No.…”.
Ukrposhta is paid for delivery by whoever is selected in “Delivery payer”. Elbuz won't create a second waybill for the same order: “Waybill already exists: … — skipped.”
If the connection broke off, the order won't have a number. Clicking again will create a new shipment even if Ukrposhta managed to register the previous one — if in doubt, check with your Ukrposhta manager.
Waybills in bulk
Where: order list → check the orders → “Create waybill (shipping)”. The service is taken from each order's delivery type, and the values from the saved form or from the order.
Orders that already have a waybill number are skipped. More: waybills in bulk.
How to print a label
Where: order card → “View waybill” → “Print”, or “Shipments” → row → “Print waybill”.
Elbuz downloads the 100×100 mm PDF address label from Ukrposhta itself and opens it in a window. The keys never reach the browser. Bulk printing from “Shipments” works only for Nova Poshta waybills — print Ukrposhta labels one at a time.
How Elbuz tracks Ukrposhta parcels
Every 10 minutes Elbuz asks Ukrposhta for the latest status of each waybill. One pass covers up to 100 waybills, starting with those not checked for the longest time. Numbers from the old Ukrposhta module are tracked too.
- Which orders — created in the last 60 days or in the marked statuses, until the parcel code is next to “Delivered” in “Delivery statuses”.
- Orders in a marked status — the order, delivery and payment status changes by your tables, and the change goes to the log.
- Other orders — only the Ukrposhta status code and text are updated.
All parcels are visible in “Shipments”: state, tiles, filters, SMS to the recipient. The state comes from the “Delivery statuses” table; to update right now, click “Refresh statuses”.
Scenarios
First connection
What to do. Sign a contract and get the Bearer, counterparty token and sender UUID from your manager. Enter them in the Ukrposhta entry, mark the “Shipped” and “Delivered” statuses, fill in the codes in “Delivery statuses” and 41000 next to “Delivered” in “Order statuses”.
What you get. Waybills are created from the order card, and orders switch to “Delivered” by themselves once Ukrposhta has handed over the parcel.
Payment on delivery
What to do. Leave payment on delivery in the order and don't mark it as paid.
What you get. The waybill form already has “Money” for the order amount, and the recipient pays at the branch.
Orders from your website
What to do. Nothing: the shopper picks a Ukrposhta branch on your Elbuz CMS website.
What you get. The branch postcode is already in the form, and the waybill takes one click.
The day's shipments
What to do. In the order list, check the Ukrposhta orders → “Create waybill (shipping)”, then in “Shipments” click “Print” for each row.
What you get. Numbers in the orders, labels printed, statuses come in by themselves.
What to do when something goes wrong
| What you see | Why | What to do |
|---|---|---|
| “The delivery service is not connected: fill in its API settings…” instead of the form | The Ukrposhta entry has an empty “Token” or “Active” is off | Enter the Bearer and turn on “Active” (where to enter the keys) |
| “Error: sender uuid is required (API settings)” or “counterparty token is required (API settings)” | “Sender UUID” or “Counterparty token” isn't filled in | Fill in the “Ukrposhta parameters” block (API keys) |
| “Error: postcode is required for recipient” (or first_name, last_name, phone, city), “declared_price is required for shipment”; several are comma-separated | A required field in the form is empty | Fill in the first name, last name, phone, postcode, city or declared cost (form) |
| “Error: …” with Ukrposhta's text | Ukrposhta rejected the data: key, postcode, address, cash-on-delivery amount | Fix the field named in the error; for keys, contact your Ukrposhta manager |
| Ukrposhta parcels in “Shipments” are in the “Unknown” state | The “Delivery statuses” table of the Ukrposhta entry is empty | Enter the codes (code table) |
| Waybills are created, but parcel statuses don't come in | Ukrposhta issued a separate Bearer for status tracking, and its field is empty | Enter it in “Tracking token (StatusTracking)” (where to enter the keys) |
| “print error: …” in the print window | Ukrposhta didn't return the label: the waybill was deleted or the key isn't valid | Check the waybill in Ukrposhta's services and the keys in the entry |
FAQ
How much does the Ukrposhta integration cost?
Elbuz charges nothing for waybills, labels and statuses. You pay Ukrposhta for delivery under your contract.
Who pays for delivery — me or the recipient?
Whoever you select in “Delivery payer”. By default the recipient pays when the order has free delivery, otherwise you do. The cash-on-delivery fee is always paid by the recipient.
Can I ship to a parcel locker or abroad?
No, the form has only a branch and an address in Ukraine.
Are waybills from Elbuz visible in the Ukrposhta personal account?
No, according to the Ukrposhta documentation, shipments created via the API aren't shown in the personal account. You can see them in Elbuz in “Shipments”.
What is the maximum parcel weight?
According to the Ukrposhta API documentation — up to 30 kg for a single-piece shipment. To an address outside the courier delivery area — up to 2 kg and 70 cm.
Where to find it and who has access
- Menu
- Account → System settings → Other settings → External services and integrations → Delivery
- Other entry points
- Directories → Documents → Shipments → “Delivery services”; order card → “Delivery” section
- Access right
- connection — “API & access tokens”; waybill — the “Delivery waybill creation” window; parcels — “Shipments”
- Prepare
- a contract with Ukrposhta, the Bearer, counterparty token, sender UUID
A waybill can be created only for an order the user can see under the “Data scope” setting.
- Get the API keysUkrposhta manager
- Enter the keys and sender UUIDExternal services and integrations → Ukrposhta
- Mark statuses and fill in codesSame place, “Notification settings”
- Create a waybillOrder card, “Delivery” section
- Print the labelOrder card or Shipments
Related topics
- If you want to see parcels of all services in one list — Shipments.
- If you also ship with Nova Poshta — Nova Poshta API in Elbuz.
- If the order came from Rozetka and the waybill must be created through the marketplace — waybill via Rozetka.
- If you need waybills for dozens of orders — waybills in bulk.
