Search by

sergiynezbritskiy / ukrposhta-api

sergiynezbritskiy

Library for connecting to Ukrposhta API

Package info

github.com/sergiynezbritskiy/ukrposhta-api

pkg:composer/sergiynezbritskiy/ukrposhta-api

Statistics

Installs: 107

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

1.1.1 2026-11-07 22:16 UTC

This package is auto-updated.

Last update: 2026-11-07 22:22:42 UTC


README

Library for connecting your PHP application with Ukrposhta REST API

codecov

Scrutinizer Code Quality Build Status Code Intelligence Status

Latest Stable Version Total Downloads Latest Unstable Version License PHP Version Require

Installation

The easiest way to install module is using Composer

composer require sergiynezbritskiy/ukrposhta-api

Configuration

In order to use this library you need two credentials issued by Ukrposhta after signing the eCom contract (ask your Ukrposhta manager, there is no self-service registration):

  • Bearer eCom - sent in the Authorization: Bearer header;
  • Counterparty token - sent in the token query parameter.

Ukrposhta provides a separate pair of credentials for the sandbox (dev.ukrposhta.ua), pass 'sandbox' => true in the options to use it.

Usage

Using library is as easy as possible

//create client for connecting with API
$client = new \SergiyNezbritskiy\Ukrposhta\Client('<your_bearer>', '<your_token>');
//or for the sandbox
$client = new \SergiyNezbritskiy\Ukrposhta\Client('<sandbox_bearer>', '<sandbox_token>', ['sandbox' => true]);

//1. create addresses
$senderAddress = $client->address->save(['postcode' => '07401', 'region' => 'Київська', 'city' => 'Бровари', /* ... */]);
$recipientAddress = $client->address->save(['postcode' => '04071', 'region' => 'Київ', 'city' => 'Київ', /* ... */]);

//2. create sender and recipient
$sender = $client->client->save([
    'type' => \SergiyNezbritskiy\Ukrposhta\Models\Client::TYPE_INDIVIDUAL,
    'firstName' => 'Петро',
    'lastName' => 'Петренко',
    'phoneNumber' => '0671231234',
    'addressId' => $senderAddress['id'],
]);
$recipient = $client->client->save([/* ... */ 'addressId' => $recipientAddress['id']]);

//3. create shipment
$shipment = $client->shipment->save([
    'sender' => ['uuid' => $sender['uuid']],
    'recipient' => ['uuid' => $recipient['uuid']],
    'deliveryType' => \SergiyNezbritskiy\Ukrposhta\Models\Shipment::DELIVERY_TYPE_W2D,
    'paidByRecipient' => true,
    'parcels' => [['weight' => 1200, 'length' => 170]],
]);

//4. print the sticker
file_put_contents('sticker.pdf', $client->forms->getShipmentSticker($shipment['uuid']));

Every other option from the request body of the corresponding endpoint can be passed through the arrays, see the PHPDoc of the model methods and the Swagger below.

Address classifier

The address classifier returns the regions and the post offices (branches), e.g. to let a customer pick a branch:

//1. find the region, the response is a list of matches by the part of the name
$regions = $client->classifier->getRegions(['region_name' => 'Київ']); // or ['region_name_en' => 'Kyiv']
// [['REGION_ID' => '286', 'REGION_UA' => 'Київ', 'REGION_EN' => 'Kyiv', ...], ['REGION_ID' => '270', 'REGION_UA' => 'Київська', ...]]

//2. get all the post offices of the region (optionally narrowed down with district_id, city_id or postindex)
$postOffices = $client->classifier->getPostOffices(['region_id' => 286]);
// [['ID' => '266', 'PO_SHORT' => 'Київ 26', 'POSTINDEX' => '03026', 'ADDRESS' => 'вул. Заболотного Академіка, 37', 'LOCK_CODE' => '0', ...], ...]

//3. or find the post offices near the given coordinates, within 2 km
$nearest = $client->classifier->getNearestPostOffices(50.450166, 30.523307, 2);

The classifier is authorized with the bearer only. With 'sandbox' => true the sandbox classifier (https://dev.ukrposhta.ua/address-classifier-ws/) is used; mind that its IDs differ from the production ones (e.g. the Kyiv region is 389 in the sandbox and 286 in production). Pass 'classifier_uri' => 'https://...' in the client options to override the base URL. Post offices with LOCK_CODE other than Classifier::LOCK_CODE_ACTIVE are blocked.

Notes

For more details please visit documentation and Swagger