Data Format

External Commerce API request ve response body'lerinde JSON kullanır. Başarılı ve başarısız cevaplar ortak bir envelope yapısını takip eder.

Request formatı

Body kabul eden endpointlerde JSON gönderin ve Content-Type: application/json header'ını kullanın.

Alan tiplerini endpoint dokümantasyonunda belirtilen contract'a uygun gönderin.

Başarılı response

Başarılı çağrılarda success=true olur. Endpoint'e ait asıl veri data objesi içerisinde bulunur.

Liste endpointleri pagination veya authority gibi ek bilgileri meta içerisinde döndürebilir.

Alan	Tip	Ne işe yarar?
success	boolean	İşlemin başarılı olduğunu gösterir
data	object	Endpoint'e ait veri
meta	object\|null	Pagination veya ek metadata
request_id	string	İsteğin correlation kimliği

Hata response

Başarısız çağrılarda success=false olur. error.code uygulamanızın programatik karar vermesi, error.message ise hatanın insan tarafından anlaşılması için kullanılır.

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "Gönderilen veriler geçersiz."
  },
  "request_id": "req_xxx"
}

JSON veri tipleri

boolean: true veya false
integer: tam sayı ID veya stok gibi değerler
number/decimal: fiyat gibi sayısal değerler
string: ad, SKU, URL, status gibi değerler
null: contract izin verdiğinde boş değer
array: birden fazla item veya event
object: iç içe response yapıları

Response parser kuralı

Alan sırasına güvenmeyin. Yalnızca ihtiyaç duyduğunuz alanları okuyun. Yeni geriye uyumlu alanların response'a eklenmesi entegrasyonunuzu bozmamalıdır.

request_id neden önemli?

Her API isteğini operasyonel olarak izlemek için response request_id değerini teknik loglarınızda saklamanız önerilir. Beklenmeyen bir hatada bu değer belirli API çağrısının bulunmasını kolaylaştırır.