Skip to content

README.md

Latest commit

 

History

History
395 lines (301 loc) · 14.9 KB

README.md

File metadata and controls

395 lines (301 loc) · 14.9 KB
Raw

PTT Kargo PHP

PHP Version License

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)

PHP Version License

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