README

UPS Turkey (UPS Kargo) carrier driver for the Omniship shipping library.

Uses the UPS Turkey domestic SOAP API with session-based authentication.

Installation

composer require tcgunel/omniship-ups

Usage

Initialize

use Omniship\Omniship;

$carrier = Omniship::create('UPS');
$carrier->initialize([
    'username' => 'your-username',
    'password' => 'your-password',
    'customerNumber' => 'your-customer-number',
    'testMode' => true, // false for production
]);

Create Shipment

UPS Turkey requires numeric CityCode and AreaCode for both shipper and consignee addresses. These are UPS-specific codes (see UmoCityAreaCode.xls in docs).

use Omniship\Common\Address;
use Omniship\Common\Package;
use Omniship\Common\Enum\PaymentType;

$response = $carrier->createShipment([
    'shipFrom' => new Address(
        name: 'Serkan Kose',
        company: 'UPS TURKIYE',
        street1: 'Mevlana Cd. No:85 UPS Plaza',
        city: 'Istanbul',
        postalCode: '34896',
        phone: '02124132222',
        email: 'skose@ups.com',
    ),
    'shipTo' => new Address(
        name: 'Ismet Kutuk',
        company: 'KOSE A.S.',
        street1: 'Dumlupinar Mh. Alibaba Cd. No:57',
        city: 'Istanbul',
        postalCode: '34400',
        phone: '04444444444',
        email: 'ismet@example.com',
    ),
    'packages' => [
        new Package(
            weight: 2.0,
            length: 20,
            width: 25,
            height: 15,
            description: 'ORTA BOY KOLI',
        ),
    ],
    'shipperCityCode' => 34,          // required - UPS city code
    'shipperAreaCode' => 1707,         // required - UPS area code
    'consigneeCityCode' => 34,         // required - UPS city code
    'consigneeAreaCode' => 463,        // required - UPS area code
    'serviceLevel' => 3,              // 3=Standard (default)
    'packageType' => 'K',             // K=Package, D=Letter
    'paymentType' => PaymentType::SENDER,
    'invoiceNumber' => 'INV-001',     // optional
    'reference' => 'REF-001',         // optional
    'cashOnDelivery' => false,
    'codAmount' => 0.0,
    'codCurrency' => 'TL',
])->send();

if ($response->isSuccessful()) {
    echo $response->getTrackingNumber(); // "1Z340006800001006"
    echo $response->getShipmentId();     // same as tracking number
    echo $response->getBarcode();        // base64 PNG barcode image
    echo $response->getLabelLink();      // URL for label printing

    // All barcode images (one per package)
    $barcodes = $response->getBarcodeArray();

    // Label object with format info
    $label = $response->getLabel();
} else {
    echo $response->getMessage(); // error description
    echo $response->getCode();    // UPS error code
}

Track Shipment

Tracking uses the separate Query Package Info web service. The system logs in automatically.

$response = $carrier->getTrackingStatus([
    'trackingNumber' => '1Z340006800001006',
])->send();

if ($response->isSuccessful()) {
    $info = $response->getTrackingInfo();
    echo $info->trackingNumber;
    echo $info->status->value;  // pre_transit, in_transit, delivered, etc.
    echo $info->carrier;        // "UPS Kargo"
    echo $info->signedBy;       // person who signed for delivery

    foreach ($info->events as $event) {
        echo $event->description;
        echo $event->occurredAt->format('Y-m-d H:i');
        echo $event->location;   // branch name
        echo $event->status->value;
    }
}

Cancel Shipment

$response = $carrier->cancelShipment([
    'trackingNumber' => '1Z340006800001006',
])->send();

if ($response->isCancelled()) {
    echo 'Shipment cancelled';
} else {
    echo $response->getMessage(); // error description
}

Get Rates

Rate queries require CityCode and AreaCode for both shipper and consignee (same codes as createShipment).

use Omniship\Common\Package;
use Omniship\Common\Enum\PaymentType;

$response = $carrier->getRates([
    'shipperCityCode' => 34,          // required - UPS city code
    'shipperAreaCode' => 1707,         // required - UPS area code
    'consigneeCityCode' => 6,          // required - UPS city code
    'consigneeAreaCode' => 463,        // required - UPS area code
    'packages' => [
        new Package(weight: 2.0),
    ],
    'paymentType' => PaymentType::SENDER,
])->send();

if ($response->isSuccessful()) {
    foreach ($response->getRates() as $rate) {
        echo $rate->serviceCode;       // "3"
        echo $rate->serviceName;       // "DOM. STANDARD"
        echo $rate->totalPrice;        // 45.50 (tax-inclusive)
        echo $rate->currency;          // "TL"
        echo $rate->transitDays;       // 2
    }
}

Service Levels

Payment Types

Status Mapping

For StatusCode 1, the status is inferred from Turkish keywords in the event description (kabul, aktarma, dagitim, teslim, iade, etc.).

API Endpoints

SOAP Methods Used

Session Management

UPS Turkey uses session-based authentication. Each API call:

1. Calls Login_Type1 (or Login_V1) to get a SessionID
2. Uses that SessionID for the actual operation

Sessions expire after 5 minutes of inactivity. The library handles login automatically on each request.

Testing

vendor/bin/pest

License

MIT