Eski API'den v1'e Geçiş

Eski API endpointleri kullanım dışıdır ve ileride kaldırılacaktır. Bu sayfa her eski endpointin v1 karşılığını ve entegrasyonunuzda değiştirmeniz gerekenleri listeler. Panelden alınan İstemci ID / Gizli Anahtar bilgileri değişmez.

Genel Değişiklikler

• Taban adres https://api.zemlog.com yerine https://gateway.zemlog.com'dur. Eski endpointler kaldırılana kadar https://api.zemlog.com üzerinde çalışmaya devam eder.
• Endpoint yolları değişti; her endpointin v1 yolu aşağıdaki tabloda yer alır.
• Başarılı yanıtlar { success, message, data } zarfında döner; listeler items ve sayfalıysa meta döner. Eski API'de kayıt doğrudan, listeler düz dizi olarak (fatura listesi data ve pagination ile) dönüyordu. Ayrıntılar için Başlangıç sayfasına bakın.
• Hata gövdesi { success: false, code, message, errors? } biçimindedir; entegrasyonunuzda message yerine code alanını kullanın. Doğrulama hataları 400 yerine 422 VALIDATION_FAILED ile döner; violations[].propertyPath yerine errors[].path kullanılır ve her alan için yalnızca ilk hata listelenir.
• Eski API'de 406 dönen iş kuralı hataları v1'de 400 ve işleme özgü code ile döner; alana bağlı olanlar (ör. eksik gümrük posta kodu) 422 ile döner.
• Hizmet geçici olarak kullanılamadığında eski API 500 Beklenmedik bir hata oluştu., v1 503 DEPENDENCY_UNAVAILABLE döner.
• Eski API'de iş kuralı mesajları Accept-Language diline çevriliyordu. v1'de başarı, iş kuralı, yetki ve 503 mesajları her zaman Türkçedir; ad alanları (ülke, ölçü birimi, durum, paket ek ücreti) ve doğrulama mesajları dile göre döner. v1, Accept-Language değeri en ile başlıyorsa (ör. en-US,tr;q=0.9) İngilizce kabul eder.
• Tarihler 2026-10-10T10:24:19+00:00 yerine 2026-10-10T10:24:19.000Z biçimindedir.
• Liste endpointleri sayfalıdır (page, perPage en fazla 200). Varsayılan perPage fatura listesinde 25, yardımcı listelerde 50'dir; tüm listeyi almak için meta.pageCount kadar sayfayı dolaşın.
• sortOrder değerleri asc / desc'tir (büyük-küçük harf duyarsız). Tanımsız sortBy değeri 422 döner.
• Sorgu parametreleri doğrulanır: boş gönderilen (ör. search=) ya da tanımsız değerdeki parametre yok sayılmaz, 422 döner.

Endpoint Eşleştirmesi

Eski endpoint	v1 endpoint	Değişiklikler
POST /auth/application	POST /api/v1/auth/application	Token kök seviyedeki token yerine data.token alanında döner. Hatalı istemci bilgisinde 401 CLIENT_ID_OR_SECRET_INVALID, eksik alanda 400 yerine 422 döner.
POST /api/calculate/price	POST /api/v1/shipment/price-calculations	Taşıyıcı teklifleri kök dizi yerine items içinde döner. fuelSurcharges alanının adı fuelSurcharge oldu. Paket satırlarında id, piece ve perimeter dönmez; istekteki packages[].id desteklenmez. Paket ek ücretleri { type, desc, value } yerine { slug, name, amount } biçimindedir. null yalnızca city, zipCode, date ve piece için gönderilmemiş sayılır; diğer alanlarda (ör. carrierId, packages) 422 döner.
POST /api/calculate/price/country/validate	POST /api/v1/shipment/price-calculations/validate-destination	Başarıda 204 yerine 200 ve { success, message } döner. Uygun olmayan varış adresi 422 ile döner; mesajlar alana özgüdür (ör. Bu değer boş bırakılamaz. yerine Bu ülke için posta kodu zorunlu.).
POST /api/consignment/document	POST /api/v1/shipment/shipments/documents	200 yerine 201 döner, gönderi data içindedir. Organizasyona ait olmayan senderAddressId 406 yerine 400 BAD_REQUEST döner. Yanıt alanlarındaki farklar paket gönderisiyle aynıdır.
POST /api/consignment/package/advance	POST /api/v1/shipment/shipments/packages	Ürünlerde unitOfMeasure: { code, name } yerine unitOfMeasureCode gönderilir. 200 yerine 201 döner, gönderi data içindedir. 406 dönen iş kuralı hataları 400 ve kodla döner (ör. CARRIER_IS_NOT_FOUND, SENDER_ADDRESS_TAX_INFORMATION_IS_NOT_COMPLETED; şehir ve ilçe adaylarıyla params.options); eksik gümrük posta kodu ve yeni gönderici adresinde ilçeyle eşleşmeyen şehir 422 döner. Boş paket ya da ürün listesi 400 metni yerine 422 (packages / products) döner. Tamamlanmış tek nokta ithalat Tek nokta ithalat bulunamadı. yerine SINGLE_POINT_IMPORT_HAS_ALREADY_BEEN_COMPLETED_BEFORE döner. Yanıtta ülke bilgisi flags ve tax nesnelerindedir (flagW20 / flagW40 ve taxType / taxMaxValidPrice yerine); currency.updatedAt ve orderData dönmez; singlePointImport.shipmentId yerine singlePointImport.upsShipmentId gelir. Tip, durum, ülke ve menşe ülke adları her zaman Türkçe yerine Accept-Language diline göre döner.
POST /api/single/point/import	POST /api/v1/shipment/single-point-imports	200 yerine 201 döner, kayıt data içindedir. shipmentId yerine upsShipmentId (GCCN) gelir; senderAddress ve createdAt dönmez. Daha önce kullanılmış ad 400 yerine 422 (name) döner. SINGLE_POINT_IMPORT_CHARGE_FAILED hatası 500 yerine 400 ile döner.
POST /api/single/point/import/complete	POST /api/v1/shipment/single-point-imports/{id}/complete	ID gövde yerine yolda gönderilir. Başarıda 204 yerine 200 ve { success, message } döner.
POST /api/invoice/list	GET /api/v1/finance/invoices	GET isteğidir; süzgeçler gövde yerine sorgu parametresiyle gönderilir. isPayment yerine isPaid, dateAtBetween.startAt / endAt yerine dateFrom / dateTo, paymentExpirationAtBetween.startAt / endAt yerine paymentExpirationFrom / paymentExpirationTo kullanılır; tarihler yalnızca YYYY-MM-DD biçiminde kabul edilir. statusId süzgecinden 4 değeri kaldırıldı. Yanıtta data yerine items, pagination (count, lastPage) yerine meta (total, pageCount), currency.code yerine currencyCode döner; organizationId eklendi.
GET /country/all	GET /api/v1/public/shared/countries	Sayfalıdır. flagW20 / flagW40 yerine flags.w20 / flags.w40, taxType / taxMaxValidPrice yerine tax.type / tax.maxValidPrice gelir. isGuarantee süzgeci "1" / "0" yerine boolean'dır (true / false, 1 / 0 da kabul edilir); başka değer yok sayılmaz, 422 döner. search Türkçe adlarda da arar.
GET /city/all	GET /api/v1/public/shared/cities	Sayfalıdır. countryId ya da countryCode artık zorunlu değildir; verilmezse tüm ülkelerin şehirleri döner. ids, nameExact ve namePrefix süzgeçleri eklendi.
GET /county/all	GET /api/v1/public/shared/counties	Sayfalıdır. cityId artık zorunlu değildir; verilmezse tüm ilçeler döner. ids, nameExact ve namePrefix süzgeçleri eklendi.
GET /api/currency	GET /api/v1/shared/currencies	Sayfalıdır. rate ve updatedAt yerine TCMB kurları rates.sellingTry / rates.buyingTry (TRY) ve rates.updatedAt gelir; flagPath eklendi. sortBy değerleri sellingRateTry / buyingRateTry yerine sellingTry / buyingTry'dır. codes ve isDefined süzgeçleri eklendi.
GET /api/unit/of/measure/all	GET /api/v1/shared/units-of-measure	Sayfalıdır. Tanımsız sortBy değeri orderNumber'a düşmez, 422 döner.
GET /api/export/code	GET /api/v1/shared/export-codes	Sayfalıdır. Tanımsız sortBy değeri orderNumber'a düşmez, 422 döner.

Ülke, para birimi, ölçü birimi ve ihracat kodu ID'leri ve kodları değişmemiştir; Yardımcı Dokümanlar altındaki tablolar her iki sürüm için geçerlidir.