Temel Ticaret APIinventory:writeproducts:writeAsync Batch

Stok & Fiyat API

ERP veya depo sisteminizdeki stok miktarlarını ve liste/satış fiyatlarını bağlı tüm pazaryerlerine yüksek hızlı toplu partiler (bulk batches) halinde iletin.

Asenkron Toplu Güncelleme (Batch) Akışı

Pazaryerleri toplu stok ve fiyat güncellemelerini kendi kuyruklarında işlediği için Armonika bu uçlarda HTTP 202 Accepted ve bir batch_id döndürür:

  1. 1. Paket Gönderimi (Maks 500 Kalem): Tek tek her varyant için istek atmak yerine değişen varyantları 500'lü diziler halinde POST /v1/inventory/bulk veya POST /v1/prices/bulk ucuna gönderin.
  2. 2. Sonuç Yoklama (Batch Polling): GET /v1/batches/{batch_id} ucuyla status alanının completed olmasını izleyin ve olası satır bazlı pazaryeri retlerini failures dizisinden okuyun.
Idempotency-Key ile Güvenli Yeniden Deneme
Ağ kopması durumunda aynı stok paketini güvenle tekrar gönderebilmek için isteğinize benzersiz bir Idempotency-Key (UUID) başlığı ekleyin. 24 saat içinde aynı anahtarla gelen tekrar istekler mükerrer kuyruk oluşturmadan mevcut batch_id yanıtını döner.
Batch Durum Değerleri
queued -> Sıraya alındı
processing -> Kanallara iletiliyor
completed -> Tamamlandı (failures dizisini kontrol edin)
failed -> Kanal erişim hatası nedeniyle tamamlanamadı
POST/v1/inventory/bulk

Toplu Stok Güncelleme

Basic base64(apiKey:secretKey)Kapsam: inventory:writeLimit: 60 istek / dk (maks 500 kalem/istek)

SKU veya barkod bazında tek istekte en fazla 500 varyantın stok miktarını günceller ve bağlı satış kanallarına asenkron parti (batch) olarak dağıtır. Yanıtta dönen batch_id ile işlem sonucu takip edilir.

İstek Parametreleri

AlanKonumTipZorunlulukAçıklama
Idempotency-KeyHeaderstring (uuid)OpsiyonelAğ zaman aşımında aynı toplu stok paketinin iki kez kuyruğa alınmasını önleyen opsiyonel tekillik anahtarı.
channelsBody (JSON)string[]OpsiyonelHedef kanallar (boş bırakılırsa mağazadaki tüm aktif kanallara gönderilir).
itemsBody (JSON)Array<{ barcode?: string; sku?: string; quantity: number }>Zorunlu1–500 adet stok satırı. Her satırda barcode veya sku zorunludur; quantity >= 0 tamsayı olmalıdır.

Olası Hata Kodları

HTTPHata KoduAçıklama & Çözüm
422BATCH_LIMIT_EXCEEDEDTek istekte 500'den fazla kalem gönderildi veya negatif stok değeri iletildi.
POST/v1/inventory/bulk
curl -X POST "https://api.armonika.app/v1/inventory/bulk" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-d '{
"items": [
{ "barcode": "8680001234567", "quantity": 45 },
{ "sku": "ARM-LNN-EKR-M", "quantity": 0 }
]
}'
Yanıt (Response)
HTTP/1.1 202 Accepted
{
"success": true,
"data": {
"batch_id": "bat_01JCPB2M4N6P8Q0R2S4T",
"type": "inventory_update",
"status": "processing",
"accepted_count": 2,
"queued_at": "2026-11-17T09:35:00Z"
}
}
POST/v1/prices/bulk

Toplu Liste / Satış Fiyatı Güncelleme

Basic base64(apiKey:secretKey)Kapsam: products:writeLimit: 60 istek / dk (maks 500 kalem/istek)

Varyantların liste fiyatını (list_price / üstü çizili fiyat) ve indirimli satış fiyatını (sale_price) tek istekte topluca günceller. sale_price hiçbir zaman list_price değerinden büyük olamaz.

İstek Parametreleri

AlanKonumTipZorunlulukAçıklama
channelsBody (JSON)string[]OpsiyonelOpsiyonel hedef kanal listesi (örn. ['trendyol', 'hepsiburada']).Kanal bazlı farklı fiyat politikalarında kullanılır.
itemsBody (JSON)Array<{ barcode?: string; sku?: string; list_price: number; sale_price: number; currency?: string }>Zorunlu1–500 adet fiyat güncelleme kalemi.

Olası Hata Kodları

HTTPHata KoduAçıklama & Çözüm
422INVALID_PRICE_RELATIONsale_price değeri list_price değerinden büyük gönderildi.
POST/v1/prices/bulk
curl -X POST "https://api.armonika.app/v1/prices/bulk" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"barcode": "8680001234567",
"list_price": 1799.90,
"sale_price": 1449.90,
"currency": "TRY"
}
]
}'
Yanıt (Response)
HTTP/1.1 202 Accepted
{
"success": true,
"data": {
"batch_id": "bat_01JCPC8R2T4V6X8Z0A2C",
"type": "price_update",
"status": "processing",
"accepted_count": 1,
"queued_at": "2026-11-17T09:36:12Z"
}
}
GET/v1/batches/{batch_id}

Toplu İşlem (Batch) Sonucunu Sorgula

Basic base64(apiKey:secretKey)Kapsam: inventory:write | products:writeLimit: 120 istek / dk

/v1/inventory/bulk veya /v1/prices/bulk çağrılarından dönen batch_id ile işlemin tamamlanma durumunu ve pazaryeri tarafından reddedilen satırların hata nedenlerini döndürür.

İstek Parametreleri

AlanKonumTipZorunlulukAçıklama
batch_idPathstringZorunluToplu işlem kimliği (örn. bat_01JCPB2M4N6P8Q0R2S4T).
GET/v1/batches/{batch_id}
curl -X GET "https://api.armonika.app/v1/batches/bat_01JCPB2M4N6P8Q0R2S4T" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j"
Yanıt (Response)
HTTP/1.1 200 OK
{
"success": true,
"data": {
"batch_id": "bat_01JCPB2M4N6P8Q0R2S4T",
"type": "inventory_update",
"status": "completed",
"summary": {
"total": 2,
"succeeded": 2,
"failed": 0
},
"failures": [],
"completed_at": "2026-11-17T09:35:08Z"
}
}