README

PTT Kargo web servisleri için resmi olmayan PHP kütüphanesi. kabulEkle2 (gönderi oluşturma), gonderiSorgu2 (takip), barkodVeriSil / referansVeriSil (veri silme) ve PttBilgi servislerini (il / ilçe / mahalle / ek hizmet) SOAP üzerinden kullanır.

Özellik	Metot
Gönderi oluşturma	`kabulEkle2`
Gönderi takibi	`gonderiSorgu2`, `shipmentInquiryEn`
Barkod ile veri silme	`barkodVeriSil`
Referans ile veri silme	`referansVeriSil`
İl / ilçe / mahalle listesi	`ilceSorgula`, `mahalleSorgula`
Ek hizmet listesi	`ekHizmetSorgula`
Barkod üretimi + check digit	yerel (`next_barcode`, `check_digit`)

Kurulum

composer require hasokeyk/ptt-cargo-php

Gereksinimler: PHP 8.0+, ext-curl, ext-simplexml, ext-libxml.

PTT'den alınan müşteri numarası (sayısal) ve şifre ile çalışır. Kargo göndermek için ayrıca PTT'nin verdiği barkod aralığı (örn. 123456789000X-123456789999X) gereklidir.

Kullanım

1. Gönderi Oluşturma (`kabulEkle2`)

<?php

require __DIR__ . '/vendor/autoload.php';

use Ptt\Ptt;

$ptt = new Ptt(
    '1234567890',                      // müşteri numarası
    'sifreniz',                        // şifre
    '123456789000X-123456789999X',     // PTT'nin verdiği barkod aralığı
    true                               // true = test ortamı, false = canlı
);

$result = $ptt->cargo()
    ->set_address('Örnek Mah. Atatürk Cad. No:1')
    ->set_fullname('Ad Soyad')
    ->set_city('ANKARA')
    ->set_district('ÇANKAYA')
    ->set_phone('5321234567')          // başında 0 olmadan, 10 hane
    ->set_email('ornek@example.com')
    ->set_weight(1500.0)               // gram
    ->set_reference_no('SIP-1001')
    ->set_description('Koli')
    ->send();

print_r($result);
/*
Array
(
    [hataKodu] => 1
    [aciklama] => BASARILI
    [barkod] => 1234567890002
    [dosyaAdi] => dosya20260806123456
    [dongu] => Array
        (
            [0] => Array
                (
                    [barkod] => 1234567890002
                    [donguHataKodu] => 1
                    [donguSonuc] => true
                    [donguAciklama] => https://pttws.ptt.gov.tr/...?barkod=...
                )
        )
)
*/

set_barcode() çağrılmazsa kütüphane aralıktan otomatik barkod üretir.
send() sonucundaki dosyaAdi, kaydı daha sonra silmek için saklanmalıdır.

2. Gönderi Takibi (`gonderiSorgu2`)

$ptt = new Ptt('1234567890', 'sifreniz', '', true); // takip için aralık gerekmez

$result = $ptt->track('1234567890002');
print_r($result);

İngilizce alan adları isterseniz track_en() kullanın.

Takip, kargo PTT'de fiziksel olarak kabul edildikten sonra veri döndürür. Test ortamında yalnızca veri yüklenen (kabul edilmeyen) gönderiler sonucKodu: -15 ("kayıt bulunamadı") döndürür.

3. Veri Silme (`barkodVeriSil` / `referansVeriSil`)

Sadece kabulü henüz yapılmamış (hatalı yüklenmiş) kayıtlar silinebilir. Silme için dosya adı zorunludur — send() sonucundaki dosyaAdi alanını kullanın.

// Barkod ile sil
$result = $ptt->delete_barcode('1234567890002', 'dosya20260806123456');

// Referans numarası ile sil (o referansa ait tüm kayıtlar)
$result = $ptt->delete_reference('SIP-1001', 'dosya20260806123456');

4. İl / İlçe / Mahalle / Ek Hizmet (`PttBilgi`)

Bilgi servisi müşteri bilgileriyle çalışır (dokümandaki pttUser/PttBilgi*2015 artık geçersizdir).

// Tüm iller: il_id => il_ad
$cities = $ptt->get_cities();

// Bir ilin ilçeleri: ilce_id => ilce_ad
$ankara = array_search('ANKARA', $cities, true); // 06
$districts = $ptt->get_districts($ankara);

// Ek hizmetler: ek_hizmet_id => ek_hizmet_ad (DK, OS, UA ...)
$services = $ptt->get_extra_services();

// Bir ilçenin mahalleleri: mahalleKod => mahalleAd
$neighborhoods = $ptt->get_neighborhoods($ankara, array_key_first($districts));

5. Barkod Üretimi ve Check Digit

// Sıradaki barkodu üret (13 hane, check digit dahil)
$barcode = $ptt->next_barcode();

// 12 haneli bir numaranın check digit'ini hesapla
$check = $ptt->check_digit('123456789000'); // örn. 2

Sınıf Referansı

Çalıştırılabilir örnekler için examples/ klasörüne, servis parametrelerinin tam açıklamaları için docs/ptt_cargo_webservice.md dosyasına bakın.

`Ptt`

Metot	Açıklama
`new Ptt($username, $password, $barcode_range = '', $test = true)`	İstemciyi oluşturur. `$test=false` canlı ortama gönderir.
`cargo(): Cargo`	Yeni gönderi builder'ı döndürür.
`track($barcode): array`	Gönderi durumunu sorgular (`gonderiSorgu2`).
`track_en($barcode): array`	Gönderi durumunu İngilizce alanlarla sorgular (`shipmentInquiryEn`).
`delete_barcode($barcode, $file_name = ''): array`	Barkod ile veri siler.
`delete_reference($reference_no, $file_name = ''): array`	Referans no ile veri siler.
`get_cities(): array`	İl listesi (`il_id => il_ad`).
`get_districts(?$il_id = null): array`	İlçe listesi (`ilce_id => ilce_ad`).
`get_neighborhoods($il_id, $ilce_id): array`	Mahalle listesi (`mahalleKod => mahalleAd`).
`get_extra_services(): array`	Ek hizmet listesi (`ek_hizmet_id => ek_hizmet_ad`).
`next_barcode(): string`	Aralıktan sıradaki barkodu üretir.
`check_digit($barcode12): string`	13. kontrol hanesini hesaplar.
`endpoint()` / `track_endpoint()` / `info_endpoint()`	Kullanılan servis adresleri.

`Cargo` (fluent setter'lar, hepsi zincirlenebilir)

Metot	Açıklama
`set_address(string)`	Alıcı adresi (zorunlu)
`set_fullname(string)`	Alıcı ad-soyad (zorunlu)
`set_barcode(string)`	13 haneli barkod (boşsa otomatik üretilir)
`set_phone(?string)`	Telefon, 0'sız 10 hane
`set_sms(?string)`	SMS numarası, 0'sız 10 hane
`set_email(?string)`	E-posta
`set_city(?string)`	İl adı
`set_district(?string)`	İlçe adı
`set_weight(float)`	Ağırlık (gram)
`set_description(?string)`	Gönderi adı / ürün
`set_reference_no(?string)`	Müşteri referans numarası
`set_extra_service(?string)`	Ek hizmet kodu(ları), örn. `DK`, `OS`, `DKOS`
`set_value_amount(?float)`	Değer konulmuş bedel (sigorta)
`set_cash_on_delivery(?float)`	Ödeme şartlı ücret (kapıda ödeme)
`set_payment_method(?string)`	Ödeme şekli: `MH` (masraflı), `N` (normal), `UA` (ücreti alıcıdan)
`set_file_name(?string)`	Dosya adı (varsayılan otomatik üretilir)
`send(): array`	Gönderiyi PTT'ye iletir

Test ve Canlı Ortam

Servis	Test	Canlı
Veri yükleme	`https://pttws.ptt.gov.tr/PttVeriYuklemeTest/services/Sorgu`	`https://pttws.ptt.gov.tr/PttVeriYukleme/services/Sorgu`
Gönderi takip	`https://pttws.ptt.gov.tr/GonderiTakipV2Test/services/Sorgu`	`https://pttws.ptt.gov.tr/GonderiTakipV2/services/Sorgu`
Bilgi (il/ilçe/ek hizmet)	– (test ortamı yok)	`https://pttws.ptt.gov.tr/PttBilgi/services/Sorgu`

Güvenlik Notları

Kimlik bilgilerini ve barkod aralığını asla sabit kod olarak yazmayın; .env, ortam değişkenleri veya gizli yapılandırma kullanın.
Silme işlemleri yalnızca kabul edilmemiş kayıtlar için geçerlidir; dikkatli kullanın.

Lisans

MIT

PTT Cargo PHP (English)

An unofficial PHP client library for PTT (Turkish Post) cargo web services. It uses SOAP to create shipments (kabulEkle2), track them (gonderiSorgu2), delete data (barkodVeriSil / referansVeriSil) and query reference data via the PttBilgi service (cities / districts / neighborhoods / extra services).

Feature	Method
Create shipment	`kabulEkle2`
Track shipment	`gonderiSorgu2`, `shipmentInquiryEn`
Delete data by barcode	`barkodVeriSil`
Delete data by reference	`referansVeriSil`
Cities / districts / neighborhoods	`ilceSorgula`, `mahalleSorgula`
Extra services	`ekHizmetSorgula`
Barcode generation + check digit	local (`next_barcode`, `check_digit`)

Installation

composer require hasokeyk/ptt-cargo-php

Requirements: PHP 8.0+, ext-curl, ext-simplexml, ext-libxml.

Works with the customer number (numeric) and password provided by PTT. To create shipments you also need the barcode range assigned by PTT (e.g. 123456789000X-123456789999X).

Usage

1. Create a Shipment (`kabulEkle2`)

<?php

require __DIR__ . '/vendor/autoload.php';

use Ptt\Ptt;

$ptt = new Ptt(
    '1234567890',                      // customer number
    'your-password',                   // password
    '123456789000X-123456789999X',     // barcode range assigned by PTT
    true                               // true = test environment, false = production
);

$result = $ptt->cargo()
    ->set_address('Example St. No:1')
    ->set_fullname('John Doe')
    ->set_city('ANKARA')
    ->set_district('CANKAYA')
    ->set_phone('5321234567')          // 10 digits, without leading 0
    ->set_email('john@example.com')
    ->set_weight(1500.0)               // grams
    ->set_reference_no('ORD-1001')
    ->set_description('Package')
    ->send();

print_r($result);
/*
Array
(
    [hataKodu] => 1
    [aciklama] => BASARILI
    [barkod] => 1234567890002
    [dosyaAdi] => dosya20260806123456
    [dongu] => Array
        (
            [0] => Array
                (
                    [barkod] => 1234567890002
                    [donguHataKodu] => 1
                    [donguSonuc] => true
                    [donguAciklama] => https://pttws.ptt.gov.tr/...?barkod=...
                )
        )
)
*/

If set_barcode() is not called, the library generates the next barcode from the range automatically.
Keep the dosyaAdi from the result if you may need to delete the record later.

2. Track a Shipment (`gonderiSorgu2`)

$ptt = new Ptt('1234567890', 'your-password', '', true); // no barcode range needed for tracking

$result = $ptt->track('1234567890002');
print_r($result);

Use track_en() for English field names (resultCode, barcodeNumber, ...).

Tracking returns data only after the shipment is physically accepted by PTT. Shipments that are only uploaded (not accepted) return sonucKodu: -15 ("record not found"), especially in the test environment.

3. Delete Data (`barkodVeriSil` / `referansVeriSil`)

Only records that have not yet been accepted (incorrectly uploaded) can be deleted. The file name is required — use the dosyaAdi from the send() result.

// Delete by barcode
$result = $ptt->delete_barcode('1234567890002', 'dosya20260806123456');

// Delete by reference number (all records of that reference)
$result = $ptt->delete_reference('ORD-1001', 'dosya20260806123456');

4. Cities / Districts / Neighborhoods / Extra Services (`PttBilgi`)

The info service works with your customer credentials (the pttUser/PttBilgi*2015 credentials in the old docs are no longer valid).

// All cities: il_id => il_ad
$cities = $ptt->get_cities();

// Districts of a city: ilce_id => ilce_ad
$ankara = array_search('ANKARA', $cities, true); // 06
$districts = $ptt->get_districts($ankara);

// Extra services: ek_hizmet_id => ek_hizmet_ad (DK, OS, UA ...)
$services = $ptt->get_extra_services();

// Neighborhoods of a district: mahalleKod => mahalleAd
$neighborhoods = $ptt->get_neighborhoods($ankara, array_key_first($districts));

5. Barcode Generation and Check Digit

// Next barcode from the range (13 digits, check digit included)
$barcode = $ptt->next_barcode();

// Calculate the check digit for a 12-digit number
$check = $ptt->check_digit('123456789000'); // e.g. 2

Class Reference

See the examples/ directory for runnable examples and docs/ptt_cargo_webservice.md for the full service parameter reference.

`Ptt`

Method	Description
`new Ptt($username, $password, $barcode_range = '', $test = true)`	Creates the client. `$test=false` targets the production environment.
`cargo(): Cargo`	Returns a new shipment builder.
`track($barcode): array`	Queries shipment status (`gonderiSorgu2`).
`track_en($barcode): array`	Queries shipment status with English fields (`shipmentInquiryEn`).
`delete_barcode($barcode, $file_name = ''): array`	Deletes data by barcode.
`delete_reference($reference_no, $file_name = ''): array`	Deletes data by reference number.
`get_cities(): array`	Cities (`il_id => il_ad`).
`get_districts(?$il_id = null): array`	Districts (`ilce_id => ilce_ad`).
`get_neighborhoods($il_id, $ilce_id): array`	Neighborhoods (`mahalleKod => mahalleAd`).
`get_extra_services(): array`	Extra services (`ek_hizmet_id => ek_hizmet_ad`).
`next_barcode(): string`	Generates the next barcode from the range.
`check_digit($barcode12): string`	Computes the 13th check digit.
`endpoint()` / `track_endpoint()` / `info_endpoint()`	Endpoints used by the client.

`Cargo` (fluent setters, all chainable)

Method	Description
`set_address(string)`	Recipient address (required)
`set_fullname(string)`	Recipient full name (required)
`set_barcode(string)`	13-digit barcode (auto-generated if omitted)
`set_phone(?string)`	Phone, 10 digits without leading 0
`set_sms(?string)`	SMS number, 10 digits without leading 0
`set_email(?string)`	Email
`set_city(?string)`	City name
`set_district(?string)`	District name
`set_weight(float)`	Weight (grams)
`set_description(?string)`	Shipment name / product
`set_reference_no(?string)`	Customer reference number
`set_extra_service(?string)`	Extra service code(s), e.g. `DK`, `OS`, `DKOS`
`set_value_amount(?float)`	Insured value
`set_cash_on_delivery(?float)`	Cash on delivery amount
`set_payment_method(?string)`	Payment method: `MH`, `N` or `UA` (collect)
`set_file_name(?string)`	File name (auto-generated by default)
`send(): array`	Sends the shipment to PTT

Test vs. Production Endpoints

Service	Test	Production
Data upload	`https://pttws.ptt.gov.tr/PttVeriYuklemeTest/services/Sorgu`	`https://pttws.ptt.gov.tr/PttVeriYukleme/services/Sorgu`
Tracking	`https://pttws.ptt.gov.tr/GonderiTakipV2Test/services/Sorgu`	`https://pttws.ptt.gov.tr/GonderiTakipV2/services/Sorgu`
Info (cities/districts/services)	– (no test env)	`https://pttws.ptt.gov.tr/PttBilgi/services/Sorgu`

Security Notes

Never hardcode credentials or barcode ranges; use .env, environment variables or a secure config.
Deletion only works for non-accepted records; use with care.

License

MIT

hasokeyk / ptt-cargo-php

Maintainers

Package info

Statistics

Security

README

Kurulum

Kullanım

1. Gönderi Oluşturma (`kabulEkle2`)

2. Gönderi Takibi (`gonderiSorgu2`)

3. Veri Silme (`barkodVeriSil` / `referansVeriSil`)

4. İl / İlçe / Mahalle / Ek Hizmet (`PttBilgi`)

5. Barkod Üretimi ve Check Digit

Sınıf Referansı

`Ptt`

`Cargo` (fluent setter'lar, hepsi zincirlenebilir)

Test ve Canlı Ortam

Güvenlik Notları

Lisans

PTT Cargo PHP (English)

Installation

Usage

1. Create a Shipment (`kabulEkle2`)

2. Track a Shipment (`gonderiSorgu2`)

3. Delete Data (`barkodVeriSil` / `referansVeriSil`)

4. Cities / Districts / Neighborhoods / Extra Services (`PttBilgi`)

5. Barcode Generation and Check Digit

Class Reference

`Ptt`

`Cargo` (fluent setters, all chainable)

Test vs. Production Endpoints

Security Notes

License

hasokeyk / ptt-cargo-php

Maintainers

Package info

Statistics

Security

README

Kurulum

Kullanım

1. Gönderi Oluşturma (kabulEkle2)

2. Gönderi Takibi (gonderiSorgu2)

3. Veri Silme (barkodVeriSil / referansVeriSil)

4. İl / İlçe / Mahalle / Ek Hizmet (PttBilgi)

5. Barkod Üretimi ve Check Digit

Sınıf Referansı

Ptt

Cargo (fluent setter'lar, hepsi zincirlenebilir)

Test ve Canlı Ortam

Güvenlik Notları

Lisans

PTT Cargo PHP (English)

Installation

Usage

1. Create a Shipment (kabulEkle2)

2. Track a Shipment (gonderiSorgu2)

3. Delete Data (barkodVeriSil / referansVeriSil)

4. Cities / Districts / Neighborhoods / Extra Services (PttBilgi)

5. Barcode Generation and Check Digit

Class Reference

Ptt

Cargo (fluent setters, all chainable)

Test vs. Production Endpoints

Security Notes

License

1. Gönderi Oluşturma (`kabulEkle2`)

2. Gönderi Takibi (`gonderiSorgu2`)

3. Veri Silme (`barkodVeriSil` / `referansVeriSil`)

4. İl / İlçe / Mahalle / Ek Hizmet (`PttBilgi`)

`Ptt`

`Cargo` (fluent setter'lar, hepsi zincirlenebilir)

1. Create a Shipment (`kabulEkle2`)

2. Track a Shipment (`gonderiSorgu2`)

3. Delete Data (`barkodVeriSil` / `referansVeriSil`)

4. Cities / Districts / Neighborhoods / Extra Services (`PttBilgi`)

`Ptt`

`Cargo` (fluent setters, all chainable)