Başlangıç

ZEMLOG API v1 nedir ?

ZEMLOG app panelinden yapılan işlemleri başka sistemler üzerinden yapabilmeniz için geliştirilen API'nin güncel sürümüdür. Tüm istekler tek bir taban adrese gönderilir; her endpointin tam yolu kendi sayfasında yer alır.

ℹ️ Eski API'den mi geçiyorsunuz?

Eski endpointlerin v1 karşılıkları ve değişen alanlar Eski API'den Geçiş sayfasında listelenmiştir.

API Değişkenleri

Değişken	Tip	Değer
token	string
api_url	string	https://gateway.zemlog.com

API v1 istekleri https://gateway.zemlog.com adresine gönderilir. https://api.zemlog.com yalnızca kullanım dışı eski endpointler için kullanılmaya devam eder.

Kapsam

API v1 ile şu işlemleri yapabilirsiniz:

• Token alma
• Fiyat hesaplama, gönderi oluşturma ve tek nokta ithalat
• Fatura listeleme
• Ülke, şehir, ilçe, para birimi, ölçü birimi ve ihracat kodu listeleri

/api/v1/public/ ile başlayan istekler token gerektirmez. Diğer tüm istekler Authorization başlığında token ister.

İstek Başlıkları

Başlık	Zorunlu	Açıklama
Authorization	Evet (/public/ istekleri hariç)	Bearer {token}
Content-Type	Gövdeli isteklerde	application/json
Accept-Language	Hayır	tr (varsayılan) ya da en (en ile başlayan değerler, ör. en-US, İngilizce sayılır). Ülke, ölçü birimi, durum ve paket ek ücreti adları ile doğrulama mesajları bu dilde döner.

Her yanıt Zemlog-Request-Id başlığını içerir. Destek talebinde bu değeri paylaşırsanız isteğinizi hızlıca bulabiliriz.

Yanıt Yapısı

Tek kayıt dönen istekler:

{
  "success": true,
  "message": "Gönderi oluşturuldu",
  "data": {}
}

Listeler data yerine items döner; sayfalı listelerde meta da gelir:

{
  "success": true,
  "message": "Faturalar listelendi",
  "items": [],
  "meta": { "page": 1, "perPage": 25, "total": 3, "pageCount": 1 }
}

Gövdesiz işlemlerde (ör. tek nokta ithalatı tamamlama) yalnızca success ve message döner. Tarihler ISO 8601 biçiminde ve UTC'dir (ör. 2026-10-10T10:24:19.000Z).

Sayfalama

Listeleme istekleri page (varsayılan 1), perPage (en fazla 200), sortBy ve sortOrder (asc / desc) sorgu parametrelerini kabul eder.

Hata Yapısı

{
  "success": false,
  "code": "VALIDATION_FAILED",
  "message": "Girdi doğrulanamadı.",
  "errors": [{ "path": "recipientAddress.zipCode", "message": "Posta kodu gerekli." }]
}

HTTP	Anlamı	code
400	İş kuralı hatası, bulunamayan kayıt ya da okunamayan JSON gövdesi	İşleme özgü kod (ör. CARRIER_IS_NOT_FOUND); kendi kodu olmayan bulunamama durumlarında ve okunamayan gövdede BAD_REQUEST
401	Token yok, geçersiz ya da süresi dolmuş; uygulama pasif ya da silinmiş; uygulamayı oluşturan kullanıcı artık organizasyonun üyesi değil	SESSION_TIME_HAS_EXPIRED (token yok, Bearer öneki eksik ya da süresi dolmuş), TOKEN_COULD_NOT_BE_VERIFIED, APPLICATION_IS_NOT_ACTIVE, APPLICATION_IS_NOT_FOUND, ORGANIZATION_IS_NOT_SELECTED
403	Uygulamayı oluşturan kullanıcının bu işlem için izni yok	ACCESS_DENIED; ZEMLOG'un verdiği ek yetki gereken alanlarda (ör. gönderi yorumu) FORBIDDEN
404	Tanımsız yol (gövdesiz döner)	—
422	İstek doğrulanamadı; errors hatalı alanları listeler	VALIDATION_FAILED
500	Beklenmeyen sunucu hatası	INTERNAL_ERROR
503	Hizmet geçici olarak kullanılamıyor; isteği tekrar deneyin	DEPENDENCY_UNAVAILABLE

Entegrasyonunuzda message yerine code alanını kullanın. Başarı, iş kuralı, yetki ve 503 mesajları Accept-Language başlığından bağımsız olarak Türkçe döner. Doğrulama hatalarında errors her alan için yalnızca ilk hatayı içerir.

İzinler

Uygulama tokenı, uygulamayı oluşturan kullanıcının organizasyondaki izinleriyle çalışır. İzin eksikse istek 403 ACCESS_DENIED döner.

İşlem	Gerekli izin
Fiyat Hesapla, Varış Adresini Doğrula	Fiyat Hesaplama ya da Gönderiler (yalnızca Gönderiler izniyle tutarlar dönmez)
Belge ve Paket Gönderisi Oluştur	Gönderiler
Tek Nokta İthalat Oluştur ve Tamamla	Tek Nokta İthalat
Fatura Listesi	Faturalar
Yardımcı API	İzin gerekmez

API için Token Nasıl Alınır ?

Token alma işleminin nasıl yapılacağına dair detaylı bilgi için tıklayınız.

⚠️ Dikkat

Bu işlemler yapılmadan ZEMLOG API v1'i kullanamazsınız (/api/v1/public/ istekleri hariç).