README

Surat Kargo carrier driver for the Omniship shipping library.

Uses the unified SOAP API at webservices.suratkargo.com.tr/services.asmx with the newer GonderiyiKargoyaGonderYeniSiparisBarkodOlustur method that returns structured responses with barcode.

Installation

composer require tcgunel/omniship-surat

Usage

Initialize

use Omniship\Omniship;

$carrier = Omniship::create('Surat');
$carrier->initialize([
    'kullaniciAdi' => '1038106246',    // 10-digit Cari Kodu
    'sifre' => '123456',               // Cari Sifre (for shipment creation & cancel)
    'cariKodu' => '1038106246',        // Same Cari Kodu (for tracking)
    'webSifre' => '123456.Ff',         // Web Servis Sifresi (for tracking queries)
    'testMode' => true,
]);

Note: Surat Kargo uses separate passwords for shipment operations (sifre) and tracking queries (webSifre). The web service password is customer-defined at ekargo.suratkargo.com.tr.

Create Shipment

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

$response = $carrier->createShipment([
    'shipTo' => new Address(
        name: 'Mehmet Demir',
        street1: 'Ataturk Cad. No:42',
        city: 'Ankara',
        district: 'Cankaya',
        phone: '05559876543',
        email: 'mehmet@example.com',
    ),
    'packages' => [
        new Package(weight: 2.5, desi: 3),
    ],
    'trackingNumber' => 'SIPARIS-001',     // OzelKargoTakipNo (your custom tracking code)
    'referenceNumber' => 'REF-001',        // Optional: group shipments
    'paymentType' => PaymentType::SENDER,  // SENDER (1=Pesin) or RECEIVER (2=Ucret Alici)
    'cargoType' => 3,                      // 1=Dosya, 2=Mi, 3=Koli
    'cargoContent' => 'Elektronik urun',   // Optional
])->send();

if ($response->isSuccessful()) {
    echo $response->getBarcode();        // 14-digit barcode from Surat
    echo $response->getTrackingNumber(); // OzelKargoTakipNo you provided
} else {
    echo $response->getMessage();        // Error description
}

Cash on Delivery (Kapida Odeme)

$response = $carrier->createShipment([
    'shipTo' => new Address(/* ... */),
    'packages' => [new Package(weight: 1.0)],
    'trackingNumber' => 'COD-001',
    'cashOnDelivery' => true,
    'codAmount' => 150.50,               // KapidanOdemeTutari
    // KapidanOdemeTahsilatTipi: 1=Nakit, 2=POS
])->send();

Track Shipment

$response = $carrier->getTrackingStatus([
    'trackingNumber' => 'SIPARIS-001',   // OzelKargoTakipNo or WebSiparisKodu
])->send();

if ($response->isSuccessful()) {
    $info = $response->getTrackingInfo();
    echo $info->trackingNumber;
    echo $info->status->value;           // DELIVERED, IN_TRANSIT, etc.

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

Cancel Shipment

$response = $carrier->cancelShipment([
    'trackingNumber' => 'SIPARIS-001',   // OzelKargoTakipNo
    'cancelReason' => 'Musteri istegi',  // Required: IptalNeden
])->send();

if ($response->isSuccessful() && $response->isCancelled()) {
    echo 'Shipment cancelled';
}

API Endpoints

Legacy Endpoints (from PDF docs, for reference)

Credentials

Surat Kargo uses three credentials (unlike most Turkish carriers):

Test Credentials

SOAP Methods Used

Alternative Methods Available

Gonderi Fields

Notes

• The unified service at webservices.suratkargo.com.tr contains both shipment creation and tracking methods. Legacy separate endpoints may return 404.
• OzelKargoTakipNo (custom tracking number) set during creation becomes the WebSiparisKodu used for tracking queries.
• TakipNo in tracking responses is Surat Kargo's internal barcode number (14 digits).
• Address is a single field (AliciAdresi), not structured. Il (city) and Ilce (district) are separate required fields.
• Cancel requires IptalNeden (cancellation reason) — it is mandatory.
• The EkHizmetler field accepts comma-separated service names: GondericiyeSms, TelefonIhbar, AliciyaSms, AdrestenAlim.

Testing

vendor/bin/pest

License

MIT