PHPackages                             tcgunel/omniship-surat - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. tcgunel/omniship-surat

ActiveLibrary[API Development](/categories/api)

tcgunel/omniship-surat
======================

Sürat Kargo carrier for Omniship

v0.0.2(1w ago)03↓100%MITPHPPHP ^8.2

Since Mar 12Pushed 1w agoCompare

[ Source](https://github.com/tcgunel/omniship-surat)[ Packagist](https://packagist.org/packages/tcgunel/omniship-surat)[ RSS](/packages/tcgunel-omniship-surat/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (5)Versions (3)Used By (0)

Omniship Surat Kargo
====================

[](#omniship-surat-kargo)

Surat Kargo carrier driver for the [Omniship](https://github.com/tcgunel/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
------------

[](#installation)

```
composer require tcgunel/omniship-surat
```

Usage
-----

[](#usage)

### Initialize

[](#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](https://ekargo.suratkargo.com.tr).

### Create Shipment

[](#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)

[](#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

[](#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

[](#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
-------------

[](#api-endpoints)

EnvironmentURLProduction`https://webservices.suratkargo.com.tr/services.asmx`Test`https://prova.suratkargo.com.tr/services.asmx`### Legacy Endpoints (from PDF docs, for reference)

[](#legacy-endpoints-from-pdf-docs-for-reference)

ServiceURLGonderi (Prod)`http://www.suratkargo.com.tr/GonderiWebServiceGercek/service.asmx`Gonderi (Test)`http://www.suratkargo.com.tr/GonderiWebServiceProva/service.asmx`Takip (Prod)`http://webservices.suratkargo.com.tr/services.asmx`Takip (Test)`https://esatis.suratkargo.com.tr/services.asmx`Credentials
-----------

[](#credentials)

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

CredentialFieldUsed ForSet ByCari Kodu`kullaniciAdi` / `cariKodu`All operationsSurat Kargo (10-digit)Cari Sifresi`sifre`Shipment creation, cancelSurat KargoWeb Servis Sifresi`webSifre`Tracking, reportingCustomer (at ekargo portal)### Test Credentials

[](#test-credentials)

FieldValueCari Kodu`1038106246`Cari Sifresi`123456`Web Servis Sifresi`123456.Ff`COD Cari Kodu`1038106247`COD Cari Sifresi`1234567`Test Tracking Codes`123456789`, `12v34567g89`SOAP Methods Used
-----------------

[](#soap-methods-used)

OperationSOAP MethodDescriptionCreate Shipment`GonderiyiKargoyaGonderYeniSiparisBarkodOlustur`Returns structured response with barcodeTrack Shipment`KargoTakipHareketDetayliV2`Detailed tracking by WebSiparisKoduCancel Shipment`GonderiGeriCek`Cancel with reason (IptalNeden)### Alternative Methods Available

[](#alternative-methods-available)

MethodDescription`GonderiyiKargoyaGonder`Legacy create (returns "Tamam" string, no barcode)`GonderiyiKargoyaGonderYeni`Newer create (returns string, no barcode)`WebSiparisKodu`Track by order code (returns DataSet)`TakipNo`Track by Surat's barcode number (returns DataSet)`GonderiSil`Delete shipment (different auth: cariKodu + WebPassword)`WebSiparisKodundanKargoTeslimatBilgisi`Delivery info (returns TeslimatBilgisiSonuc)Gonderi Fields
--------------

[](#gonderi-fields)

FieldTypeRequiredDescriptionKisiKurumstringYesRecipient nameAliciAdresistringYesFull address (single field)IlstringYesCity/ProvinceIlcestringYesDistrictTelefonCepstringConditionalMobile phone (required if SMS service)KargoTuruintYes1=Dosya, 2=Mi, 3=KoliOdemeTipiintYes1=Pesin (sender), 2=Ucret Alici (receiver)AdetintYesPackage countOzelKargoTakipNostringNoYour custom tracking codeBirimDesistringNoVolumetric weight per unitBirimKgstringNoWeight per unitKapidanOdemeTahsilatTipiintIf COD1=Nakit, 2=POSKapidanOdemeTutaristringIf CODCOD amountIrsaliyeSeriNostringIf CODInvoice serial numberIrsaliyeSiraNostringIf CODInvoice sequence numberTeslimSekliintNo1=Address delivery, 2=Branch pickupNotes
-----

[](#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
-------

[](#testing)

```
vendor/bin/pest
```

License
-------

[](#license)

MIT

###  Health Score

38

—

LowBetter than 86% of packages

Maintenance98

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity37

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

10d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/36dffe883e88aeef07c26067af3d6a7eda1c2a81f1ae45fdd430b721665131da?d=identicon)[Mobius Studio](/maintainers/Mobius%20Studio)

---

Top Contributors

[![tcgunel](https://avatars.githubusercontent.com/u/3923425?v=4)](https://github.com/tcgunel "tcgunel (2 commits)")

###  Code Quality

TestsPest

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tcgunel-omniship-surat/health.svg)

```
[![Health](https://phpackages.com/badges/tcgunel-omniship-surat/health.svg)](https://phpackages.com/packages/tcgunel-omniship-surat)
```

###  Alternatives

[google/apiclient

Client library for Google APIs

9.8k186.9M887](/packages/google-apiclient)[stripe/stripe-php

Stripe PHP Library

4.0k139.3M414](/packages/stripe-stripe-php)[webonyx/graphql-php

A PHP port of GraphQL reference implementation

4.7k75.4M276](/packages/webonyx-graphql-php)[twilio/sdk

A PHP wrapper for Twilio's API

1.6k90.6M251](/packages/twilio-sdk)[friendsofsymfony/jsrouting-bundle

A pretty nice way to expose your Symfony routing to client applications.

1.5k52.7M206](/packages/friendsofsymfony-jsrouting-bundle)[knplabs/github-api

GitHub API v3 client

2.2k15.3M171](/packages/knplabs-github-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
