Çoklu Paket Gönderi Oluştur

Bu API, bir sevkiyatın birden fazla paket içerdiği gönderileri oluşturmak için kullanılır. Örneğin, bir siparişin birden fazla koliye bölündüğü durumlarda bu endpoint kullanılmalıdır.

Ne Zaman Kullanılmalı?

Senaryo Endpoint
Tek paket gönderisi /api/v1/consignments
2 veya daha fazla paket /api/v1/consignments/multi-package

Örnek Senaryo: Bir müşteri 3 adet büyük ürün sipariş etti ve her biri ayrı koliye konuldu. Bu durumda 3 paketli tek bir sevkiyat (consignment) oluşturulur.


Endpoint Bilgileri

Özellik Değer
URL {{BASE_URL}}/api/v1/consignments/multi-package
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.


Tekli Paket ile Farkları

Özellik Tekli Paket Çoklu Paket
Endpoint /api/v1/consignments /api/v1/consignments/multi-package
packages dizisi 1 eleman Minimum 2 eleman
package_type Her paket farklı olabilir Tüm paketler aynı olmalı
specific_provider_barcode Gönderi seviyesinde Paket seviyesinde (her pakete ayrı)

Önemli Kurallar

1. Paket Türü Kuralı

Tüm paketlerin package_type değeri aynı olmalıdır. Farklı package_type değerleri gönderilirse hata alırsınız.

2. Özel Barkod Kuralı (specific_provider_barcode)

Çoklu paket gönderisinde özel barkod kullanımı paket seviyesinde yapılır. Aşağıdaki kurallara dikkat edilmelidir:

Durum Geçerli mi? Açıklama
Tüm paketlere barkod verildi ✅ Geçerli Her pakete benzersiz barkod atandı
Hiçbir pakete barkod verilmedi ✅ Geçerli Sistem otomatik barkod atar
Bazı paketlere barkod verildi ❌ Hata Ya hepsine verin ya da hiçbirine

Kural: specific_provider_barcode kullanılacaksa tüm paketlere benzersiz barkod verilmelidir. Kısmi kullanım (bazı paketlere barkod verip bazılarına vermemek) kabul edilmez.


Hızlı Başlangıç

Minimal İstek Örneği

Aşağıda 2 paketli bir gönderi oluşturma örneğ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,
            "weight": 2.5,
            "length": 40,
            "width": 30,
            "height": 20
        },
        {
            "package_type": 1,
            "post_type": 4,
            "weight": 3.2,
            "length": 50,
            "width": 35,
            "height": 25
        }
    ]
}

Özel Barkodlu İstek Örneği

Her pakete özel barkod atamak için:

{
    "provider_id": 1,
    "preference": 0,
    "consignor": { ... },
    "consignee": { ... },
    "packages": [
        {
            "package_type": 1,
            "post_type": 4,
            "weight": 2.5,
            "length": 40,
            "width": 30,
            "height": 20,
            "specific_provider_barcode": "PKG-001-A"
        },
        {
            "package_type": 1,
            "post_type": 4,
            "weight": 3.2,
            "length": 50,
            "width": 35,
            "height": 25,
            "specific_provider_barcode": "PKG-001-B"
        }
    ]
}

Not: packages dizisinde en az 2 paket bulunmalıdır. Tek paket için Yurtiçi Gönderi Oluştur veya Yurtdışı Gönderi Oluştur endpoint'lerini kullanın.


Opsiyonel Header'lar

Etiket Formatı (X-Label-Format)

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

İ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 zorunludur. Kullanılabilir Değerler
address_resolver_type Integer OPSİYONEL Adres çözümleme türü. Kullanılabilir Değerler
reference_no String (MAX 255) OPSİYONEL Referans numarası
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 Otomatik barkod oluşturma. Varsayılan: false
is_pickup_requested Bool OPSİYONEL Kurye çağırma talebi. Varsayılan: false

Gönderen Bilgileri (consignor)

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)
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 (consignee)

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)
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 (packages)

Önemli Kurallar:

  • packages dizisi en az 2 eleman içermelidir
  • Tüm paketlerin package_type değeri aynı olmalıdır
  • specific_provider_barcode kullanılacaksa tüm paketlere verilmelidir
Parametre Adı Parametre Tipi Zorunluluk Açıklama
packages[].package_type Integer ZORUNLU Paket türü (tüm paketlerde aynı olmalı). Kullanılabilir Değerler
packages[].provider_packaging_type String OPSİYONEL Sağlayıcı özel paketleme türü. Kullanılabilir Değerler
packages[].post_type Integer OPSİYONEL Gönderi türü. 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)
packages[].specific_provider_barcode String (MAX 255) OPSİYONEL Pakete özel barkod. Kullanılacaksa tüm paketlere verilmeli

Paket İçerik Bilgileri (packages[].items) - Opsiyonel

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 (varsayılan: TRY)

Ek Hizmet Bilgileri (special_services) - Opsiyonel

Parametre Adı Parametre Tipi Zorunluluk Açıklama
special_services[].service_type String ZORUNLU Hizmet tipi
special_services[].details Object KOŞULLU Hizmet detayları

Detaylı bilgi için Ek Hizmetler sayfasına bakın.

Döküman Bilgileri (documents) - Opsiyonel

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

Detaylı bilgi için Döküman Yükleme sayfasına bakın.


Örnek Kullanım

3 Paketli Gönderi Örneği (Özel Barkodlu)

curl -X POST "{{BASE_URL}}/api/v1/consignments/multi-package" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}" \
  -d '{
    "provider_id": 1,
    "preference": 0,
    "reference_no": "SIP-20241217-MULTI-001",
    "consignor": {
        "name": "Mobilya Mağazası A.Ş.",
        "country": "TR",
        "state": "İstanbul",
        "city": "Şişli",
        "postal_code": "34381",
        "address": "Büyükdere Caddesi No:185",
        "phone_number": "+902123456789"
    },
    "consignee": {
        "name": "Ahmet Yılmaz",
        "country": "TR",
        "state": "Ankara",
        "city": "Çankaya",
        "postal_code": "06690",
        "address": "Kızılay Mahallesi No:42",
        "phone_number": "+905551234567"
    },
    "packages": [
        {
            "package_type": 1,
            "post_type": 4,
            "weight": 15.5,
            "length": 120,
            "width": 60,
            "height": 40,
            "specific_provider_barcode": "MOB-2024-001-A",
            "items": [
                {
                    "description": "Koltuk - Sol Modül",
                    "unit_price": 5000,
                    "quantity": 1
                }
            ]
        },
        {
            "package_type": 1,
            "post_type": 4,
            "weight": 15.5,
            "length": 120,
            "width": 60,
            "height": 40,
            "specific_provider_barcode": "MOB-2024-001-B",
            "items": [
                {
                    "description": "Koltuk - Sağ Modül",
                    "unit_price": 5000,
                    "quantity": 1
                }
            ]
        },
        {
            "package_type": 1,
            "post_type": 4,
            "weight": 8.2,
            "length": 80,
            "width": 50,
            "height": 30,
            "specific_provider_barcode": "MOB-2024-001-C",
            "items": [
                {
                    "description": "Koltuk - Orta Modül",
                    "unit_price": 4000,
                    "quantity": 1
                }
            ]
        }
    ]
}'

API Cevabı

Başarılı Yanıt

{
    "status": true,
    "message": "Multi package consignment created successfully",
    "data": {
        "consignment": 632285,
        "barcode": "XYZ123456",
        "c2hBarcode": "C2H07238640099",
        "providerTrackingCode": "XYZ123456",
        "trackingUrl": "https://<provider_domain>/<tracking_url>",
        "contentType": "application/pdf",
        "base64label": "...base64data",
        "detail": {
            "total_cost": 450.50,
            "currency_code": "TRY",
            "currency_rate": 1,
            "reference_no": "SIP-20241217-MULTI-001",
            "packages": {
                "desi": 125.6,
                "weight": 39.2,
                "quantity": 3
            }
        }
    }
}

Response Alanları

Alan Tip Açıklama
data.consignment Integer Oluşturulan gönderi ID'si
data.barcode String Kargo firması barkodu
data.c2hBarcode String ComToHome sistem barkodu
data.providerTrackingCode String Kargo takip kodu
data.trackingUrl String Kargo takip URL'i
data.base64label String Base64 encoded kargo etiketi
data.detail.total_cost Float Toplam kargo ücreti
data.detail.packages.quantity Integer Toplam paket adedi
data.detail.packages.weight Float Toplam ağırlık (kg)
data.detail.packages.desi Float Toplam desi değeri

Hata Cevapları

Yetersiz Paket Sayısı

{
    "status": false,
    "errors": [
        {
            "message": "This collection should contain 2 elements or more.",
            "field": "packages"
        }
    ]
}

Farklı Package Type Hatası

Tüm paketlerin package_type değeri aynı olmalıdır:

{
    "status": false,
    "errors": [
        {
            "message": "All package elements must have the same [package_type].",
            "field": "packages[1].packageType"
        }
    ]
}

Kısmi Barkod Hatası

Bazı paketlere barkod verilip bazılarına verilmediğinde:

{
    "status": false,
    "errors": [
        {
            "message": "Paketlerden herhangi birinde [specific_provider_barcode] varsa, tüm paketlerde olmalı ve her biri benzersiz olmalıdır.",
            "field": "specific_provider_barcode"
        }
    ]
}

Yaygın Hata Senaryoları

Hata Açıklama Çözüm
This collection should contain 2 elements or more. packages dizisinde 2'den az eleman var En az 2 paket ekleyin
All package elements must have the same [package_type]. Paketlerin package_type değerleri farklı Tüm paketlerde aynı package_type kullanın
Paketlerden herhangi birinde [specific_provider_barcode] varsa, tüm paketlerde olmalı ve her biri benzersiz olmalıdır. Bazı paketlere barkod verilmiş, bazılarına verilmemiş Ya tüm paketlere benzersiz barkod verin ya da hiçbirine vermeyin

İlgili Sayfalar