Toplu İşlemler (Import / Export)

Tüm ürün kataloğunu tek seferde Excel (.xlsx) veya CSV olarak dışa aktar (yedek, mutabakat, raporlama) ya da dosya yükleyerek toplu içe aktar.

Base URL: https://api.entegrasyoner.com/v1Auth: Bearer token zorunlu — Authentication.

İçe aktarım asenkrondur (202, kuyruğa girer); export senkrondur (200, dönüşte hazır). Tek-tek programatik yazım için POST /products alternatiftir — hepsi aynı yazma yolundan (marka/kategori auto-resolve dahil) geçer.

İçe Aktarım (Import)

Excel/CSV dosyası yükleyip toplu ürün yaz. Dosya kuyruğa alınır, arka planda işlenir.

POST /v1/bulk-operations/import
Authorization: Bearer <API_KEY>
Content-Type: multipart/form-data

[email protected]        # zorunlu, max 50 MB
source=excel               # zorunlu: csv | excel

Response — 202 Accepted: (iş kuyruğa alındı, henüz işlenmedi)

{
  "message": "İçe aktarım kuyruğa alındı.",
  "data": {"id": 101, "type": "product_import", "status": "queued", "has_file": true}
}

İlerlemeyi takip et: GET /v1/bulk-operations/101 (status: queued → processing → completed/failed). Satır hatalarını indir: GET /v1/bulk-operations/101/errors. Dosya şeması export ile aynıdır (aşağıdaki Products sheet).

Export

POST /v1/bulk-operations/export
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "format": "xlsx",
  "filter": {"brand_id": 12, "status": true}
}

format: csv veya xlsx. filter opsiyonel — products liste filtreleri ile aynı.

Response — 200 OK: (export senkron biter, dönüşte completed)

{
  "message": "Dışa aktarım tamamlandı.",
  "data": {"id": 100, "type": "product_export", "status": "completed", "has_file": true}
}

Dosya hemen hazırdır → GET /v1/bulk-operations/100/result ile indir (binary). Export için status polling gerekmez.

Export dosya şeması

Sheet 1 — Products (CSV'de tek tablo)

Kolonlar, üretildikleri sıraya göre:

sync_id | product_id | model | sku | ean | name | status |
brand_id | category_ids |
price | tax_rate | price_with_vat |
stock | <mağaza kodu 1> | <mağaza kodu 2> | ...

Kolon	Açıklama
sync_id	Ürünün Entegrasyoner iç id'si (string).
product_id	Ürün id'si (eşleme/güncelleme için stabil identifier).
model	Ürün kodu (Opencart vb. kaynaktan gelir).
sku, ean	Stok kodu / barkod.
name, status	Ad / aktiflik (1/0).
brand_id	Marka id'si. İsmi Brands sheet'inden bakılır.
category_ids	Çoklu kategori, pipe (|) ayraçlı: "45|67|89". İsimleri Categories sheet'inden bakılır.
price	KDV-hariç fiyat.
tax_rate	KDV oranı (%).
price_with_vat	KDV-dahil fiyat (hesaplanmış).
stock	Genel (varsayılan lokasyon) stok.
<mağaza kodu>	Her aktif mağaza lokasyonu için ayrı kolon (kod başlık olur), o mağazanın stoğu.

Üründe brand/category isimleri Products sheet'inde yoktur — yalnızca brand_id / category_ids vardır. Okunabilir adlar aşağıdaki lookup sheet'lerindedir.

xlsx lookup sheet'leri (yalnız referans)

xlsx'te iki ek sheet bulunur (CSV'de yoktur):

• Brands — kolonlar: id, name, normalized_name.
• Categories — kolonlar: id, parent_id, name, path (örn. Electronics > Smartphones).

İndir

GET /v1/bulk-operations/100/result      # sonuç dosyası (binary)
GET /v1/bulk-operations/100             # durum / metadata (JSON)
GET /v1/bulk-operations/100/errors      # hata satırları (import için)

GET /v1/bulk-operations geçmiş import/export kayıtlarını listeler.

Sil

Tamamlanmış (veya başarısız) bir işlemi ve dosyalarını kaldır:

DELETE /v1/bulk-operations/100
Authorization: Bearer <API_KEY>

Devam eden (queued/processing) işlem silinemez → 409. Başarılıysa 200: {"message": "Silindi."}.

Hata kodları (özet)

HTTP	Senaryo
401	Token eksik/geçersiz
404	id bulunamadı (veya başka tenant'a ait)
422	Geçersiz format veya filtre parametresi
5xx	Sunucu hatası — geçici

Detaylı: errors.