Temel Ticaret APIproducts:readproducts:write

Ürünler & Katalog API

Ana ürün kataloğunuzu ve varyantlarınızı yönetin, barkod/SKU bazlı pazaryeri eşleşmelerini sorgulayın ve kanallar arası stok/fiyat uyumsuzluklarını tespit edin.

Katalog Yapısı & Kanal Eşleşme Mimarisi

Armonika'da her ürün bir model_code altında gruplanan bir veya daha fazla satılabilir varyanttan (beden, renk vb.) oluşur. Varyantlar bağlı pazaryerlerindeki ilanlarla şu öncelik sırasıyla eşleştirilir:

  1. 1. Barcode (GTIN / EAN): Önce tekil barkod eşleşmesi aranır.
  2. 2. SKU (Stok Kodu): Barkod eşleşmezse satıcı stok koduna (SKU) bakılır.
  3. 3. Manual (Elle Eşleştirme): Panel üzerinden elle bağlanan varyantlar otomatik senkronlarda korunur.
Stok ve Fiyat Güncellemeleri İçin Toplu Uçları Kullanın
PATCH /v1/products/{product_id} ucu başlık, açıklama ve durum gibi katalog bilgileri içindir. Sık değişen stok ve fiyat güncellemeleri için yüksek kapasiteli POST /v1/inventory/bulk ve POST /v1/prices/bulk uçlarını tercih edin.
Eşleşme Yöntemleri (match_method)
{
"variant_id": "var_01JA9M2R8K1N3P5Q7S9U",
"sku": "ARM-SWT-BLK-M",
"barcode": "8680001234567",
"mappings": [
{ "channel": "shopify", "match_method": "primary" },
{ "channel": "trendyol", "match_method": "barcode" },
{ "channel": "hepsiburada", "match_method": "sku" },
{ "channel": "boyner", "match_method": "manual" }
]
}
GET/v1/products

Ürün Kataloğunu Listele

Basic base64(apiKey:secretKey)Kapsam: products:readLimit: 120 istek / dk

Mağaza kataloğundaki ana ürünleri, varyant özetlerini, toplam stoklarını ve kanal eşleşme sayılarını imleçli olarak döndürür.

İstek Parametreleri

AlanKonumTipZorunlulukAçıklama
statusQuery'active' | 'draft' | 'archived'OpsiyonelÜrün yayın durumu filtresi.
qQuerystringOpsiyonelÜrün başlığı, model kodu, SKU veya barkod araması.
brandQuerystringOpsiyonelMarka adına göre filtrele.
cursorQuerystringOpsiyonelSonraki sayfa için pagination.next_cursor değeri.
limitQueryinteger (1–100)Vars: 50Sayfa boyutu.
GET/v1/products
curl -X GET "https://api.armonika.app/v1/products?status=active&limit=25" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j"
Yanıt (Response)
HTTP/1.1 200 OK
{
"success": true,
"data": [
{
"id": "prd_01JA9M2K4P6R8T0V2X4Z",
"model_code": "ARM-SWT-2026",
"title": "Oversize Pamuklu Sweatshirt",
"brand": "Armonika",
"category": "Üst Giyim > Sweatshirt",
"status": "active",
"variant_count": 4,
"total_stock": 148,
"price_range": { "min": 1499.9, "max": 1499.9, "currency": "TRY" },
"mapped_channels": ["shopify", "trendyol", "hepsiburada"],
"updated_at": "2026-11-17T08:45:00Z"
}
],
"pagination": {
"limit": 25,
"has_more": false,
"next_cursor": null
}
}
GET/v1/products/{product_id}

Tekil Ürün ve Varyant Detaylarını Getir

Basic base64(apiKey:secretKey)Kapsam: products:readLimit: 120 istek / dk

Ürünün açıklaması, görselleri, tüm varyantları (beden/renk seçenekleri, barkod, SKU, stok, liste/satış fiyatı) ve bağlı pazaryeri eşleşmelerini döndürür.

İstek Parametreleri

AlanKonumTipZorunlulukAçıklama
product_idPathstringZorunluArmonika tekil ürün kimliği (örn. prd_01JA9M2K4P6R8T0V2X4Z).
GET/v1/products/{product_id}
curl -X GET "https://api.armonika.app/v1/products/prd_01JA9M2K4P6R8T0V2X4Z" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j"
Yanıt (Response)
HTTP/1.1 200 OK
{
"success": true,
"data": {
"id": "prd_01JA9M2K4P6R8T0V2X4Z",
"model_code": "ARM-SWT-2026",
"title": "Oversize Pamuklu Sweatshirt",
"brand": "Armonika",
"vat_rate": 10,
"status": "active",
"variants": [
{
"id": "var_01JA9M2R8K1N3P5Q7S9U",
"sku": "ARM-SWT-BLK-M",
"barcode": "8680001234567",
"options": { "Renk": "Siyah", "Beden": "M" },
"stock": 42,
"list_price": 1799.9,
"sale_price": 1499.9
}
]
}
}
POST/v1/products

Yeni Ürün Oluştur

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

Mağaza kataloğuna varyantlarıyla birlikte yeni bir ürün ekler. Barkod veya SKU mevcut kanal ürünleriyle eşleşiyorsa otomatik kanal eşleştirmesi tetiklenir.

İstek Parametreleri

AlanKonumTipZorunlulukAçıklama
titleBody (JSON)stringZorunluÜrün başlığı (2–250 karakter).
model_codeBody (JSON)stringZorunluAna model / grup kodu (varyantları gruplamak için kullanılır).
brandBody (JSON)stringZorunluMarka adı.
vat_rateBody (JSON)0 | 1 | 10 | 20Vars: 20KDV oranı (%).
variantsBody (JSON)VariantInput[]ZorunluEn az 1 varyant içeren dizi: { sku, barcode, stock, list_price, sale_price, options }.

Olası Hata Kodları

HTTPHata KoduAçıklama & Çözüm
409DUPLICATE_SKU_OR_BARCODEGönderilen SKU veya barkod mağaza kataloğunda başka bir varyantta zaten kayıtlı.
POST/v1/products
curl -X POST "https://api.armonika.app/v1/products" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j" \
-H "Content-Type: application/json" \
-d '{
"title": "Keten Yazlık Gömlek",
"model_code": "ARM-LNN-2026",
"brand": "Armonika",
"vat_rate": 10,
"variants": [
{
"sku": "ARM-LNN-EKR-M",
"barcode": "8680009876543",
"stock": 30,
"list_price": 1999.0,
"sale_price": 1699.0,
"options": { "Renk": "Ekru", "Beden": "M" }
}
]
}'
Yanıt (Response)
HTTP/1.1 201 Created
{
"success": true,
"data": {
"id": "prd_01JCP9A1B2C3D4E5F6G7",
"model_code": "ARM-LNN-2026",
"status": "active",
"variant_count": 1
}
}
PATCH/v1/products/{product_id}

Ürün Bilgilerini Güncelle

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

Ürünün başlık, açıklama, marka, KDV oranı, görsel listesi veya yayın durumunu kısmi olarak günceller. (Yüksek hacimli stok/fiyat güncellemeleri için /v1/inventory/bulk ve /v1/prices/bulk uçlarını kullanın.)

İstek Parametreleri

AlanKonumTipZorunlulukAçıklama
product_idPathstringZorunluGüncellenecek ürün kimliği.
titleBody (JSON)stringOpsiyonelYeni ürün başlığı.
description_htmlBody (JSON)stringOpsiyonelÜrün açıklaması (temiz HTML).
statusBody (JSON)'active' | 'draft' | 'archived'OpsiyonelYayın durumu.
PATCH/v1/products/{product_id}
curl -X PATCH "https://api.armonika.app/v1/products/prd_01JA9M2K4P6R8T0V2X4Z" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j" \
-H "Content-Type: application/json" \
-d '{"title": "Oversize %100 Organik Pamuklu Sweatshirt", "status": "active"}'
Yanıt (Response)
HTTP/1.1 200 OK
{
"success": true,
"data": {
"id": "prd_01JA9M2K4P6R8T0V2X4Z",
"title": "Oversize %100 Organik Pamuklu Sweatshirt",
"status": "active",
"updated_at": "2026-11-17T09:32:00Z"
}
}
GET/v1/products/mappings

Barkod / SKU Kanal Eşleşmelerini Listele

Basic base64(apiKey:secretKey)Kapsam: products:readLimit: 120 istek / dk

Ana katalog varyantlarının bağlı pazaryerlerindeki (Trendyol, Hepsiburada, Boyner, Beymen) karşılıklarını ve eşleşme yöntemini (barcode, sku veya manual) döndürür.

İstek Parametreleri

AlanKonumTipZorunlulukAçıklama
channelQuerystringOpsiyonelPazaryeri filtresi: trendyol, hepsiburada, boyner, beymen.
stateQuery'matched' | 'unmatched'OpsiyonelYalnızca eşleşmiş veya henüz eşleşmemiş kayıtları filtreler.
barcodeQuerystringOpsiyonelBelirli bir barkodu sorgula.
GET/v1/products/mappings
curl -X GET "https://api.armonika.app/v1/products/mappings?channel=trendyol&state=matched" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j"
Yanıt (Response)
HTTP/1.1 200 OK
{
"success": true,
"data": [
{
"variant_id": "var_01JA9M2R8K1N3P5Q7S9U",
"sku": "ARM-SWT-BLK-M",
"barcode": "8680001234567",
"channel": "trendyol",
"channel_listing_id": "8680001234567",
"match_method": "barcode",
"matched_at": "2026-10-12T14:20:00Z"
}
],
"pagination": { "limit": 50, "has_more": false, "next_cursor": null }
}
GET/v1/products/discrepancies

Kanallar Arası Stok ve Fiyat Farklarını Getir

Basic base64(apiKey:secretKey)Kapsam: products:readLimit: 120 istek / dk

Ana stok/fiyat kaynağı ile pazaryerlerindeki canlı ilanlar arasında oluşan stok adedi veya satış fiyatı uyumsuzluklarını listeler.

İstek Parametreleri

AlanKonumTipZorunlulukAçıklama
channelQuerystringOpsiyonelKanal filtresi (örn. trendyol, hepsiburada).
typeQuery'stock' | 'price'OpsiyonelYalnızca stok veya yalnızca fiyat farklarını getirir.
GET/v1/products/discrepancies
curl -X GET "https://api.armonika.app/v1/products/discrepancies?type=stock" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j"
Yanıt (Response)
HTTP/1.1 200 OK
{
"success": true,
"data": [
{
"variant_id": "var_01JA9M2R8K1N3P5Q7S9U",
"sku": "ARM-SWT-BLK-M",
"barcode": "8680001234567",
"channel": "trendyol",
"expected_stock": 42,
"channel_stock": 39,
"expected_sale_price": 1499.9,
"channel_sale_price": 1499.9,
"detected_at": "2026-11-17T09:10:00Z"
}
],
"pagination": { "limit": 50, "has_more": false, "next_cursor": null }
}