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 |
| Ürün Tanımlayıcıları (PID) | AB'ye yapılan B2C gönderilerde her kalem için 1 Kasım 2026'dan itibaren zorunlu |
| 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",
"party_type": "business"
},
"consignee": {
"name": "Receiver Name",
"country": "DE",
"state": "Berlin",
"city": "Berlin",
"postal_code": "10115",
"address": "Receiver address",
"phone_number": "+4930123456",
"party_type": "individual"
},
"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,
"merchant_product_id": "SKU-ACC-001",
"manufacturer_product_id": "MFR-USB-C-2M"
}
]
}
],
"generate_templated_documents": [
{
"type": "PROFORMA_INVOICE"
}
]
}
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ı artık API isteğinde kök seviyede ioss_number alanı ile gönderilir. IOSS kullanılacak gönderilerde bu alanı request payload içine eklemelisiniz.
Örnek kullanım:
{
"provider_id": 7,
"ioss_number": "IM2760000742",
"consignor": { ... },
"consignee": { ... },
"packages": [ ... ]
}
| Özellik | Açıklama |
|---|---|
| Kapsam | AB ülkelerine 150 EUR altı B2C gönderiler |
| Avantaj | Alıcı gümrükte KDV ödemez, teslimat hızlanır |
| Gönderim Şekli | API isteğinde kök seviyede ioss_number alanı ile |
Avrupa Birliği gümrük reformu kapsamında, AB ülkelerine yapılan B2C gönderilerde her ürün kalemi için ürün tanımlayıcısı (Product Identifier, PID) bildirilmesi gerekmektedir. Bu bilgiler her kalem için packages[].items[] içinde üç ayrı alanla gönderilir.
Önemli: 1 Kasım 2026 tarihinden itibaren AB ülkelerine yapılan B2C gönderilerde her ürün kalemi için PID bilgisi zorunludur. PID bilgisi eksik olan gönderiler gümrükte bekletilebilir, gecikebilir veya göndericiye iade edilebilir. API bu alanlar olmadan da gönderi oluşturur; ancak AB'ye giden gönderilerinizde bu alanları mutlaka doldurmanız gerekmektedir.
| Alan | AB Karşılığı | Açıklama | Örnek |
|---|---|---|---|
merchant_product_id |
Merchant PID (M-PID) | Satıcının kendi ürün kodu, genellikle mağazadaki SKU. AB tarafından her kalem için istenir. | SKU-TSHIRT-001 |
manufacturer_product_id |
Non-standardised Manufacturer PID (NS-PID) | Üreticinin verdiği model veya parça numarası (MPN). AB tarafından her kalem için istenir. | MFR-TS-RED-M |
standard_product_id |
Standardised Manufacturer PID (S-PID) | Uluslararası standart barkod: GTIN, EAN, UPC veya ISBN. Ürünün böyle bir kodu varsa gönderilmelidir. | 8690000000012 |
Kurallar:
null gönderin."") gönderilirse istek Bu değer boş bırakılmamalıdır. hatasıyla reddedilir.Örnek kullanım:
Aşağıdaki örnekte ilk kalemde üç alan da gönderilmiştir. İkinci kalemin standart barkodu olmadığı için standard_product_id gönderilmemiştir.
{
"provider_id": 7,
"consignor": { ... },
"consignee": { ... },
"packages": [
{
"package_type": 1,
"post_type": 4,
"weight": 3,
"length": 30,
"width": 20,
"height": 15,
"dangerous_goods": false,
"items": [
{
"description": "Cotton T-shirt",
"gtip": "610910",
"origin": "TR",
"currency_code": "EUR",
"unit_price": 12.50,
"quantity": 1,
"merchant_product_id": "SKU-TSHIRT-001",
"manufacturer_product_id": "MFR-TS-RED-M",
"standard_product_id": "8690000000012"
},
{
"description": "Denim jeans",
"gtip": "620342",
"origin": "TR",
"currency_code": "EUR",
"unit_price": 25.00,
"quantity": 2,
"merchant_product_id": "SKU-JEANS-002",
"manufacturer_product_id": "MFR-JN-BLU-32"
}
]
}
]
}
İpucu: Gönderinin B2C olduğunun kargo firmasına doğru iletilmesi için alıcı bireysel ise consignee.party_type alanını individual olarak göndermeniz önerilir.
| Özellik | Açıklama |
|---|---|
| Kapsam | AB ülkelerine yapılan B2C gönderiler |
| Yürürlük | 1 Kasım 2026 |
| Gönderim Şekli | Her ürün kalemi için packages[].items[] içinde |
| Eksik Olursa | Gönderi gümrükte bekletilebilir, gecikebilir veya iade edilebilir |
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 |
Sadece Staging: Bu header yalnızca staging (test) ortamında çalışır. Production ortamında herhangi bir etkisi yoktur ve gönderilse de yok sayılır.
Takip akışınızı test etmek istediğinizde, gönderi oluştururken X-Create-Dummy-Data: true header'ını gönderebilirsiniz. Staging ortamında bu, oluşturulan gönderi için rastgele seçilmiş sahte (dummy) event'lerin otomatik olarak oluşturulmasını tetikler. Böylece gerçek gönderi hareketlerini beklemeden tracking/webhook entegrasyonunuzu test edebilirsiniz.
| Header | Değer | Açıklama |
|---|---|---|
X-Create-Dummy-Data |
true |
Oluşturulan gönderi için rastgele seçilmiş sahte event'ler üretir. Sadece staging ortamı. |
curl -X POST "{{BASE_URL}}/api/v1/consignments" \
-H "Content-Type: application/json" \
-H "APIKEY: {{APIKEY}}" \
-H "x-create-dummy-data: true" \
-d '{ ... }'
Not: Sahte event'ler sistem tarafından rastgele seçilir. Tracking testleriniz için belirli event'lerin eklenmesini isterseniz destek ekibimizle iletişime geçebilirsiniz.
| 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 |
ioss_number |
String (MAX 255) | OPSİYONEL | IOSS numarası. AB'ye 150 EUR altı B2C gönderilerde request payload'ın kök seviyesinde gönderilir |
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. Barkod tanımlanması için müşteri temsilciniz ile iletişime geçiniz. |
is_pickup_requested |
Bool | OPSİYONEL | Kurye çağırma talebi. true ise gönderi için otomatik kurye talebi oluşturulur. Varsayılan: false |
generate_templated_documents |
Array | OPSİYONEL | Otomatik oluşturulacak doküman listesi. Detaylı Bilgi |
| 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) |
consignor.party_type |
String | OPSİYONEL | Gönderici tipi. Alabileceği değerler: individual, business. B2B/B2C gönderi bilgisini belirlemek ve provider'lara iletmek için kullanılır |
| 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) |
consignee.party_type |
String | OPSİYONEL | Alıcı tipi. Alabileceği değerler: individual, business. B2B/B2C gönderi bilgisini belirlemek ve provider'lara iletmek için kullanılır |
| 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 |
packages.items.merchant_product_id |
String (MAX 100) | OPSİYONEL | Satıcı ürün kodu (M-PID), genellikle SKU. 1 Kasım 2026'dan itibaren AB'ye B2C gönderilerde gereklidir. Değer yoksa gönderilmemeli veya null gönderilmelidir; boş metin kabul edilmez |
packages.items.manufacturer_product_id |
String (MAX 100) | OPSİYONEL | Üretici ürün kodu (NS-PID), model veya parça numarası. 1 Kasım 2026'dan itibaren AB'ye B2C gönderilerde gereklidir. Değer yoksa gönderilmemeli veya null gönderilmelidir; boş metin kabul edilmez |
packages.items.standard_product_id |
String (MAX 100) | OPSİYONEL | Standart ürün kodu (S-PID): GTIN, EAN, UPC veya ISBN. Ürünün böyle bir kodu varsa AB'ye B2C gönderilerde gönderilmelidir. Boş metin kabul edilmez |
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 |
Gönderi oluşturma isteğinde generate_templated_documents parametresini kullanarak, gönderi ile birlikte otomatik olarak Proforma Invoice dökümanı oluşturabilirsiniz. Bu sayede gönderi oluşturduktan sonra ayrı bir API çağrısı yapmanıza gerek kalmaz.
| Parametre Adı | Parametre Tipi | Zorunluluk | Açıklama |
|---|---|---|---|
generate_templated_documents |
Array | OPSİYONEL | Otomatik oluşturulacak doküman listesi |
generate_templated_documents[].type |
String | ZORUNLU | Doküman türü. Şu an desteklenen: PROFORMA_INVOICE |
| Tür | Değer | Açıklama |
|---|---|---|
| Proforma Invoice | PROFORMA_INVOICE |
Gümrük işlemleri için proforma fatura |
{
"provider_id": 7,
"consignor": { ... },
"consignee": { ... },
"packages": [ ... ],
"generate_templated_documents": [
{
"type": "PROFORMA_INVOICE"
}
]
}
Asenkron İşleme: Dokümanlar arka planda asenkron olarak oluşturulur. API yanıtı hemen döner, ancak doküman henüz hazır olmayabilir. Oluşturulan dokümanları Doküman Listele endpoint'i ile sorgulayabilirsiniz.
Idempotent Davranış: Aynı gönderi için daha önce aynı türde doküman oluşturulmuşsa, sistem tekrar oluşturmaz. Bu sayede aynı istek birden fazla kez gönderilse bile mükerrer doküman oluşmaz.
İpucu: Gönderi oluşturduktan sonra manuel olarak da proforma oluşturabilirsiniz. Detaylı bilgi için Proforma Oluştur sayfasını inceleyin.
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,
"ioss_number": "IM2760000742",
"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",
"merchant_product_id": "SKU-BT-HP-001",
"manufacturer_product_id": "MFR-WH1000-BLK",
"standard_product_id": "8690000000029"
}
]
}
],
"generate_templated_documents": [
{
"type": "PROFORMA_INVOICE"
}
]
}'
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 |
Bu değer boş bırakılmamalıdır. |
packages.items.merchant_product_id vb. |
PID alanına boş metin ("") gönderilmiş |
Alanı hiç göndermeyin veya null gönderin |
Bu değer çok uzun. 100 karakter veya daha az olmalıdır. |
packages.items.merchant_product_id vb. |
PID değeri 100 karakteri aşıyor | Değeri en fazla 100 karakter olacak şekilde düzeltin |
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