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.
| Ö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.
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ı |
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.
{
"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 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.
Sözleşme gönderilerinde paket package_type değeri 6 olarak gönderilmelidir.
{
"packages": [
{
"package_type": 6
}
]
}
Sözleşme gönderileri tek paket olarak oluşturulmalıdır. Bir gönderide birden fazla paket gönderimi desteklenmez.
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"
}
]
}
]
}
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) |
| 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 |
| 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 |
consignee.tax_number |
String (MAX 255) | ZORUNLU | Alıcının T.C. kimlik numarası |
| 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 |
| 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) |
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"
}
]
}
]
}'
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 |
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"
}
]
}
| 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 |
Gönderi başarıyla oluşturulduktan sonra:
base64label alanını decode ederek etiketi yazdırıntrackingUrl, providerTrackingCode veya c2hBarcode ile gönderiyi takip edin