# Ukrposhta + Krokul CRM

Yes. Krokul CRM integrates with Ukrposhta through the eCom API. A manager creates a shipment right from the deal card, and Krokul sets up the address and recipient in Ukrposhta, returns the barcode and updates the parcel status on the deal by itself.

**Status:** Via API and webhooks.

## What your team gets

### An Ukrposhta shipment from the deal card

A manager opens the deal and clicks «Ship with Ukrposhta». Krokul takes the name, phone and address from the deal contact and creates an address (`/addresses`), a recipient client (`/clients`) and a shipment (`/shipments`) in Ukrposhta, in exactly the order the documentation requires. The barcode appears in the deal shipment and in the deal feed.

### Cash on delivery within the declared value

For payment on receipt, the manager enters the amount, and Krokul passes it in the postPay field of the shipment. Ukrposhta accepts a postPay no higher than declaredPrice, so Krokul sets the declared value to at least this amount. Krokul reads the state of the cash on delivery transfer from `/transfers/shipment-postpays/{barcode}/with-recipient` and closes the payment on the deal when the money has been transferred.

### Parcel movement next to the correspondence

On a schedule, Krokul reads `/shipments/{barcodeOrUuid}/lifecycle` for every active barcode. Statuses such as IN_DEPARTMENT or DELIVERED appear in the deal feed, and a company rule moves the deal to the right stage. The manager sees where the parcel is without opening tracking separately.

### A task for the manager when a shipment comes back

When a shipment gets the RETURNING status, Krokul creates a task for the owner with the deal and the barcode. The manager has time to call the client while the parcel travels back, and the RETURNED status records on the deal that the goods have come back.

### A label and form 103a for a batch of shipments

The manager prints the shipment address label from the deal card. To hand several parcels over at a branch, Krokul collects the selected shipments and gets the accompanying form 103a from the Ukrposhta forms service, which the warehouse prints as one file.

## What moves between Ukrposhta and Krokul

| Ukrposhta | Krokul | Direction | When |
|---|---|---|---|
| Address (`/addresses`) and recipient client (`/clients`) | Deal contact: name, phone, address | Krokul → Ukrposhta | A manager creates a shipment |
| Shipment (`/shipments`): weight, declaredPrice, postPay, deliveryType | Deal shipment and cash on delivery amount | Krokul → Ukrposhta | Right after the recipient is created |
| Shipment barcode | Shipment in the deal card, deal feed | Ukrposhta → Krokul | In reply to the shipment creation |
| Lifecycle (`/lifecycle`): IN_DEPARTMENT, DELIVERED, RETURNING, RETURNED | Shipment status, feed entry, deal stage | Ukrposhta → Krokul | Krokul polls on a schedule while the shipment is active |
| RETURNING status | Task for the owner | Ukrposhta → Krokul | The shipment travels back to the sender |
| Cash on delivery transfer | Actual deal payment | Ukrposhta → Krokul | When Ukrposhta has transferred the money |
| Address label and form 103a | Print buttons in the shipment and in the shipment register | Ukrposhta → Krokul | When a manager or the warehouse asks for it |

## How to connect today

### Your own flow through the Krokul API and webhooks

1. Sign a contract with Ukrposhta and get from your account manager a bearer for eCom, a counterparty token and separate values for the dev.ukrposhta.ua test environment.
2. In Krokul, create an API key with scopes for deals and documents, and subscribe a webhook to the `card.won` or `card.statusChanged` event filtered by stage. Each delivery carries the `x-crm-signature` header, which you check with your secret.
3. On the event, create an address, a recipient client and a shipment in Ukrposhta in the order /addresses → /clients → /shipments, taking the data from the deal through `card/api-read`.
4. Store the barcode on the deal through `externalRef/api-upsert`, and write the statuses from /lifecycle to the deal feed through `activity/api-create`.

### For integrators

Through the Krokul public API, you can create Ukrposhta shipments, read their status and link the barcode to the deal with an `externalRef` external key. The signal that an order is ready to ship comes from the signed `card.won` or `card.statusChanged` webhook filtered by stage, and the delivery log lets you redeliver an event. You can test the code in the Krokul sandbox on a demo company together with the Ukrposhta test environment.

[API documentation](https://app.krokul.com/api/v1/docs)

## Questions and answers

### Can I create an Ukrposhta shipment right on the deal card?

Yes. Krokul takes the recipient from the deal contact, creates the address, client and shipment in Ukrposhta and shows the barcode in the deal shipment.

### How does Krokul know that an Ukrposhta parcel is delivered?

Krokul polls the shipment lifecycle by barcode itself, because Ukrposhta sends no events. The DELIVERED status is recorded on the deal, and polling for that shipment stops.

### What do I need to connect Ukrposhta to Krokul?

A contract with Ukrposhta. Under it, your account manager issues a bearer for eCom and for StatusTracking, a counterparty token and separate test environment values, which your flow or the Krokul connection to Ukrposhta uses.

### Does Ukrposhta cash on delivery work with a Krokul deal?

Yes. The cash on delivery amount goes to the postPay field, and when Ukrposhta has transferred the money, Krokul records an actual payment on the deal.

## Limits

Ukrposhta sends no status change events, so Krokul reads the shipment lifecycle on a schedule. Ukrposhta grants API access under a contract, and the keys for the live and test environments are different.

## Related services

- [Nova Poshta](https://krokul.com/en/integrations/nova-poshta/index.md)
- [Meest](https://krokul.com/en/integrations/meest/index.md)
- [Rozetka](https://krokul.com/en/integrations/rozetka/index.md)
- [Horoshop](https://krokul.com/en/integrations/horoshop/index.md)
- [Checkbox](https://krokul.com/en/integrations/checkbox/index.md)

[Delivery (Ukraine)](https://krokul.com/en/integrations/category/delivery-ua/index.md)

Ukrposhta is a trademark of its owner. Krokul is not affiliated with Ukrposhta.

Updated: 2026-10-15

---

App: https://app.krokul.com/ · API: https://app.krokul.com/api/v1/docs