Sözleşme Gönderisi Oluştur

Bu API, PTT Sözleşme sağlayıcısı ile sözleşme tipi gönderi oluşturmak için kullanılır. Gönderi isteği standart gönderi oluşturma endpoint'i üzerinden yapılır; sözleşme bilgileri paket içindeki items alanında iletilir.

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ıç

Sözleşme gönderisi 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 sağlayıcı seçimi
Gönderen Bilgileri Ad, adres ve iletişim bilgileri
Alıcı Bilgileri Ad, adres, iletişim bilgileri ve T.C. kimlik numarası
Paket Bilgileri package_type: 6 değeri ile sözleşme paketi
Sözleşme Bilgileri Onay sonrası alınan sözleşme ID değeri ve sözleşme adı

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

Gönderi oluştururken kargo sağlayıcısını iki şekilde belirleyebilirsiniz:

Yöntem Ne Zaman Kullanılır? Örnek
provider_id Belirli bir sağlayıcı ile çalışmak istiyorsanız "provider_id": 12
preference Sistemin uygun sağlayıcıyı 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

{
    "provider_id": 12,
    "preference": 0,
    "reference_no": "SOZ-20260807-0001",
    "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",
        "tax_number": "12345678901"
    },
    "packages": [
        {
            "package_type": 6,
            "post_type": 7,
            "quantity": 1,
            "weight": 0.1,
            "length": 20,
            "width": 15,
            "height": 1,
            "items": [
                {
                    "description": "SOZLESME-10001",
                    "category": "Konut Kredisi Sözleşmesi"
                }
            ]
        }
    ]
}

Not: package_type: 6 değeri sözleşme paket tipini ifade eder. Tüm paket tipi değerleri için Paket Tipleri sayfasına bakın.

Not: Örneklerdeki post_type: 7 değeri döküman gönderi türünü ifade eder. Tüm gönderi türü değerleri için Gönderi Posta Tipleri sayfasına bakın.


Sözleşme Gönderilerine Özel Kurallar

Sözleşme Onayı ve Sözleşme ID

Sözleşme dökümanları sevkiyat gönderilmeden önce ComToHome'a iletilmeli ve onay süreci tamamlanmalıdır. Onay sonrası alınan sözleşme ID değeri, gönderi isteğinde packages[].items[].description alanında gönderilmelidir.

Sözleşme adı, aynı item içinde packages[].items[].category alanında yer almalıdır.

Paket Tipi

Sözleşme gönderilerinde paket package_type değeri 6 olarak gönderilmelidir.

{
    "packages": [
        {
            "package_type": 6
        }
    ]
}

Tek Paket Kullanımı

Sözleşme gönderileri tek paket olarak oluşturulmalıdır. Bir gönderide birden fazla paket gönderimi desteklenmez.

Birden Fazla Sözleşme Gönderimi

Bir pakete birden fazla sözleşme eklemek için aynı paketin items dizisine birden fazla kayıt ekleyebilirsiniz.

{
    "packages": [
        {
            "package_type": 6,
            "items": [
                {
                    "description": "SOZLESME-10001",
                    "category": "Konut Kredisi Sözleşmesi"
                },
                {
                    "description": "SOZLESME-10002",
                    "category": "Sigorta Sözleşmesi"
                }
            ]
        }
    ]
}

Sözleşme Bilgilerinin Gönderimi

PTT Sözleşme gönderilerinde onaylı sözleşme bilgileri packages[].items[] alanları ile iletilir:

Parametre Zorunluluk Açıklama
packages[].items[].description ZORUNLU PTT sözleşme ID değeri (sozlesmeId)
packages[].items[].category ZORUNLU PTT sözleşme adı (sozlesmeAdi)

İ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 PTT Sözleşme sağlayıcı ID'si. preference 0 ise zorunludur. Kullanılabilir Değerler
address_resolver_type Integer OPSİYONEL Adres çözümleme türü. Varsayılan: 0. Detaylı Bilgi
reference_no String (MAX 255) OPSİYONEL Referans numarası
invoice_number String (MAX 255) OPSİYONEL Fatura numarası
specific_provider_barcode String (MAX 255) OPSİYONEL Özel barkod tanımlama. Barkod tanımlanması için müşteri temsilciniz ile iletişime geçiniz.
is_pickup_requested Bool OPSİYONEL Kurye çağırma talebi. 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
consignee.tax_number String (MAX 255) ZORUNLU Alıcının T.C. kimlik numarası

Paket Bilgileri

Parametre Adı Parametre Tipi Zorunluluk Açıklama
packages[].package_type Integer ZORUNLU Sözleşme gönderileri için 6 gönderilmelidir
packages[].post_type Integer OPSİYONEL Gönderi türü. Döküman gönderileri için 7 kullanılabilir. Kullanılabilir Değerler
packages[].quantity Integer OPSİYONEL Paket adedi
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[].items Array ZORUNLU Sözleşme bilgileri listesi

Paket İçerik Bilgileri

Parametre Adı Parametre Tipi Zorunluluk Açıklama
packages[].items[].description String (MAX 255) ZORUNLU PTT sözleşme ID değeri (sozlesmeId)
packages[].items[].category String (MAX 255) ZORUNLU PTT sözleşme adı (sozlesmeAdi)
packages[].items[].quantity Integer OPSİYONEL Miktar
packages[].items[].unit_price Float OPSİYONEL Birim fiyat
packages[].items[].currency_code String (3 KARAKTER) OPSİYONEL Para birimi kodu (varsayılan: TRY)

Örnek Kullanım

curl -X POST "{{BASE_URL}}/api/v1/consignments" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}" \
  -d '{
    "provider_id": 12,
    "preference": 0,
    "reference_no": "SOZ-20260807-0001",
    "consignor": {
        "name": "Anadolu Finans A.Ş.",
        "country": "TR",
        "state": "İstanbul",
        "city": "Ataşehir",
        "postal_code": "34758",
        "address": "Barbaros Mahallesi, Örnek Caddesi No:10",
        "phone_number": "+902161234567",
        "email": "operasyon@example.com"
    },
    "consignee": {
        "name": "Ayşe Yılmaz",
        "country": "TR",
        "state": "Ankara",
        "city": "Çankaya",
        "postal_code": "06690",
        "address": "Kavaklıdere Mahallesi, Örnek Sokak No:5",
        "phone_number": "+905551234567",
        "tax_number": "12345678901"
    },
    "packages": [
        {
            "package_type": 6,
            "post_type": 7,
            "quantity": 1,
            "weight": 0.1,
            "length": 20,
            "width": 15,
            "height": 1,
            "items": [
                {
                    "description": "SOZLESME-10001",
                    "category": "Konut Kredisi Sözleşmesi"
                },
                {
                    "description": "SOZLESME-10002",
                    "category": "Sigorta Sözleşmesi"
                }
            ]
        }
    ]
}'

API Cevabı

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

{
    "status": true,
    "message": "Consignment created successfully",
    "data": {
        "consignment": 632280,
        "barcode": "PTT123456789",
        "c2hBarcode": "C2H07238640094",
        "providerTrackingCode": "PTT123456789",
        "trackingUrl": "https://<provider_domain>/<tracking_url>",
        "contentType": "application/pdf",
        "base64label": "...base64data",
        "detail": {
            "total_cost": 120.96,
            "currency_code": "TRY",
            "currency_rate": 1,
            "reference_no": "SOZ-20260807-0001",
            "packages": {
                "desi": 1,
                "weight": 0.1,
                "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 Sağlayıcı tarafından atanan barkod
data.c2hBarcode String ComToHome sistem barkodu
data.providerTrackingCode String Sağlayıcı takip kodu
data.trackingUrl String Takip sayfası URL'i
data.contentType String Etiket dosya formatı
data.base64label String Base64 encoded gönderi etiketi
data.detail.total_cost Float Toplam gönderi ücreti
data.detail.currency_code String Para birimi

Hata Cevapları

API isteği başarısız olursa aşağıdaki formatta hata yanıtı döner:

{
    "status": false,
    "errors": [
        {
            "message": "Bu değer boş bırakılmamalıdır.",
            "field": "packages[0].items[0].description"
        }
    ]
}

Yaygın Hata Senaryoları

Hata Açıklama Çözüm
Geçersiz provider_id Hesabınıza tanımlı olmayan veya PTT Sözleşme olmayan sağlayıcı kullanılmıştır Geçerli PTT Sözleşme sağlayıcı ID'si ile tekrar deneyin
Eksik sözleşme ID packages[].items[].description alanı gönderilmemiştir Her sözleşme için sözleşme ID değerini gönderin
Eksik sözleşme adı packages[].items[].category alanı gönderilmemiştir Her sözleşme için sözleşme adını gönderin
Onaylanmamış sözleşme bilgisi Sözleşme dökümanı gönderi öncesinde onaylanmamıştır Sözleşme dökümanını ComToHome'a iletip onay sonrası alınan sözleşme ID değerini kullanın
Eksik alıcı T.C. kimlik numarası consignee.tax_number alanı gönderilmemiştir Alıcının T.C. kimlik numarasını gönderin
Birden fazla paket Sözleşme gönderisi tek paket olarak oluşturulmalıdır Tüm sözleşmeleri tek paketin items dizisine ekleyin

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, providerTrackingCode veya c2hBarcode ile gönderiyi takip edin
  3. Webhook: Gönderi durumu değişikliklerini otomatik almak için Webhook kurulumu yapın