Yurtdışı Gönderi Oluştur

Bu API, Türkiye'den yurtdışına kargo ve lojistik gönderileri oluşturmak için kullanılır. Gönderen adresi Türkiye, alıcı adresi yurtdışında olmalıdır.

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

Yurtdışı 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, vergi numarası (Türkiye adresi)
Alıcı Bilgileri Ad, adres, telefon (Yurtdışı adresi)
Paket Bilgileri Ağırlık, boyutlar, GTİP kodu, menşei ülke, birim fiyat
Incoterms Gümrük teslim koşulu (DDP, DDU, DAP)

Minimal İstek Örneği

Aşağıda sadece zorunlu alanları içeren en basit yurtdışı gönderi oluşturma isteği bulunmaktadır:

{
    "provider_id": 7,
    "preference": 0,
    "address_resolver_type": 0,
    "incoterms_type": 1,
    "consignor": {
        "name": "Gönderen Firma",
        "country": "TR",
        "state": "İstanbul",
        "city": "Kadıköy",
        "postal_code": "34700",
        "address": "Gönderen adresi",
        "phone_number": "+902161234567",
        "tax_number": "1234567890"
    },
    "consignee": {
        "name": "Receiver Name",
        "country": "DE",
        "state": "Berlin",
        "city": "Berlin",
        "postal_code": "10115",
        "address": "Receiver address",
        "phone_number": "+4930123456"
    },
    "packages": [
        {
            "package_type": 1,
            "post_type": 4,
            "weight": 1,
            "length": 20,
            "width": 15,
            "height": 10,
            "dangerous_goods": false,
            "items": [
                {
                    "description": "Electronic Accessory",
                    "gtip": "854370900000",
                    "origin": "TR",
                    "currency_code": "EUR",
                    "unit_price": 25.00,
                    "quantity": 1
                }
            ]
        }
    ]
}

Yurtdışı Gönderilere Özel Alanlar

Incoterms (Gümrük Teslim Koşulları)

incoterms_type parametresi, gümrük vergilerinin ve teslimat sorumluluğunun kime ait olduğunu belirler.

Değer Kod Açıklama
1 DDP Delivered Duty Paid - Gümrük vergileri gönderene aittir. Alıcı hiçbir ek ödeme yapmaz.
2 DDU Delivered Duty Unpaid - Gümrük vergileri alıcıya aittir. Varsayılan değer.
3 DAP Delivered at Place - DDU ile aynı. Gümrük vergileri alıcıya aittir.

State Code (Eyalet Kodu)

ABD, Kanada ve İrlanda'ya yapılan gönderilerde state_code alanı zorunludur.

Ülke Örnek state_code
ABD (US) CA (California), NY (New York), TX (Texas)
Kanada (CA) ON (Ontario), BC (British Columbia), QC (Quebec)
İrlanda (IE) D (Dublin), CO (Cork)
{
    "consignee": {
        "country": "US",
        "state": "California",
        "state_code": "CA",
        "city": "Los Angeles",
        "postal_code": "90001"
    }
}

GTİP (Gümrük Tarife İstatistik Pozisyonu)

Yurtdışı gönderilerde her ürün için gtip kodu zorunludur. Bu kod, ürünün gümrük sınıflandırmasını belirler.

Ürün Kategorisi Örnek GTİP
Elektronik aksesuarlar 854370900000
Tekstil ürünleri 620520000000
Gıda ürünleri 170490999019
Kozmetik 330499900000

GTİP Arama: Doğru GTİP kodunu bulmak için GTİP Arama API'yi kullanabilirsiniz.

Post Type (Gönderi Türü)

Yurtdışı gönderilerde post_type alanı zorunludur. Bu alan, gönderinin gümrük beyanı türünü belirler.

Değer Kod Açıklama
1 SAMPLE Numune gönderisi
2 MICRO Mikro İhracat (ETGB) - 15.000 EUR altı ticari gönderiler
3 GIFT Hediye gönderisi
4 SALE Satış - E-ticaret gönderileri için önerilen
5 PERSONAL Bireysel gönderi
6 OTHER Diğer
7 DOCUMENT Döküman - Ticari değeri olmayan evraklar

E-ticaret İpucu: Online satış gönderileri için SALE (4) veya mikro ihracat kapsamındaki gönderiler için MICRO (2) kullanın.

E-Arşiv Fatura Zorunluluğu

Ticari yurtdışı gönderilerde e-arşiv fatura yüklemesi zorunludur:

Post Type Kod E-Arşiv Fatura
2 MICRO (Mikro İhracat) Zorunlu
4 SALE (Satış) Zorunlu

Gönderi oluşturmadan önce faturayı sisteme yüklemeniz ve dönen id değerini gönderi isteğinde kullanmanız gerekir.

Adım İşlem Açıklama
1 E-Arşiv Fatura Yükle Döküman Yükleme API ile faturayı yükleyin
2 Döküman ID'sini Al Yanıtta dönen id değerini saklayın
3 Gönderi Oluştur documents dizisine döküman ID'sini ekleyerek gönderi oluşturun

Gönderi isteğinde döküman ekleme:

{
    "packages": [
        {
            "post_type": 2,
            ...
        }
    ],
    "documents": [
        {
            "id": 12345
        }
    ]
}

Önemli: Mikro ihracat ve satış gönderilerinde e-arşiv fatura yüklemeden gönderi oluşturmaya çalışırsanız, kargo firması gönderinizi reddedebilir. Detaylı bilgi için Döküman Yükleme sayfasını inceleyin.

EORI Numarası

Avrupa Birliği ülkelerine yapılan ticari gönderilerde eori_number alanı önerilir. EORI (Economic Operators Registration and Identification), AB gümrük işlemlerinde kullanılan benzersiz bir tanımlayıcıdır.

{
    "consignor": {
        "name": "Anadolu Teknoloji A.Ş.",
        "tax_number": "1234567890",
        "eori_number": "TR1234567890123"
    }
}

Taşıma Yöntemi Seçimi (PTT Abroad)

PTT Abroad ile yurtdışı gönderi oluştururken, specific_shipping_method parametresi ile Uçak Koli veya Yüzey Koli taşıma yöntemini seçebilirsiniz.

Değer Açıklama Teslimat Süresi
pttabroad_air_parcel Uçak Koli - Hava yolu ile taşıma Daha hızlı (5-10 iş günü)
pttabroad_ground_parcel Yüzey Koli - Kara/deniz yolu ile taşıma Daha ekonomik (15-45 iş günü)

Not: Bu parametre yalnızca PTT Abroad provider'ı için geçerlidir. Belirtilmezse varsayılan olarak Uçak Koli kullanılır.

Örnek Kullanım:

{
    "provider_id": 7,
    "specific_shipping_method": "pttabroad_ground_parcel",
    "consignor": { ... },
    "consignee": { ... },
    "packages": [ ... ]
}

IOSS Numarası (Import One-Stop Shop)

Avrupa Birliği'ne yapılan 150 EUR altı e-ticaret gönderilerinde IOSS numarası kullanılabilir. IOSS, satıcının alıcı adına KDV'yi ödeyerek gümrük süreçlerini hızlandırmasını sağlar.

Önemli: IOSS numarası API isteğinde gönderilmez. Bu numara müşteri parametresi olarak sisteme tanımlanır ve tüm yurtdışı gönderilerinize otomatik olarak eklenir.

IOSS numarası tanımlatmak için: ComToHome destek ekibiyle iletişime geçerek ioss_number parametresinin hesabınıza tanımlanmasını talep edin.

Özellik Açıklama
Kapsam AB ülkelerine 150 EUR altı B2C gönderiler
Avantaj Alıcı gümrükte KDV ödemez, teslimat hızlanır
Tanımlama Müşteri parametresi olarak panel üzerinden

Opsiyonel Header'lar

Etiket Formatı (X-Label-Format)

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 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ü. Varsayılan: 0 (NONE). Detaylı Bilgi
reference_no String (MAX 255) OPSİYONEL Referans numarası
invoice_number String (MAX 255) OPSİYONEL Fatura numarası
incoterms_type Integer OPSİYONEL Gümrük teslim koşulu. Varsayılan: 2 (DDU). Kullanılabilir Değerler
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 atama. Varsayılan: false
specific_provider_barcode String (MAX 255) OPSİYONEL Özel barkod tanımlama
is_pickup_requested Bool OPSİYONEL Kurye çağırma talebi. true ise gönderi için otomatik kurye talebi oluşturulur. 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 (TR)
consignor.state String (MAX 100) ZORUNLU İl
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
consignor.tax_number String (MAX 255) OPSİYONEL Vergi numarası (yurtdışı için önerilir)
consignor.eori_number String (MAX 255) OPSİYONEL EORI numarası (AB ülkeleri için önerilir)
consignor.state_code String (MAX 255) KOŞULLU Eyalet kodu (ABD, Kanada, İrlanda için zorunlu)

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/ISO3)
consignee.state String (MAX 100) ZORUNLU İl/Eyalet
consignee.city String (MAX 100) ZORUNLU Şehir
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) OPSİYONEL Vergi numarası
consignee.eori_number String (MAX 255) OPSİYONEL EORI numarası
consignee.state_code String (MAX 255) KOŞULLU Eyalet kodu (ABD, Kanada, İrlanda için zorunlu)

Paket Bilgileri

Parametre Adı Parametre Tipi Zorunluluk Açıklama
packages.reference_no String (MAX 255) OPSİYONEL Paket referans numarası
packages.package_type Integer ZORUNLU Paket türü. 1 (Box) veya 2 (Envelope) Kullanılabilir Değerler
packages.provider_packaging_type String OPSİYONEL Sağlayıcı özel paketleme türü
packages.post_type Integer ZORUNLU Gönderi türü Kullanılabilir Değerler
packages.weight Float ZORUNLU Paket ağırlığı (kg). Minimum: 0.01
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.dangerous_goods Boolean ZORUNLU Tehlikeli madde içeriyor mu?
packages.items Array ZORUNLU Paket içerik listesi (en az 1 adet)

Paket İçerik Bilgileri

Parametre Adı Parametre Tipi Zorunluluk Açıklama
packages.items.description String (MAX 255) ZORUNLU Ürün açıklaması (İngilizce önerilir)
packages.items.gtip String (MAX 16) ZORUNLU GTİP kodu (Gümrük tarife numarası)
packages.items.origin String (2-3 KARAKTER) ZORUNLU Menşei ülke kodu
packages.items.currency_code String (3 KARAKTER) ZORUNLU Para birimi (EUR, USD, GBP vb.)
packages.items.unit_price Float ZORUNLU Birim fiyat. Minimum: 0
packages.items.quantity Integer ZORUNLU Miktar. Minimum: 1
packages.items.category String (MAX 255) OPSİYONEL Kategori
packages.items.weight Float OPSİYONEL Ürün ağırlığı (kg). Minimum: 0.01

Döküman Bilgileri (Opsiyonel)

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.

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

Ek Hizmet Bilgileri (Opsiyonel)

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

Parametre Adı Parametre Tipi Zorunluluk Açıklama
special_services.service_type String ZORUNLU Hizmet tipi (örn. INSURANCE, SIGNATURE_REQUIRED)
special_services.details.$dinamik Dinamik KOŞULLU Her hizmet tipi için dinamik parametreler

Örnek Kullanım

Tam İstek Örneği (Tüm Diller)

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": 7,
    "preference": 0,
    "address_resolver_type": 0,
    "incoterms_type": 2,
    "reference_no": "SIP-20241217-EU-001",
    "consignor": {
        "name": "Anadolu Teknoloji A.Ş.",
        "attention_name": "İhracat Departmanı",
        "country": "TR",
        "state": "İstanbul",
        "city": "Kadıköy",
        "postal_code": "34710",
        "address": "Moda Caddesi No:45 Kat:3 Caferağa Mahallesi",
        "phone_number": "+902163456789",
        "email": "ihracat@anadolutech.com",
        "tax_number": "1234567890",
        "eori_number": "TR1234567890123"
    },
    "consignee": {
        "name": "Hans Mueller",
        "attention_name": "Hans Mueller",
        "country": "DE",
        "state": "Berlin",
        "city": "Berlin",
        "postal_code": "10115",
        "address": "Friedrichstrasse 123, Mitte",
        "phone_number": "+493012345678",
        "email": "hans.mueller@example.de"
    },
    "packages": [
        {
            "package_type": 1,
            "post_type": 4,
            "weight": 0.85,
            "length": 25,
            "width": 20,
            "height": 10,
            "dangerous_goods": false,
            "items": [
                {
                    "description": "Wireless Bluetooth Headphones",
                    "gtip": "851830000000",
                    "origin": "TR",
                    "currency_code": "EUR",
                    "unit_price": 79.99,
                    "quantity": 1,
                    "category": "Electronics"
                }
            ]
        }
    ]
}'

API Cevabı

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

{
    "status": true,
    "message": "Consignment created successfully",
    "data": {
        "consignment": 632279,
        "barcode": "C2H46282802942",
        "c2hBarcode": "C2H46282802942",
        "providerTrackingCode": "1Z999AA10123456784",
        "trackingUrl": "https://provider.com/track/1Z999AA10123456784",
        "contentType": "application/pdf",
        "base64label": "...base64data",
        "detail": {
            "total_cost": 245.50,
            "currency_code": "TRY",
            "currency_rate": 1,
            "reference_no": "SIP-20241217-EU-001",
            "packages": {
                "desi": 1.13,
                "weight": 0.85,
                "quantity": 1
            }
        }
    }
}

Response Alanları

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
data.providerTrackingCode String Kargo firması takip kodu
data.trackingUrl String Kargo takip sayfası URL'i
data.contentType String Etiket dosya formatı
data.base64label String Base64 encoded kargo etiketi
data.detail.total_cost Float Toplam kargo ücreti
data.detail.currency_code String Para birimi

Hata Cevapları

API isteği başarısız olursa, API aşağıdaki gibi bir hata yanıtı döndürecektir:

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

Yaygın Hata Senaryoları

Hata Mesajı Field Açıklama Çözüm
[referenceNo] Referans numarası kullanılmaktadır. reference_no Aynı referans daha önce kullanılmış Benzersiz referans numarası kullanın
Bu değer boş bırakılmamalıdır. packages.items.gtip vb. Zorunlu alan boş İlgili alanı doldurun
Eyalet kodu zorunludur. consignee.state_code ABD/Kanada/İrlanda için state_code eksik İlgili eyalet kodunu ekleyin
Kargo sağlayıcısı bu ülkeye gönderi desteklememektedir. consignee.country Provider hedef ülkeyi desteklemiyor Farklı provider seçin
Only BOX, ENVELOPE enums are allowed. packages.package_type Geçersiz paket tipi 1 (Box) veya 2 (Envelope) kullanın

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. Gümrük Belgeleri: Gerekirse CN22 veya CN23 oluşturun
  3. Proforma Fatura: Proforma Invoice oluşturun
  4. Takip: trackingUrl veya c2hBarcode ile gönderiyi takip edin
  5. Webhook: Gönderi durumu değişikliklerini otomatik almak için Webhook kurulumu yapın