Satıcı Entegrasyonu

Entegrasyon API Dokümantasyonu

Ürün, stok, fiyat, sipariş ve müşteri sorularınızı kendi yazılımınız ya da entegratörünüz üzerinden yönetin. Tüm istekler JSON formatındadır.

https://takimelbise.com/api/public/integration

Yetkilendirme

API bilgilerinize Satıcı Paneli → Mağaza Yönetimi → Entegrasyon Bilgileri sayfasından ulaşabilirsiniz. Satıcı ID, API Key ve API Secret mağazanıza özeldir; API Secret yalnızca oluşturulduğu anda gösterilir. Anahtarı yenilediğinizde eski anahtar hemen geçersiz olur.

Authorization: Basic base64(apiKey:apiSecret)
User-Agent: {saticiId} - {EntegratorAdi} — kendi yazılımınızı kullanıyorsanız SelfIntegration yazın. Entegratör adı en fazla 30 karakter, harf/rakam içerebilir.
Satıcıya özel uçlarda URL'deki {sellerId} ile User-Agent'taki satıcı ID'si, anahtarın ait olduğu mağaza ile aynı olmalıdır; aksi halde 403 döner.

Örnek başlıklar

Authorization: Basic QVBJX0tFWTpBUElfU0VDUkVU
User-Agent: 100001 - SelfIntegration
Content-Type: application/json

Limitler

Mağaza başına 10 saniyede en fazla 50 istek. Aşıldığında 429 döner.
Toplu isteklerde tek seferde en fazla 1000 kalem.
Listeleme uçlarında sayfa boyutu en fazla 200.

Ürün

Ürünler varyant (barkod) bazında gönderilir. Aynı productMainId'ye sahip kalemler tek ürünün varyantları olarak gruplanır. Oluşturma ve güncelleme işlemleri asenkron mantıkta batchRequestId döner; sonucu toplu işlem sorgulama ucu ile kontrol edin.

Ürün Oluşturma

POST/sellers/{sellerId}/products

Tek istekte en fazla 1000 kalem gönderilebilir. Oluşturulan ürünler onay bekliyor durumunda başlar.

İstek gövdesi (items[] içindeki her kalem)

Alan	Tip	Zorunlu	Açıklama
barcode	string	Evet	Varyanta ait benzersiz barkod (en fazla 40 karakter).
title	string	Evet	Ürün adı (3-200 karakter).
productMainId	string	Evet	Ana ürün/model kodu; varyantları gruplar.
brandId	uuid	Hayır	Marka listesinden alınan ID.
categoryId	uuid	Evet	Kategori ağacından alt (leaf) kategori ID.
quantity	int	Evet	Stok adedi.
stockCode	string	Evet	Satıcı stok kodu (SKU).
listPrice	number	Evet	Liste (üstü çizili) fiyat, TL.
salePrice	number	Evet	Satış fiyatı, TL.
vatRate	number	Hayır	KDV oranı (0, 1, 10, 20). Varsayılan 10.
description	string	Hayır	Ürün açıklaması (HTML desteklenir).
dimensionalWeight	number	Hayır	Desi.
images	array	Hayır	[{ url }] en fazla 8 görsel; ilk görsel kapak olur.
attributes	array	Hayır	[{ attributeId, attributeValueId \| customAttributeValue }]

Örnek istek

curl -X POST "https://takimelbise.com/api/public/integration/sellers/100001/products" \
  -H "Authorization: Basic $(echo -n 'API_KEY:API_SECRET' | base64)" \
  -H "User-Agent: 100001 - SelfIntegration" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"barcode":"TE-LAC-48","title":"Slim Fit Lacivert Takım Elbise","productMainId":"TE-LAC","brandId":"b1c2…","categoryId":"c3d4…","quantity":25,"stockCode":"TE-LAC-48","listPrice":4999.9,"salePrice":3499.9,"vatRate":10,"description":"<p>%100 yün kumaş</p>","images":[{"url":"https://cdn.ornek.com/te-lac-1.jpg"}],"attributes":[{"attributeId":"a1…","attributeValueId":"v48…"}]}]}'

Örnek yanıt

{
  "batchRequestId": "7f0d6a1e-…"
}

Ürün Bilgisi Güncelleme

PUT/sellers/{sellerId}/products

Barkod ile eşleşen ürünün başlık, açıklama, kategori, marka, KDV ve stok kodu bilgilerini günceller. Fiyat-stok için ayrı ucu kullanın.

İstek gövdesi (items[] içindeki her kalem)

Alan	Tip	Zorunlu	Açıklama
barcode	string	Evet	Güncellenecek varyantın barkodu.
title / description / categoryId / brandId / vatRate / stockCode	—	Hayır	Sadece gönderilen alanlar güncellenir.

Örnek istek

curl -X PUT "https://takimelbise.com/api/public/integration/sellers/100001/products" \
  -H "Authorization: Basic $(echo -n 'API_KEY:API_SECRET' | base64)" \
  -H "User-Agent: 100001 - SelfIntegration" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"barcode":"TE-LAC-48","title":"Slim Fit Lacivert Takım Elbise - Yeni Sezon"}]}'

Örnek yanıt

{
  "batchRequestId": "8a1b…"
}

Ürün Filtreleme

GET/sellers/{sellerId}/products

Mağazanıza ait ürünleri varyant bazında listeler.

Sorgu parametreleri

Alan	Tip	Zorunlu	Açıklama
page	int	Hayır	Sayfa numarası (0'dan başlar).
size	int	Hayır	Sayfa boyutu (varsayılan 50, en fazla 200).
barcode	string	Hayır	Barkoda göre filtrele.
stockCode	string	Hayır	Stok koduna göre filtrele.
approved	boolean	Hayır	true: onaylı, false: onaysız ürünler.

Örnek istek

curl -X GET "https://takimelbise.com/api/public/integration/sellers/100001/products" \
  -H "Authorization: Basic $(echo -n 'API_KEY:API_SECRET' | base64)" \
  -H "User-Agent: 100001 - SelfIntegration"

Örnek yanıt

{
  "totalElements": 1,
  "totalPages": 1,
  "page": 0,
  "size": 50,
  "content": [
    {
      "id": "…",
      "variantId": "…",
      "barcode": "TE-LAC-48",
      "stockCode": "TE-LAC-48",
      "title": "Slim Fit Lacivert Takım Elbise",
      "productMainId": "TE-LAC",
      "approved": true,
      "quantity": 25,
      "listPrice": 4999.9,
      "salePrice": 3499.9,
      "vatRate": 10
    }
  ]
}

Toplu İşlem Kontrolü

GET/sellers/{sellerId}/products/batch-requests/{batchRequestId}

Ürün oluşturma, güncelleme ve fiyat-stok isteklerinin kalem bazlı sonucunu döner.

Örnek istek

curl -X GET "https://takimelbise.com/api/public/integration/sellers/100001/products/batch-requests/{batchRequestId}" \
  -H "Authorization: Basic $(echo -n 'API_KEY:API_SECRET' | base64)" \
  -H "User-Agent: 100001 - SelfIntegration"

Örnek yanıt

{
  "batchRequestId": "7f0d6a1e-…",
  "batchRequestType": "ProductCreate",
  "status": "COMPLETED",
  "itemCount": 1,
  "failedItemCount": 0,
  "items": [
    {
      "requestItem": {
        "barcode": "TE-LAC-48"
      },
      "status": "SUCCESS",
      "failureReasons": []
    }
  ]
}

Fiyat ve Stok

Stok ve Fiyat Güncelleme

POST/sellers/{sellerId}/products/price-and-inventory

Barkod bazında stok ve fiyat günceller. salePrice, listPrice'tan büyük olamaz.

İstek gövdesi (items[] içindeki her kalem)

Alan	Tip	Zorunlu	Açıklama
barcode	string	Evet	Varyant barkodu.
quantity	int	Hayır	Yeni stok adedi.
listPrice	number	Hayır	Liste fiyatı.
salePrice	number	Hayır	Satış fiyatı.

Örnek istek

curl -X POST "https://takimelbise.com/api/public/integration/sellers/100001/products/price-and-inventory" \
  -H "Authorization: Basic $(echo -n 'API_KEY:API_SECRET' | base64)" \
  -H "User-Agent: 100001 - SelfIntegration" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"barcode":"TE-LAC-48","quantity":10,"listPrice":4999.9,"salePrice":2999.9}]}'

Örnek yanıt

{
  "batchRequestId": "9c2e…"
}

Kategori ve Marka

Kategori Ağacı

GET/product-categories

Aktif kategorileri alt kategorileriyle birlikte ağaç yapısında döner. Ürünler leaf kategorilere eklenir.

Örnek istek

curl -X GET "https://takimelbise.com/api/public/integration/product-categories" \
  -H "Authorization: Basic $(echo -n 'API_KEY:API_SECRET' | base64)" \
  -H "User-Agent: 100001 - SelfIntegration"

Örnek yanıt

{
  "categories": [
    {
      "id": "…",
      "name": "Takım Elbise",
      "parentId": null,
      "leaf": false,
      "subCategories": [
        {
          "id": "…",
          "name": "Slim Fit",
          "leaf": true,
          "subCategories": []
        }
      ]
    }
  ]
}

Kategori Özellik Listesi

GET/product-categories/{categoryId}/attributes

Kategoriye bağlı özellikleri ve o kategori için seçilebilir değerleri döner (ör. takım elbise bedeni 44-62, tişört bedeni S-XXL).

Örnek istek

curl -X GET "https://takimelbise.com/api/public/integration/product-categories/{categoryId}/attributes" \
  -H "Authorization: Basic $(echo -n 'API_KEY:API_SECRET' | base64)" \
  -H "User-Agent: 100001 - SelfIntegration"

Örnek yanıt

{
  "id": "…",
  "name": "Takım Elbise",
  "categoryAttributes": [
    {
      "attribute": {
        "id": "…",
        "code": "beden",
        "name": "Beden"
      },
      "required": true,
      "varianter": true,
      "allowCustom": false,
      "allowMultiple": false,
      "attributeValues": [
        {
          "id": "…",
          "name": "48"
        },
        {
          "id": "…",
          "name": "50"
        }
      ]
    }
  ]
}

Marka Listesi

GET/brands

Aktif markaları döner.

Sorgu parametreleri

Alan	Tip	Zorunlu	Açıklama
name	string	Hayır	Marka adında arama.

Örnek istek

curl -X GET "https://takimelbise.com/api/public/integration/brands" \
  -H "Authorization: Basic $(echo -n 'API_KEY:API_SECRET' | base64)" \
  -H "User-Agent: 100001 - SelfIntegration"

Örnek yanıt

{
  "brands": [
    {
      "id": "…",
      "name": "Kadir Büyükkaya"
    }
  ]
}

Sipariş

Her sipariş mağaza bazında paketlere ayrılır; id değeri mağazanıza ait sipariş paketinin ID'sidir.

Sipariş Paketlerini Çekme

GET/sellers/{sellerId}/orders

Mağazanıza ait sipariş paketlerini satırlarıyla birlikte listeler.

Sorgu parametreleri

Alan	Tip	Zorunlu	Açıklama
page	int	Hayır	Sayfa numarası (0'dan başlar).
size	int	Hayır	Sayfa boyutu (varsayılan 50, en fazla 200).
status	string	Hayır	paid, confirmed, preparing, shipped, delivered, cancelled, refunded
startDate	long	Hayır	Başlangıç tarihi (epoch ms).
endDate	long	Hayır	Bitiş tarihi (epoch ms).

Örnek istek

curl -X GET "https://takimelbise.com/api/public/integration/sellers/100001/orders" \
  -H "Authorization: Basic $(echo -n 'API_KEY:API_SECRET' | base64)" \
  -H "User-Agent: 100001 - SelfIntegration"

Örnek yanıt

{
  "totalElements": 1,
  "page": 0,
  "size": 50,
  "content": [
    {
      "id": "…",
      "orderNumber": "TE100245",
      "status": "paid",
      "orderDate": 1761222000000,
      "totalPrice": 3499.9,
      "cargoProviderName": null,
      "cargoTrackingNumber": null,
      "lines": [
        {
          "productName": "Slim Fit Lacivert Takım Elbise",
          "barcode": "TE-LAC-48",
          "quantity": 1,
          "price": 3499.9
        }
      ]
    }
  ]
}

Paket Statü Güncelleme

PUT/sellers/{sellerId}/orders/{packageId}/status

Paketi onaylandı, hazırlanıyor, kargoya verildi, teslim edildi veya iptal durumuna çeker. Kargoya verirken takip numarası zorunludur.

İstek gövdesi (items[] içindeki her kalem)

Alan	Tip	Zorunlu	Açıklama
status	string	Evet	confirmed \| preparing \| shipped \| delivered \| cancelled
cargoProviderName	string	Hayır	Kargo firması (ör. Yurtiçi Kargo).
trackingNumber	string	Hayır	Kargo takip numarası (shipped için zorunlu).
trackingUrl	string	Hayır	Takip bağlantısı.
invoiceNumber	string	Hayır	Fatura numarası.

Örnek istek

curl -X PUT "https://takimelbise.com/api/public/integration/sellers/100001/orders/{packageId}/status" \
  -H "Authorization: Basic $(echo -n 'API_KEY:API_SECRET' | base64)" \
  -H "User-Agent: 100001 - SelfIntegration" \
  -H "Content-Type: application/json" \
  -d '{"status":"shipped","cargoProviderName":"Yurtiçi Kargo","trackingNumber":"123456789"}'

Örnek yanıt

{
  "id": "…",
  "status": "shipped"
}

Müşteri Soruları

Soruları Çekme

GET/sellers/{sellerId}/questions

Ürünlerinize sorulan soruları listeler.

Sorgu parametreleri

Alan	Tip	Zorunlu	Açıklama
page	int	Hayır	Sayfa numarası (0'dan başlar).
size	int	Hayır	Sayfa boyutu (varsayılan 50, en fazla 200).
status	string	Hayır	WAITING_FOR_ANSWER \| ANSWERED

Örnek istek

curl -X GET "https://takimelbise.com/api/public/integration/sellers/100001/questions" \
  -H "Authorization: Basic $(echo -n 'API_KEY:API_SECRET' | base64)" \
  -H "User-Agent: 100001 - SelfIntegration"

Örnek yanıt

{
  "totalElements": 1,
  "content": [
    {
      "id": "…",
      "text": "Kumaşı terletir mi?",
      "status": "WAITING_FOR_ANSWER",
      "productName": "Slim Fit Lacivert Takım Elbise",
      "answer": null
    }
  ]
}

Soru Cevaplama

POST/sellers/{sellerId}/questions/{questionId}/answers

Cevap 10-2000 karakter olmalıdır.

İstek gövdesi (items[] içindeki her kalem)

Alan	Tip	Zorunlu	Açıklama
text	string	Evet	Cevap metni.

Örnek istek

curl -X POST "https://takimelbise.com/api/public/integration/sellers/100001/questions/{questionId}/answers" \
  -H "Authorization: Basic $(echo -n 'API_KEY:API_SECRET' | base64)" \
  -H "User-Agent: 100001 - SelfIntegration" \
  -H "Content-Type: application/json" \
  -d '{"text":"Yün karışımlı nefes alan bir kumaştır, terletmez."}'

Örnek yanıt

{
  "id": "…",
  "status": "ANSWERED"
}

Hata Kodları

Hatalarda yanıt gövdesi { "status": 400, "message": "…" } formatındadır.

400	Bad Request	İstek gövdesi veya parametreler hatalı. errors alanında ayrıntı bulunur.
401	Unauthorized	Authorization ya da User-Agent başlığı eksik/hatalı veya anahtar iptal edilmiş.
403	Forbidden	Anahtar, istekteki satıcı ID'sine ait değil veya mağaza aktif değil.
404	Not Found	Uç nokta veya kayıt bulunamadı.
429	Too Many Requests	İstek limiti aşıldı.
500	Server Error	Beklenmeyen hata; isteği daha sonra tekrar deneyin.