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.
| Ö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.
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 |
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.
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.
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.
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.
| 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ı |
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. |
| 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) |
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
}
}
| 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 |
| 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 |
| 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 |
| 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) |
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) |
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 |
{
//diğer gönderi parametreleri...
"documents": [
{
"id": 4617
}
]
//diğer gönderi parametreleri...
}
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 |
{
//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...
}
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
}
]
}
]
}'
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
}
}
}
}
| 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.
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"
}
]
}
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"
}
]
}
| 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 |
Gönderi başarıyla oluşturulduktan sonra:
base64label alanını decode ederek etiketi yazdırıntrackingUrl veya c2hBarcode ile gönderiyi takip edin