Yurtiçi Gönderi Oluştur

Bu API, Türkiye içi kargo ve lojistik gönderileri oluşturmak için kullanılır. Gönderen ve alıcı adreslerinin her ikisi de Türkiye sınırları içinde olmalıdır.

Endpoint Bilgileri

Özellik Değer
URL {{BASE_URL}}/api/v1/consignments
HTTP Metodu POST
İçerik Türü application/json
Kimlik Doğrulama APIKEY header
Rate Limit 300 istek / 1 dakika (sliding window)

Rate Limit Aşımı: Limit aşıldığında API 429 Too Many Requests hatası döner. Detaylı bilgi için Rate Limit sayfasına bakın.

Idempotency: Bu endpoint tekrarlanan istek korumasını destekler. Detaylı bilgi için Idempotency sayfasına bakın.


Hızlı Başlangıç

Yurtiçi gönderi oluşturmak için aşağıdaki temel bilgilere ihtiyacınız vardır:

Gereksinim Açıklama
API Key Hesabınıza tanımlı API anahtarı
Provider Seçimi provider_id veya preference ile kargo firması belirleme
Gönderen Bilgileri Ad, adres, telefon (Türkiye adresi)
Alıcı Bilgileri Ad, adres, telefon (Türkiye adresi)
Paket Bilgileri Ağırlık, boyutlar, içerik değeri

Provider Seçimi Nasıl Yapılır?

Gönderi oluştururken kargo firmasını iki şekilde belirleyebilirsiniz:

Yöntem Ne Zaman Kullanılır? Örnek
provider_id Belirli bir kargo firması ile çalışmak istiyorsanız "provider_id": 1
preference Sistemin en uygun firmayı seçmesini istiyorsanız "preference": 1

Not: provider_id kullanıyorsanız preference değerini 0 olarak gönderin. Kullanılabilir provider listesi için Provider Listesi sayfasına bakın.

Minimal İstek Örneği

Aşağıda sadece zorunlu alanları içeren en basit gönderi oluşturma isteği bulunmaktadır:

{
    "provider_id": 1,
    "preference": 0,
    "consignor": {
        "name": "Gönderen Firma",
        "country": "TR",
        "state": "İstanbul",
        "city": "Şişli",
        "postal_code": "34381",
        "address": "Örnek Mahallesi, Örnek Sokak No:1",
        "phone_number": "+902121234567"
    },
    "consignee": {
        "name": "Alıcı Adı",
        "country": "TR",
        "state": "Ankara",
        "city": "Çankaya",
        "postal_code": "06690",
        "address": "Alıcı adresi",
        "phone_number": "+905551234567"
    },
    "packages": [
        {
            "package_type": 1,
            "post_type": 4,
            "quantity": 1,
            "weight": 1,
            "length": 20,
            "width": 15,
            "height": 10
        }
    ]
}

Not: post_type: 4 değeri "Satış" gönderisini ifade eder. Yurtiçi gönderilerde genellikle 4 (Satış) veya 5 (Bireysel) kullanılır. Tüm değerler için Gönderi Türleri sayfasına bakın.


Opsiyonel Header'lar

Etiket Formatı (X-Label-Format)

Gönderi oluşturulduğunda dönen kargo etiketinin formatını X-Label-Format header'ı ile belirleyebilirsiniz.

Header Değer Açıklama
X-Label-Format application/pdf Varsayılan. PDF formatında etiket döner
X-Label-Format application/zpl ZPL (Zebra Programming Language) formatında etiket döner. Termal yazıcılar için idealdir

ZPL Nedir? ZPL (Zebra Programming Language), Zebra marka termal etiket yazıcılarının anladığı bir dildir. Eğer termal yazıcı kullanıyorsanız, ZPL formatı doğrudan yazıcıya gönderilebilir ve çok daha hızlı yazdırma sağlar.

Örnek Header Kullanımı

curl -X POST "{{BASE_URL}}/api/v1/consignments" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}" \
  -H "X-Label-Format: application/zpl" \
  -d '{ ... }'

Not: Varsayılan çıktı formatı PDF'tir. Bu alan gönderilmezse veya desteklenmeyen bir format talep edilirse, sistem otomatik olarak PDF formatında çıktı üretir.


İstek Parametreleri

Temel Parametreler

Parametre Adı Parametre Tipi Zorunluluk Açıklama
preference Integer KOŞULLU Kargo sağlayıcı tercihi. provider_id belirtilmemişse zorunludur. Kullanılabilir Değerler
provider_id Integer KOŞULLU Kargo sağlayıcı ID'si. preference 0 ise veya belirtilmemişse zorunludur. Kullanılabilir Değerler
address_resolver_type Integer OPSİYONEL Adres çözümleme türü. Detaylı bilgi için aşağıya bakın
reference_no String (MAX 255) OPSİYONEL Referans numarası

Adres Çözümleme Türü (address_resolver_type)

Bu parametre, gönderilen adres bilgilerinin (il, ilçe) nasıl işleneceğini belirler. Özellikle farklı kaynaklardan gelen adres verilerinin standartlaştırılması için kritik öneme sahiptir.

Değer Sabit Adı Açıklama
0 NONE Varsayılan. Sistem veritabanında il/ilçe eşleştirmesi yapar. Gönderilen state ve city değerleri sistemdeki kayıtlarla eşleştirilir. Eşleşme bulunamazsa hata döner.
1 RESOLVE_FROM_POSTAL_CODE Posta kodundan il/ilçe bilgisi çözümlenir. Gönderilen state ve city değerleri yok sayılır, sadece postal_code kullanılarak adres belirlenir.
2 RESOLVE_FROM_POSTAL_CODE_IF_NOT_FOUND Önce sistem veritabanında eşleştirme denenir. Eşleşme bulunamazsa posta kodundan çözümleme yapılır. En esnek seçenektir.

Ne Zaman Hangi Değeri Kullanmalıyım?

Senaryo Önerilen Değer
Adres bilgilerim sistemdeki il/ilçe isimleriyle birebir eşleşiyor 0 (NONE)
Sadece posta kodum var veya posta kodum kesinlikle doğru 1 (RESOLVE_FROM_POSTAL_CODE)
Adres bilgilerim farklı kaynaklardan geliyor, bazıları eşleşmeyebilir 2 (RESOLVE_FROM_POSTAL_CODE_IF_NOT_FOUND)

Örnek Senaryolar

Senaryo 1: E-ticaret entegrasyonu (Önerilen: 2)

{
    "address_resolver_type": 2,
    "consignee": {
        "state": "istanbul",      // küçük harf, sistem "İstanbul" olarak düzeltir
        "city": "kadikoy",        // küçük harf, sistem "Kadıköy" olarak düzeltir
        "postal_code": "34710"    // Eşleşme olmazsa bu kullanılır
    }
}

Senaryo 2: Posta kodu bazlı (Önerilen: 1)

{
    "address_resolver_type": 1,
    "consignee": {
        "state": "herhangi",      // yok sayılır
        "city": "herhangi",       // yok sayılır
        "postal_code": "34710"    // sadece bu kullanılır
    }
}

Diğer Temel Parametreler

Parametre Adı Parametre Tipi Zorunluluk Açıklama
invoice_number String (MAX 255) OPSİYONEL Fatura numarası
specific_shipping_method String (MAX 255) OPSİYONEL Sağlayıcı gönderim metodu. Kullanılabilir Değerler
generate_provider_barcode Bool OPSİYONEL Sıralı barkod aralığı kullanan sağlayıcılarda geçerlidir. true ise sistem otomatik barkod atar. Varsayılan: false
specific_provider_barcode String (MAX 255) OPSİYONEL Sıralı barkod aralığı kullanan sağlayıcılarda özel barkod tanımlamak için kullanılır
is_pickup_requested Bool OPSİYONEL Kurye çağırma talebi. true ise gönderi için otomatik kurye talebi oluşturulur. Varsayılan: false

Gönderen Bilgileri

Parametre Adı Parametre Tipi Zorunluluk Açıklama
consignor.name String (MAX 255) ZORUNLU Gönderen adı
consignor.attention_name String (MAX 255) OPSİYONEL Gönderici diğer ad
consignor.country String (2-3 KARAKTER) ZORUNLU Ülke kodu (ISO2 veya ISO3 formatında)
consignor.state String (MAX 100) ZORUNLU İl/Eyalet
consignor.city String (MAX 100) ZORUNLU İlçe
consignor.postal_code String (MAX 30) OPSİYONEL Posta kodu
consignor.address String (MAX 1000) ZORUNLU Tam adres
consignor.phone_number String (MAX 20) OPSİYONEL Telefon numarası
consignor.email String (MAX 255) OPSİYONEL E-posta adresi

Alıcı Bilgileri

Parametre Adı Parametre Tipi Zorunluluk Açıklama
consignee.name String (MAX 255) ZORUNLU Alıcı adı
consignee.attention_name String (MAX 255) OPSİYONEL Alıcı diğer ad
consignee.country String (2-3 KARAKTER) ZORUNLU Ülke kodu (ISO2 veya ISO3 formatında)
consignee.state String (MAX 100) ZORUNLU İl/Eyalet
consignee.city String (MAX 100) ZORUNLU İlçe
consignee.postal_code String (MAX 30) OPSİYONEL Posta kodu
consignee.address String (MAX 1000) ZORUNLU Tam adres
consignee.phone_number String (MAX 20) OPSİYONEL Telefon numarası
consignee.email String (MAX 255) OPSİYONEL E-posta adresi

Paket Bilgileri

Parametre Adı Parametre Tipi Zorunluluk Açıklama
packages.package_type Integer ZORUNLU Paket türü Kullanılabilir Değerler
packages.provider_packaging_type String OPSİYONEL Sağlayıcı Özel Paketleme türü (örn: FEDEX_BOX). Kullanılabilir Değerler
packages.post_type Integer OPSİYONEL Gönderi türü. Yurtiçi gönderilerde opsiyonel, yurtdışı gönderilerde zorunludur. Kullanılabilir Değerler
packages.weight Float ZORUNLU Paket ağırlığı (kg)
packages.length Float ZORUNLU Paket uzunluğu (cm)
packages.width Float ZORUNLU Paket genişliği (cm)
packages.height Float ZORUNLU Paket yüksekliği (cm)

Paket İçerik Bilgileri (Opsiyonel)

Yurtiçi gönderilerde packages.items dizisi tamamen opsiyoneldir. Gönderilmezse sistem varsayılan değerler kullanır.

Parametre Adı Parametre Tipi Zorunluluk Açıklama
packages.items.unit_price Float OPSİYONEL Birim fiyat
packages.items.quantity Integer OPSİYONEL Miktar
packages.items.description String (MAX 255) OPSİYONEL Ürün açıklaması
packages.items.category String (MAX 255) OPSİYONEL Kategori
packages.items.origin String (2-3 KARAKTER) OPSİYONEL Menşei ülke
packages.items.currency_code String (3 KARAKTER) OPSİYONEL Para birimi kodu (varsayılan: TRY)

Döküman Bilgileri (Opsiyonel)

Bu alan tamamen opsiyonel olup, gönderiniz döküman içermeyecek ise kullanılmamalıdır.

Gönderimden önce Döküman Yüklemesi gerekmektedir , Bu işlem için şu dökümanı inceleyiniz: Gönderi Döküman Yükleme API.

Not: Sadece bazı providerlar Dijital Döküman Gönderimini desteklemektedir. Provider ve Kullanılabilir Döküman gönderimi bilgisi için iletişime geçiniz.

Parametre Adı Parametre Tipi Zorunluluk Açıklama
documents.id Integer ZORUNLU Daha önce yüklenmiş döküman ID’si

Döküman Bilgisi Örnek Veri

{
  //diğer gönderi parametreleri...
  "documents": [
    {
      "id": 4617
    }
  ]
  //diğer gönderi parametreleri...
}

Ek Hizmet Bilgileri (Opsiyonel)

Bu alan tamamen opsiyonel olup, gönderiniz Ek Hizmet içermiyor ise kullanılmamalıdır.

Sistemde yer alan Ek Hizmet Tiplerine ve Detay parametreleri hakkında daha fazla bilgi için şu dökümanı mutlaka inceleyiniz Ek Hizmetler

Not: Sadece bazı Providerlar Ek Hizmetleri desteklemektedir. Provider ve Kullanılabilir Ek hizmet bilgisi için iletişime geçiniz.

Parametre Adı Parametre Tipi Zorunluluk Açıklama
special_services.service_type String ZORUNLU Hizmet tipi (örn. CASH_ON_DELIVERY, HOLD_AT_DEPARTMENT)
special_services.details.$dinamik Dinamik KOŞULLU Her hizmet tipi için dinamik parametreler olabilmektedir. Detaylı bilgi için Ek Hizmetler

Ek Hizmet Bilgisi Örnek Veri

{
    //diğer gönderi parametreleri...
    "special_services": [
        {
            "service_type": "CASH_ON_DELIVERY",
            "details": {
                "method": "CASH",
                "amount": 134.52,
                "accountNumber": "12312312"
            }
        },
        {
            "service_type": "HOLD_AT_DEPARTMENT"
        }
    ],
    //diğer gönderi parametreleri...
}

Örnek Kullanım

Tam İstek Örneği (Tüm Diller)

Aşağıda farklı programlama dilleri için tam kapsamlı API istek örnekleri bulunmaktadır.

curl -X POST "{{BASE_URL}}/api/v1/consignments" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}" \
  -d '{
    "provider_id": 1,
    "preference": 0,
    "reference_no": "SIP-20241217-084523",
    "consignor": {
        "name": "Teknoloji Mağazası A.Ş.",
        "country": "TR",
        "state": "İstanbul",
        "city": "Şişli",
        "postal_code": "34381",
        "address": "Büyükdere Caddesi No:185 Kanyon AVM Kat:2",
        "phone_number": "+902123456789"
    },
    "consignee": {
        "name": "Elif Kaya",
        "country": "TR",
        "state": "İzmir",
        "city": "Karşıyaka",
        "postal_code": "35540",
        "address": "Cemal Gürsel Caddesi No:42 Daire:5 Bostanlı Mahallesi",
        "phone_number": "+905359876543"
    },
    "packages": [
        {
            "package_type": 1,
            "post_type": 4,
            "quantity": 1,
            "weight": 0.85,
            "length": 25,
            "width": 20,
            "height": 10,
            "items": [
                {
                    "unit_price": 2499.99,
                    "quantity": 1
                }
            ]
        }
    ]
}'

API Cevabı

Başarılı bir istekte, API aşağıdaki gibi bir yanıt döndürecektir:

{
    "status": true,
    "message": "Consignment created successfully",
    "data": {
        "consignment": 632280,
        "barcode": "XYZ123",
        "c2hBarcode": "C2H07238640094",
        "providerTrackingCode": "XYZ123",
        "trackingUrl": "https://<provider_domain>/<tracking_url>",
        "contentType": "application/pdf",
        "base64label": "...base64data",
        "detail": {
            "total_cost": 120.96,
            "currency_code": "TRY",
            "currency_rate": 1,
            "reference_no": "XYZ123",
            "packages": {
                "desi": 1.13,
                "weight": 5.4,
                "quantity": 1
            }
        }
    }
}

Response Alanları

Alan Tip Açıklama
status Boolean İşlem başarı durumu
message String İşlem sonuç mesajı
data.consignment Integer Oluşturulan gönderi ID'si
data.barcode String Kargo firması tarafından atanan barkod
data.c2hBarcode String ComToHome sistem barkodu (takip için kullanılır)
data.providerTrackingCode String Kargo firması takip kodu
data.trackingUrl String Kargo takip sayfası URL'i
data.contentType String Etiket dosya formatı (örn: application/pdf)
data.base64label String Base64 encoded kargo etiketi (PDF)
data.detail.total_cost Float Toplam kargo ücreti
data.detail.currency_code String Para birimi
data.detail.packages.desi Float Hesaplanan desi değeri
data.detail.packages.weight Float Toplam ağırlık (kg)
data.detail.packages.quantity Integer Toplam paket adedi

Etiket Yazdırma: base64label alanındaki veriyi decode ederek PDF dosyası olarak kaydedebilir veya direkt yazıcıya gönderebilirsiniz.


Hata Cevapları

API isteği başarısız olursa, API aşağıdaki gibi bir hata yanıtı döndürecektir:

{
    "status": false,
    "errors": [
        {
            "message": "SIP-20241217-084523 Referans numarası kullanılmaktadır.",
            "field": "reference_no"
        },
        {
            "message": "Bu değer boş bırakılmamalıdır.",
            "field": "consignee.name"
        }
    ]
}

Ek Hizmet Hata Örneği

Eğer provider istenen ek hizmeti desteklemiyorsa:

{
    "status": false,
    "errors": [
        {
            "message": "Kargo sağlayıcısı bu özel servisi desteklememektedir: [CASH_ON_DELIVERY]",
            "field": "specialServices[0].serviceType"
        },
        {
            "message": "Kargo sağlayıcısı bu özel servisi desteklememektedir: [VALUED_SHIPMENT]",
            "field": "specialServices[1].serviceType"
        }
    ]
}

Yaygın Hata Senaryoları

Hata Mesajı Field Açıklama Çözüm
[referenceNo] Referans numarası kullanılmaktadır. reference_no Aynı referans numarası daha önce kullanılmış Benzersiz bir referans numarası kullanın
[customerId] ID'li müşteri için [providerId] ID'li kargo sağlayıcısı tanımlanmamıştır. provider_id Geçersiz veya müşteriye tanımlı olmayan provider Provider Listesi'nden geçerli bir ID alın
Bu değer boş bırakılmamalıdır. consignor.name, consignee.address vb. Zorunlu alan boş bırakılmış İlgili alanı doldurun
Bu alan, eksiktir İlgili alan Zorunlu alan request'te yok İlgili alanı ekleyin
Doküman ID'leri geçersizdir: [document_ids] documents Geçersiz döküman ID'si Önce döküman yükleyip geçerli ID alın
Kargo sağlayıcısı bu özel servisi desteklememektedir: [service_name] special_services Provider bu ek hizmeti desteklemiyor Desteklenen ek hizmetleri kontrol edin

Sonraki Adımlar

Gönderi başarıyla oluşturulduktan sonra:

  1. Etiket Yazdırma: base64label alanını decode ederek etiketi yazdırın
  2. Takip: trackingUrl veya c2hBarcode ile gönderiyi takip edin
  3. Webhook: Gönderi durumu değişikliklerini otomatik almak için Webhook kurulumu yapın