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