↑↓ selectEnter openEsc close

    1. Elbuz
    2. Delivery services in Elbuz

    Ukrposhta API in Elbuz: a waybill from the order, labels and parcel statuses

    5 min readUpdated

    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.

    1. Paste the Bearer eCom into the “Token” field.
    2. In the “Ukrposhta parameters” block, fill in “Counterparty token” and “Sender UUID”.
    3. 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”.
    4. 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.

    Ukrposhta connection form with the Token field and the Ukrposhta parameters block
    1Token (Bearer eCom)
    2Counterparty token
    3Tracking token (StatusTracking)
    4Order statuses to check
    5Sender UUID
    1. Token — the Bearer key issued by Ukrposhta eCom.
    2. Counterparty token — issued by Ukrposhta when connecting to the API.
    3. Tracking token (StatusTracking) — used to query parcel statuses.
    4. Order statuses list — orders in these statuses have their parcel status checked with the delivery service.
    5. Sender UUID — the sender identifier issued by Ukrposhta.
    Elbuz doesn't check the keys when you save. You'll see a key error only on the first waybill — as Ukrposhta's response text.

    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 statusUkrposhta codesWhat they mean
    Awaiting sender10100Accepted at the branch
    On the way20700, 20800, 20900, 21500Sorting center, dispatched, heading to the delivery branch
    At destination21700, 21400, 31400Arrived at the delivery branch, held for pickup
    Delivered41000Handed over
    Refused31200, 41010The parcel is returning to the sender, the return was handed over to you
    Delivery statuses table with Ukrposhta codes
    1Code (name) on site (API) column
    2At destination
    3Delivered
    4Refused
    1. Code (name) on site (API) — the Ukrposhta status codes mapped to each delivery status.
    2. At destination — 21700, 21400, 31400.
    3. Delivered — 41000.
    4. 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

    FieldWhere it comes from
    Last name, First name, Middle name, Phone, E-MailFrom the order
    PostcodeThe postcode of the branch chosen on your Elbuz CMS website; otherwise, the postcode from the delivery address
    Region, City, StreetFrom the delivery address
    Total weight, kgThe sum of product weights; if empty, 1 kg is sent
    Declared cost, UAHThe 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.

    Ukrposhta waybill form opened from the order, full window
    1Shipping method
    2Postcode
    3Cash on delivery: Money
    4SMS notification
    5Create waybill
    1. Shipping method — switch between delivering to a branch or to an address.
    2. Postcode — the recipient's postcode, filled in from the order.
    3. Cash on delivery (recipient) with Money selected — the amount the recipient pays on receipt.
    4. SMS notification to the recipient — toggle for sending the recipient an SMS.
    5. 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”

    1. 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.
    2. It creates the recipient's address in Ukrposhta, then the recipient, then the shipment itself.
    3. 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.”

    The waybill goes into the Ukrposhta system immediately. You can't delete it from Elbuz — only in Ukrposhta's services; then clear the number in the order's “Delivery service: number” field.

    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

    Common problems
    What you seeWhyWhat 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.

    1. Get the API keysUkrposhta manager
    2. Enter the keys and sender UUIDExternal services and integrations → Ukrposhta
    3. Mark statuses and fill in codesSame place, “Notification settings”
    4. Create a waybillOrder card, “Delivery” section
    5. Print the labelOrder card or Shipments

    Related topics

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free