T-SOFT/Storefront API/Görsel Yükleme

Görsel Yükleme

Yetki:storefront:account — müşteri token'ı zorunlu.

Giriş yapmış müşterinin görsel gönderdiği iki ucu anlatır: ürün için kişiselleştirme görseli (baskı/tasarım görseli) ve sepette görselli sipariş notu. Her iki istek de multipart/form-data gövdesiyle gönderilir (JSON değil); yanıt JSON'dur.

Yoruma fotoğraf eklemek de görsel yükleme gerektirir ama ayrı bir uçtur ve kuralları (izin verilen tipler, boyut sınırı) burada anlatılanlardan farklıdır — bkz. Yorum Yazma.

Kişiselleştirme görseli

Müşterinin bir ürün için yükleyeceği kişiselleştirme (özel baskı/tasarım) görselini kaydeder ve barındırılan görselin genel URL'ini döner.

POST /storefront/account/2026-01/personalizations/with-image

curl -X POST "https://<domain>/api/v3/storefront/account/2026-01/personalizations/with-image" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer <CUSTOMER_TOKEN>" \
  -F "productId=771" \
  -F "image=@/yol/tasarim.png"

Yanıt 201 Created:

{
  "data": {
    "type": "personalization-images",
    "id": "1433-771-1752143400123",
    "attributes": {
      "productId": 771,
      "imageUrl": "/Data/Kisisellestirme/1752143400_9f2c1ab4c7d0e5f1.png",
      "createdAt": "2026-07-21T12:30:00+03:00"
    }
  }
}

İstek alanları

Alan	Tip	Kural
`productId`	integer	Zorunlu; en az `1`. Görselin bağlanacağı ürün.
`image`	dosya	Zorunlu. Tek görsel dosyası. İzinli tipler: `jpeg`, `jpg`, `png`, `gif`, `webp`. En fazla 8192 KB (8 MB).

Yanıt alanları

Alan	Tip	Kural
`id`	string	`{customerId}-{productId}-{timestamp}` biçiminde türetilir; kalıcı bir kayıt anahtarı değildir.
`productId`	integer	Görselin bağlandığı ürün.
`imageUrl`	string	Barındırılan görselin genel yolu (`/Data/Kisisellestirme/...`). Mağaza alan adıyla birleştirilerek tam URL elde edilir.
`createdAt`	string	Yükleme anı (ISO 8601).

Sepet görselli not

Giriş yapmış müşterinin, aktif sepetine ilişkin bir veya birden çok görseli (isteğe bağlı metin notlarıyla) mağazaya iletmesini sağlar. Görseller ve notlar mağazaya e-posta ile ulaştırılır.

POST /storefront/2026-01/cart/image-notes

curl -X POST "https://<domain>/api/v3/storefront/2026-01/cart/image-notes" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer <CUSTOMER_TOKEN>" \
  -F "images[]=@/yol/gorsel1.jpg" \
  -F "images[]=@/yol/gorsel2.jpg" \
  -F "notes[]=Ön yüze basılacak" \
  -F "notes[]=Arka yüz boş kalsın"

Yanıt 201 Created:

{
  "data": {
    "type": "cart-image-notes",
    "id": "1433-1752143400123",
    "attributes": {
      "imageCount": 2,
      "delivered": true,
      "createdAt": "2026-07-21T12:30:00+03:00"
    }
  }
}

İstek alanları

Alan	Tip	Kural
`images`	dizi	Zorunlu; en az `1`, en fazla `5` görsel.
`images.*`	dosya	İzinli tipler: `jpeg`, `jpg`, `png`, `gif`. Her görsel en fazla 5120 KB (5 MB).
`notes`	dizi	Opsiyonel. Görsel sayısından bağımsızdır; sunucu notları görsellere sırayla eşler.
`notes.*`	string	Opsiyonel; boş geçilebilir, en fazla `250` karakter.

Yanıt alanları

Alan	Tip	Kural
`id`	string	`{customerId}-{timestamp}` biçiminde türetilir; kalıcı bir kayıt anahtarı değildir.
`imageCount`	integer	İstekte gönderilen görsel sayısı.
`delivered`	bool	Görsel/not paketinin mağazaya iletiminin başarılı olup olmadığı.
`createdAt`	string	İşlem anı (ISO 8601).

Bu uç yalnızca giriş yapmış müşteride çalışır. Misafir sepeti token'ı istek katmanından geçse de işlem 403 ("Lütfen üye girişi yapınız.") döner — önce müşteri girişi yaptırın.

İki ucun farkları

Konu	Kişiselleştirme görseli	Sepet görselli not
Görsel adedi	Tek görsel (`image`)	Çoklu görsel (`images[]`, en fazla 5)
Boyut sınırı	8 MB / görsel	5 MB / görsel
`webp` desteği	Var	Yok (`jpeg`/`jpg`/`png`/`gif`)
Metin notu	Yok	Var (`notes[]`, her biri en fazla 250 karakter)
Misafir	Reddedilir	Reddedilir

Hatalar

Durum kodu	Sebep
401	Token yok/geçersiz veya müşteri token'ı değil
403	Müşteri token'ında `storefront:account` scope'u yok; sepet notunda misafir isteği; kişiselleştirmede ilgili mağaza özelliği kapalı
422	Doğrulama hatası — eksik/geçersiz alan, izinsiz dosya tipi, boyut/adet sınırı aşımı
429	Sepet notu ucunda istek sıklığı sınırı aşıldı (throttle)