Aras Kargo API Dokümantasyonu

Polyline Works
🌐 polylineworks.com | 📞 0530 652 78 02 | ✉️ yunus@polylineworks.com

Aras Kargo entegrasyonu için güvenli ve hızlı API çözümü

Genel Bakış

Bu API, Aras Kargo entegrasyonu için tek bir endpoint üzerinden hem sipariş oluşturma (SetOrder) hem de etiket alma (GetBarcode) işlemlerini gerçekleştirir. Tek bir request ile sipariş oluşturulur ve etiket bilgileri döndürülür.

Önemli: Bu API tek sipariş destekler. Her request'te sadece bir sipariş gönderilebilir.

Authentication

Tüm isteklerde X-API-Key header'ı ile authentication yapılmalıdır. Her client'ın kendi unique API key'i vardır.

Header

X-API-Key: your-api-key-here
			Content-Type: application/json

Örnek

curl -X POST 'https://aras-api.polyline.works/shipment' \
			  -H 'Content-Type: application/json' \
			  -H 'X-API-Key: your-api-key-here'

Base URL

Production: https://aras-api.polyline.works
			Test: https://your-api-domain-test.com

Base URL'inizi API sağlayıcınızdan alın.

Endpoints

POST /shipment

Sipariş oluşturur ve etiket bilgilerini döndürür.

Tek bir request ile:

  1. Aras Kargo'da sipariş oluşturulur (SetOrder)
  2. Sipariş başarılıysa etiket bilgileri alınır (GetBarcode)
  3. Her iki işlemin sonucu birleştirilerek döndürülür

POST /barcode

Mevcut bir sipariş için sadece etiket bilgilerini alır.

Kullanım Senaryosu:

  • Daha önce oluşturulmuş bir siparişin etiket bilgilerine ihtiyaç duyduğunuzda
  • SetOrder yapmadan sadece etiket almak istediğinizde
  • Etiket bilgilerini yeniden almak istediğinizde

Not: Bu endpoint için SetOrder'dan dönen invoiceKey gerekir. Request body'de IntegrationCode olarak gönderilmelidir.

Request Formatı

Zorunlu Alanlar

Alan Tip Açıklama
ReceiverName String Alıcı adı soyadı (boş olamaz)
ReceiverAddress String Alıcı adresi (boş olamaz)
ReceiverPhone1 String Alıcı telefon numarası (boş olamaz)
ReceiverCityName String Alıcı şehir adı (boş olamaz)
ReceiverTownName String Alıcı ilçe adı (boş olamaz)
Weight String Kargo ağırlığı (kg) (boş olamaz)
PieceCount String Parça/koli sayısı (pozitif sayı, boş olamaz)
PieceDetails Array Parça detayları dizisi (en az 1 item, PieceCount ile eşit uzunlukta)

Opsiyonel Alanlar

Alıcı Ek Bilgileri

Alan Tip Açıklama
ReceiverPhone2 String Alıcı telefon 2
ReceiverPhone3 String Alıcı telefon 3
ReceiverDistrictName String Alıcı mahalle
ReceiverQuarterName String Alıcı semt
ReceiverAvenueName String Alıcı bulvar
ReceiverStreetName String Alıcı sokak

Kargo Ek Bilgileri

Alan Tip Açıklama
TradingWaybillNumber String Ticari irsaliye numarası
InvoiceNumber String Fatura numarası
VolumetricWeight String Hacimsel ağırlık (kg)
IntegrationCode String Entegrasyon kodu (sizin sisteminizdeki sipariş kodu)
Description String Kargo açıklaması

Özel Alanlar

Alan Tip Açıklama
SpecialField1 String Özel alan 1
SpecialField2 String Özel alan 2
SpecialField3 String Özel alan 3

COD (Kapıda Ödeme) Bilgileri

Alan Tip Açıklama
CodAmount String Kapıda ödeme tutarı
CodCollectionType String Kapıda ödeme tahsilat tipi
CodBillingType String Kapıda ödeme faturalama tipi
IsCod String Kapıda ödeme aktif mi? ("1" = evet, "0" = hayır)

Vergi Bilgileri

Alan Tip Açıklama
TaxNumber String Vergi numarası
TaxOffice String Vergi dairesi
TtDocumentId String TT belge ID

Diğer Bilgiler

Alan Tip Açıklama
PrivilegeOrder String Öncelikli sipariş
Country String Ülke
CountryCode String Ülke kodu
CityCode String Şehir kodu
TownCode String İlçe kodu
PayorTypeCode String Ödeyen tip kodu
IsWorldWide String Dünya çapında gönderim
UnitID String Birim ID
SenderAccountAddressId String Gönderen hesap adres ID

Aras Kargo Credentials (Opsiyonel)

Alan Tip Açıklama
userName String Aras Kargo kullanıcı adı (yoksa client config'deki kullanılır)
password String Aras Kargo şifresi (yoksa client config'deki kullanılır)

PieceDetails Yapısı

PieceDetails bir array'dir ve her eleman bir obje olabilir. Obje boş olabilir ({}) veya aşağıdaki alanları içerebilir:

Alan Tip Açıklama
VolumetricWeight String Parçanın hacimsel ağırlığı
Weight String Parçanın gerçek ağırlığı
BarcodeNumber String Parçanın barkod numarası
ProductNumber String Ürün kodu
Description String Parçanın açıklaması

ÖNEMLİ: PieceDetails array uzunluğu PieceCount ile tam olarak eşit olmalıdır!

  • PieceCount: "1" → PieceDetails: [{}] (1 adet obje)
  • PieceCount: "3" → PieceDetails: [{}, {}, {}] (3 adet obje)
  • PieceCount: "5" → PieceDetails: [{}, {}, {}, {}, {}] (5 adet obje)

Response Formatı

Başarılı Response

{
			  "success": true,
			  "data": {
				"setOrder": {
				  "success": true,
				  "resultCode": "0",
				  "resultMessage": "Başarılı",
				  "invoiceKey": "ORDER-2024-001",
				  "orgReceiverCustId": "CUST-123"
				},
				"getBarcode": {
				  "success": true,
				  "resultCode": 0,
				  "message": "Başarılı",
				  "images": ["base64_image_data..."],
				  "zebraZpl": ["ZPL_DATA..."],
				  "zebraEpl": ["EPL_DATA..."],
				  "barcodeModels": [...]
				}
			  }
			}

Hatalı Response (Validation)

{
			  "success": false,
			  "error": {
				"message": "Eksik zorunlu alanlar: Alıcı Adı, Alıcı Adresi",
				"code": "VALIDATION_ERROR",
				"details": [
				  {
					"field": "ReceiverName",
					"fieldName": "Alıcı Adı",
					"message": "Alıcı Adı alanı zorunludur ve gönderilmelidir"
				  },
				  {
					"field": "ReceiverAddress",
					"fieldName": "Alıcı Adresi",
					"message": "Alıcı Adresi alanı zorunludur ve gönderilmelidir"
				  }
				]
			  }
			}

Hatalı Response (SetOrder Başarısız)

{
			  "success": false,
			  "data": {
				"setOrder": {
				  "success": false,
				  "resultCode": "70021",
				  "resultMessage": "Toplam parça sayısı ile gönderilen parça sayısı eşit değil.",
				  "errors": [
					{
					  "resultCode": "70021",
					  "resultMessage": "Toplam parça sayısı ile gönderilen parça sayısı eşit değil."
					}
				  ]
				},
				"getBarcode": {
				  "success": false,
				  "error": "SetOrder failed, GetBarcode not called"
				}
			  }
			}

Hatalı Response (GetBarcode Başarısız)

{
			  "success": false,
			  "data": {
				"setOrder": {
				  "success": true,
				  "resultCode": "0",
				  "resultMessage": "Başarılı",
				  "invoiceKey": "ORDER-2024-001"
				},
				"getBarcode": {
				  "success": false,
				  "resultCode": 999,
				  "message": "Kullanıcı adı yada şifreniz yanlıştır."
				}
			  }
			}

Hata Mesajları

HTTP Status Kodları

Kod Açıklama
200 Başarılı
400 Validation hatası (eksik/geçersiz alanlar)
401 Authentication hatası (API key eksik/geçersiz)
500 Sunucu hatası

Hata Kodları

Kod Açıklama
VALIDATION_ERROR Request body validation hatası
MISSING_API_KEY API key header'ı eksik
INVALID_API_KEY API key geçersiz
CLIENT_NOT_FOUND Client bilgisi bulunamadı
INTERNAL_ERROR Sunucu içi hata

Örnekler

Örnek 1: Basit Kargo Siparişi

curl -X POST 'https://aras-api.polyline.works/shipment' \
			  -H 'Content-Type: application/json' \
			  -H 'X-API-Key: your-api-key-here' \
			  -d '{
				"ReceiverName": "Ahmet Yılmaz",
				"ReceiverAddress": "Atatürk Mahallesi, Cumhuriyet Caddesi No:123 Daire:5",
				"ReceiverPhone1": "05321234567",
				"ReceiverCityName": "İstanbul",
				"ReceiverTownName": "Kadıköy",
				"Weight": "2.5",
				"PieceCount": "1",
				"PieceDetails": [{}]
			  }'

Örnek 2: Detaylı Kargo Siparişi

curl -X POST 'https://aras-api.polyline.works/shipment' \
			  -H 'Content-Type: application/json' \
			  -H 'X-API-Key: your-api-key-here' \
			  -d '{
				"ReceiverName": "Mehmet Demir",
				"ReceiverAddress": "Merkez Mahallesi, İstiklal Caddesi No:45",
				"ReceiverPhone1": "05329876543",
				"ReceiverPhone2": "02161234567",
				"ReceiverCityName": "Ankara",
				"ReceiverTownName": "Çankaya",
				"ReceiverDistrictName": "Kızılay",
				"Weight": "5.0",
				"PieceCount": "2",
				"VolumetricWeight": "6.0",
				"IntegrationCode": "ORDER-2024-001",
				"InvoiceNumber": "INV-2024-001",
				"Description": "Elektronik ürün gönderimi",
				"CodAmount": "1500.00",
				"CodCollectionType": "1",
				"CodBillingType": "1",
				"IsCod": "1",
				"PayorTypeCode": "1",
				"Country": "Türkiye",
				"CountryCode": "TR",
				"CityCode": "06",
				"TownCode": "1234",
				"PieceDetails": [
				  {},
				  {}
				]
			  }'

Örnek 3: Çoklu Parça Kargo (3 Parça)

curl -X POST 'https://aras-api.polyline.works/shipment' \
			  -H 'Content-Type: application/json' \
			  -H 'X-API-Key: your-api-key-here' \
			  -d '{
				"ReceiverName": "Ayşe Yıldız",
				"ReceiverAddress": "Çamlık Mahallesi, Deniz Caddesi No:20",
				"ReceiverPhone1": "05334445566",
				"ReceiverCityName": "Antalya",
				"ReceiverTownName": "Muratpaşa",
				"Weight": "8.5",
				"PieceCount": "3",
				"IntegrationCode": "ORDER-2024-002",
				"Description": "3 parça kargo gönderimi",
				"PieceDetails": [
				  {},
				  {},
				  {}
				]
			  }'

Örnek 4: PieceDetails ile Detaylı Bilgi

curl -X POST 'https://aras-api.polyline.works/shipment' \
			  -H 'Content-Type: application/json' \
			  -H 'X-API-Key: your-api-key-here' \
			  -d '{
				"ReceiverName": "Ali Veli",
				"ReceiverAddress": "Yeni Mahalle, Atatürk Bulvarı No:10",
				"ReceiverPhone1": "05331112233",
				"ReceiverCityName": "İzmir",
				"ReceiverTownName": "Konak",
				"Weight": "6.0",
				"PieceCount": "2",
				"IntegrationCode": "ORDER-2024-003",
				"PieceDetails": [
				  {
					"VolumetricWeight": "3.0",
					"Weight": "3.0",
					"BarcodeNumber": "ABC123",
					"ProductNumber": "PRD001",
					"Description": "İlk Paket"
				  },
				  {
					"VolumetricWeight": "3.0",
					"Weight": "3.0",
					"BarcodeNumber": "DEF456",
					"ProductNumber": "PRD002",
					"Description": "İkinci Paket"
				  }
				]
			  }'

JavaScript/TypeScript Örneği

async function createShipment() {
			  const response = await fetch('https://aras-api.polyline.works/shipment', {
				method: 'POST',
				headers: {
				  'Content-Type': 'application/json',
				  'X-API-Key': 'your-api-key-here'
				},
				body: JSON.stringify({
				  ReceiverName: "Ahmet Yılmaz",
				  ReceiverAddress: "Atatürk Mahallesi, Cumhuriyet Caddesi No:123",
				  ReceiverPhone1: "05321234567",
				  ReceiverCityName: "İstanbul",
				  ReceiverTownName: "Kadıköy",
				  Weight: "2.5",
				  PieceCount: "1",
				  PieceDetails: [{}]
				})
			  });
			
			  const data = await response.json();
			  
			  if (data.success) {
				console.log('Sipariş başarılı:', data.data.setOrder.invoiceKey);
				console.log('Etiket bilgileri:', data.data.getBarcode);
			  } else {
				console.error('Hata:', data.error);
			  }
			}

Python Örneği

import requests
			
			url = "https://aras-api.polyline.works/shipment"
			headers = {
				"Content-Type": "application/json",
				"X-API-Key": "your-api-key-here"
			}
			data = {
				"ReceiverName": "Ahmet Yılmaz",
				"ReceiverAddress": "Atatürk Mahallesi, Cumhuriyet Caddesi No:123",
				"ReceiverPhone1": "05321234567",
				"ReceiverCityName": "İstanbul",
				"ReceiverTownName": "Kadıköy",
				"Weight": "2.5",
				"PieceCount": "1",
				"PieceDetails": [{}]
			}
			
			response = requests.post(url, json=data, headers=headers)
			result = response.json()
			
			if result["success"]:
				print(f"Sipariş başarılı: {result['data']['setOrder']['invoiceKey']}")
			else:
				print(f"Hata: {result['error']}")

GetBarcode Endpoint (/barcode)

Request Formatı

Zorunlu Alanlar

Alan Tip Açıklama
IntegrationCode String SetOrder'dan dönen InvoiceKey (boş olamaz)

Opsiyonel Alanlar

Alan Tip Açıklama
userName String Aras Kargo kullanıcı adı (yoksa client config'deki kullanılır)
password String Aras Kargo şifresi (yoksa client config'deki kullanılır)

Request Örneği

{
			  "IntegrationCode": "ORDER-2024-001"
			}

Response Formatı

Başarılı Response

{
			  "success": true,
			  "data": {
				"resultCode": 0,
				"message": "Başarılı",
				"images": ["base64_image_data..."],
				"zebraZpl": ["ZPL_DATA..."],
				"zebraEpl": ["EPL_DATA..."],
				"barcodeModels": [...]
			  }
			}

Hatalı Response

{
			  "success": false,
			  "error": {
				"message": "Kullanıcı adı yada şifreniz yanlıştır.",
				"code": "INTERNAL_ERROR"
			  }
			}

cURL Örneği

curl -X POST 'https://aras-api.polyline.works/barcode' \
			  -H 'Content-Type: application/json' \
			  -H 'X-API-Key: your-api-key-here' \
			  -d '{
				"IntegrationCode": "ORDER-2024-001"
			  }'

JavaScript Örneği

async function getBarcode(invoiceKey) {
			  const response = await fetch('https://aras-api.polyline.works/barcode', {
				method: 'POST',
				headers: {
				  'Content-Type': 'application/json',
				  'X-API-Key': 'your-api-key-here'
				},
				body: JSON.stringify({
				  IntegrationCode: invoiceKey
				})
			  });
			
			  const data = await response.json();
			  
			  if (data.success) {
				console.log('Etiket bilgileri:', data.data);
				console.log('Barkod görselleri:', data.data.images);
			  } else {
				console.error('Hata:', data.error);
			  }
			}

Sık Sorulan Sorular

S: PieceCount ile PieceDetails uzunluğu neden eşit olmalı?

C: Aras Kargo API'si bu kuralı zorunlu kılar. PieceCount toplam parça sayısını belirtir ve PieceDetails array'i her parça için bir obje içermelidir. Eşit olmazsa "Toplam parça sayısı ile gönderilen parça sayısı eşit değil" hatası alırsınız.

S: PieceDetails içindeki obje boş olabilir mi?

C: Evet, boş obje ({}) gönderebilirsiniz. Aras Kargo API'si bunu kabul eder. İsterseniz parça bazında detaylı bilgi de ekleyebilirsiniz (VolumetricWeight, Weight, BarcodeNumber, vb.).

S: Birden fazla sipariş gönderebilir miyim?

C: Hayır, bu API tek sipariş destekler. Her request'te sadece bir sipariş gönderebilirsiniz. Birden fazla sipariş için her biri için ayrı request göndermelisiniz.

S: userName ve password göndermem gerekir mi?

C: Hayır, opsiyoneldir. Eğer göndermezseniz, client config'deki Aras Kargo credentials kullanılır. Sadece farklı credentials kullanmak istiyorsanız gönderebilirsiniz.

S: Response'da hem setOrder hem getBarcode var, neden?

C: API tek bir request'te hem sipariş oluşturur hem de etiket bilgilerini alır. setOrder sipariş oluşturma sonucunu, getBarcode ise etiket bilgilerini içerir. Eğer setOrder başarısız olursa getBarcode çağrılmaz.

S: Hata mesajları Türkçe mi?

C: Evet, validation hataları Türkçe döner. Ancak Aras Kargo'dan gelen hata mesajları Aras Kargo'nun kendi formatındadır.

S: Rate limit var mı?

C: Rate limit bilgisi için API sağlayıcınızla iletişime geçin.

S: Test ortamı var mı?

C: Evet, test ortamı URL'inizi API sağlayıcınızdan alın. Test ortamında gerçek kargo oluşturulmaz, sadece API entegrasyonunu test edebilirsiniz.

Destek ve İletişim

Sorularınız, teknik destek talepleriniz veya özel entegrasyon ihtiyaçlarınız için bizimle iletişime geçebilirsiniz:

Polyline Works

🌐 Website: polylineworks.com
📞 Telefon: 0530 652 78 02
✉️ E-posta: yunus@polylineworks.com

Çalışma Saatleri:
Pazartesi - Cuma: 09:00 - 18:00
Cumartesi: 10:00 - 14:00

Versiyon Bilgisi

API Versiyonu: 1.0.0
Son Güncelleme: 2026
Geliştirici: Polyline Works

Önemli Notlar

  1. PieceCount ve PieceDetails: Bu iki alanın uzunluğu mutlaka eşit olmalıdır.
  2. Tek Sipariş: Her request'te sadece bir sipariş gönderilebilir.
  3. Zorunlu Alanlar: Tüm zorunlu alanlar gönderilmelidir, aksi halde validation hatası alırsınız.
  4. API Key: Her request'te X-API-Key header'ı gönderilmelidir.
  5. Content-Type: Request body JSON formatında olmalı ve Content-Type: application/json header'ı gönderilmelidir.

© 2026 Polyline Works. Tüm hakları saklıdır.

🌐 Website | 📧 E-posta | 📞 Telefon