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.
| 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.
| Ö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.
| Ö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ı) |
Tüm paketlerin package_type değeri aynı olmalıdır. Farklı package_type değerleri gönderilirse hata alırsınız.
Ç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.
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
}
]
}
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.
| 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 |
| 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 |
| 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 |
| 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 |
Önemli Kurallar:
packages dizisi en az 2 eleman içermelidirpackage_type değeri aynı olmalıdırspecific_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 |
| 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) |
| 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.
| 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.
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
}
]
}
]
}'
{
"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
}
}
}
}
| 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 |
{
"status": false,
"errors": [
{
"message": "This collection should contain 2 elements or more.",
"field": "packages"
}
]
}
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"
}
]
}
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"
}
]
}
| 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 |