PHPackages                             emirhangungormez/suratkargoapi - 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. emirhangungormez/suratkargoapi

ActiveLibrary

emirhangungormez/suratkargoapi
==============================

A zero-dependency, cURL-based PHP SDK for the Sürat Kargo Web Service (SOAP API) designed for humans and AI coding assistants.

00PHP

Since Aug 9Pushed todayCompare

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

READMEChangelogDependenciesVersions (1)Used By (0)

Sürat Kargo Web Service SOAP API SDK
====================================

[](#sürat-kargo-web-service-soap-api-sdk)

[![PHP Version](https://camo.githubusercontent.com/905c670b6e3bc20026bddbc8923df4d38111e526b88f1252ac4ceb6643299d96/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344253230382e302d3838393242462e737667)](https://php.net)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](LICENSE)[![Zero Dependencies](https://camo.githubusercontent.com/f8a8828518e1a83fe1a2ee9be91c94e14e443da880294f80f3dfd3a58d24407c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646570656e64656e636965732d7a65726f2d626c75652e737667)](#)

Türkiye'nin en popüler kargo şirketlerinden **Sürat Kargo**'nun resmî bir PHP SDK'sı veya düzgün bir entegrasyon kılavuzu internette bulunmamaktadır.

Bu kütüphane, Sürat Kargo SOAP Web Servisi (`https://webservices.suratkargo.com.tr/services.asmx?WSDL`) üzerinde işlem yapmayı sağlayan, **sıfır bağımlılığa (zero-dependency)** sahip, PHP native `ext-soap` eklentisine dahi ihtiyaç duymadan **cURL XML SOAP** protokolünü kullanan son derece esnek bir PHP SDK'sıdır.

Hem **insan yazılımcılar** hem de **AI kodlama asistanları** (Gemini, Claude, Cursor, Copilot vb.) için en ideal entegrasyon yapısını sunar.

---

🚀 Önemli Özellikler
-------------------

[](#-önemli-özellikler)

1. **Bağımsız SOAP Motoru:** `ext-soap` eklentisi yüklü olmayan sunucularda da cURL ve SimpleXML ile doğrudan XML mesajları oluşturarak çalışır.
2. **Dayanıklı Gönderi Cascade Akışı:** Sürat Kargo API yetkilerinizin türüne göre gönderiyi önce barkodlu oluşturmayı dener (`GonderiyiKargoyaGonderYeniSiparisBarkodOlustur`), yetki yoksa ortak barkodlu oluşturur (`OrtakBarkodOlustur`), o da olmazsa ham gönderi olarak kaydeder (`GonderiyiKargoyaGonderYeni`). Entegrasyonunuz asla yarıda kesilmez.
3. **Akıllı Telefon Normalizasyonu:** Telefon numaralarını otomatik olarak temizler ve Sürat Kargo API'sinin beklediği 10 haneli (`5XXXXXXXXX`) formata getirir.
4. **E-Ticaret Durum Çözümleyici:** Sürat Kargo'dan dönen Türkçe durum ibarelerini (`dağıtıma çıkarıldı`, `teslim edildi`, `aktarma şubesinde` vb.) standart e-ticaret durumlarına (`out_for_delivery`, `delivered`, `transfer` vb.) çevirir.

---

⚠️ En Büyük Entegrasyon Tuzağı: Kimlik Bilgileri (Credentials)
--------------------------------------------------------------

[](#️-en-büyük-entegrasyon-tuzağı-kimlik-bilgileri-credentials)

Sürat Kargo entegrasyonu yapan geliştiricilerin karşılaştığı **en büyük hata**, tüm API fonksiyonlarında tek bir kullanıcı adı ve şifre kullanmaya çalışmalarıdır. Sürat Kargo sisteminde **iki ayrı yetkilendirme katmanı** vardır:

Parametre Adı (SDK)SOAP KarşılığıKullanım AlanıAçıklama**`shipping_username`**`KullaniciAdi`**Gönderi Oluşturma & İptal**Kargo göndermek, sipariş oluşturmak ve geri çekmek için kullanılan kargo şubesi tanımlı API kullanıcı adı.**`shipping_password`**`Sifre`**Gönderi Oluşturma & İptal**Gönderi API kullanıcısına ait şifre.**`customer_code`**`cariKodu` / `GonderenCariKodu`**Sorgulama & Barkod & İptal**Kargo hareketlerini takip etmek, geçmiş listelemek ve barkod etiketi indirmek için kullanılan Cari Kodu (Müşteri Numarası).**`web_password`**`WebPassword` / `Sifre`**Sorgulama & Barkod & İptal**Cari hesabınıza bağlı olan web entegrasyon paneli şifresi.Important

Gönderi oluştururken `shipping_username`/`shipping_password`; sorgulama, takip ve barkod çekerken ise `customer_code`/`web_password` kullanılmalıdır. Bu SDK, bu ayrımları arka planda otomatik olarak yönetir.

---

⚙️ Kurulum
----------

[](#️-kurulum)

Kütüphaneyi projenize Composer kullanarak dahil edebilirsiniz:

```
composer require emirhangungormez/suratkargoapi
```

---

📖 Temel Kullanım
----------------

[](#-temel-kullanım)

### 1. Kargo Gönderisi Oluşturma (Shipment Creation)

[](#1-kargo-gönderisi-oluşturma-shipment-creation)

Aşağıdaki örnekte en dayanıklı şekilde kargo siparişi oluşturma işlemi gösterilmektedir. SDK, kargo kaydını oluştururken API yetkilerinize bağlı olarak en uygun SOAP metodunu sırayla (cascade) dener.

```