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

Code	Service
1	DOM. EXPRESS PLUS 09:00
3	DOM. STANDARD (default)
4	DOM. EXPRESS 10:30
5	DOM. EXPRESS 12:00
6	DOM. EXPRESS SAVER

Payment Types

Code	Description	Omniship Enum
1	Consignee (receiver) pays	`PaymentType::RECEIVER`
2	Shipper (sender) pays	`PaymentType::SENDER`
4	Third party pays	`PaymentType::THIRD_PARTY`

Status Mapping

UPS StatusCode	Omniship Status	Description
1	Varies by description	Normal event (keyword-matched)
2	`DELIVERED`	Delivery event
3	`FAILURE`	Exception event

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

API Endpoints

Service	URL
Create Shipment	`https://ws.ups.com.tr/wsCreateShipment/wsCreateShipment.asmx`
Package Query	`https://ws.ups.com.tr/QueryPackageInfo/wsQueryPackagesInfo.asmx`

SOAP Methods Used

Operation	Service	SOAP Method	Purpose
Login	Create Shipment	`Login_Type1`	Get session ID for shipment service
Login	Package Query	`Login_V1`	Get session ID for tracking service
Create	Create Shipment	`CreateShipment_Type3`	Create shipment with dimensions
Track	Package Query	`GetTransactionsByTrackingNumber_V1`	Get all tracking events
Cancel	Create Shipment	`CancelShipment`	Cancel a shipment by tracking number
Get Rates	Create Shipment	`GetRate`	Get rate quotes by city/area codes

Session Management

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

Calls Login_Type1 (or Login_V1) to get a SessionID
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

tcgunel / omniship-ups

Maintainers

Package info

Statistics

Security