BaşlangıçREST API v1HTTPS / JSONBasic Auth (API Key + Secret)

Armonika Geliştirici API Rehberi

Armonika REST API; ERP, ön muhasebe, depo yönetim sistemi (WMS) ve özel e-ticaret yazılımlarınızı Trendyol, Hepsiburada, Shopify, Boyner ve Beymen mağazalarınızla tek bir standart arayüz üzerinden entegre etmenizi sağlar.

Kimlik Doğrulama (Mağaza API Key + Secret Key)

Armonika dış geliştirici API'si mağaza kapsamlı HTTP Basic kimlik doğrulaması kullanır. Her anahtar çifti doğrudan tek bir mağazaya bağlıdır; bu nedenle isteklerde ayrıca mağaza ID başlığı, çerez (cookie) veya kullanıcı oturumu gönderilmez.

  1. 1. Anahtar Üretimi: armonika.app panelinde Mağaza Ayarları → API Anahtarları sayfasından gerekli yetki kapsamlarını seçerek mağazanıza özel arm_... (API Key) ve arm_sec_... (Secret Key) çiftini oluşturun.
  2. 2. Birleştirme & Base64 Kodlama: İki anahtarı iki nokta üst üste (:) ile apiKey:secretKey biçiminde birleştirin ve standart UTF-8 Base64 ile kodlayın.
  3. 3. Header İletimi: Her HTTP isteğinde Authorization: Basic <base64(apiKey:secretKey)> başlığını gönderin.
Secret Key Güvenliği
Secret Key (arm_sec_...) yalnızca oluşturulduğu anda bir kez gösterilir ve yalnızca sunucu tarafında saklanmalıdır. Tarayıcı (frontend) koduna, mobil uygulamalara veya genel Git depolarına asla gömmeyin.
const apiKey = process.env.ARMONIKA_API_KEY!;     // "arm_9f8a7b6c5d4e"
const secretKey = process.env.ARMONIKA_SECRET_KEY!; // "arm_sec_1a2b3c4d5e6f7g8h9i0j"

// 1. "apiKey:secretKey" birleştirip Base64'e çevir:
const credentials = Buffer.from(`${apiKey}:${secretKey}`, "utf8").toString("base64");

// 2. Authorization: Basic başlığıyla gönder:
const response = await fetch("https://api.armonika.app/v1/orders?limit=10", {
  method: "GET",
  headers: {
    Authorization: `Basic ${credentials}`,
    Accept: "application/json",
  },
});

const payload = await response.json();

Yetki Kapsamları (Scopes)

En az ayrıcalık (least privilege) ilkesi gereği her entegrasyon için ayrı bir API anahtarı oluşturmanız ve yalnızca ihtiyaç duyulan kapsamları işaretlemeniz önerilir. Eksik kapsamla yapılan çağrılar 403 INSUFFICIENT_SCOPE döner.

Kapsam (Scope)Erişim İzni
orders:readSiparişleri, sipariş kalemlerini ve kampanya/indirim kırılımlarını okuma.
orders:writeSiparişlere kargo takip numarası ve e-Fatura / e-Arşiv belgesi işleme.
products:readÜrün kataloğunu, varyantları, kanal eşleşmelerini ve stok/fiyat farklarını okuma.
products:writeYeni ürün oluşturma, ürün bilgilerini güncelleme ve toplu fiyat gönderme (/v1/prices/bulk).
inventory:writeSKU veya barkod bazında toplu stok güncelleme (/v1/inventory/bulk) ve batch durumu sorgulama.
customers:readKanallar arası tekilleştirilmiş müşteri profillerini ve harcama kırılımlarını okuma.
webhooks:manageGiden (outbound) webhook aboneliklerini listeleme, oluşturma ve silme.
403 Yetersiz Yetki Yanıtı
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This API key requires the 'inventory:write' scope to perform this action.",
    "required_scope": "inventory:write"
  }
}

Standart Yanıt Zarfı & Cursor Sayfalama

Tüm uç noktalar üst düzeyde boolean success alanı içeren standart bir JSON zarfı döndürür. Liste uçları yüksek hacimli katalog ve siparişlerde sabit okuma performansı sağlamak için sayfa numarası (page/offset) yerine imleçli sayfalama (cursor pagination) kullanır.

  • • limit: Sayfa başına kayıt sayısı (varsayılan 50, maksimum 100).
  • • pagination.has_more: true olduğu sürece bir sonraki sayfa mevcuttur.
  • • pagination.next_cursor: Sonraki isteğin ?cursor= sorgu parametresine olduğu gibi iletilir.
{
  "success": true,
  "data": [
    { "id": "ord_01JCP7Y8N2K4M6R8T0V2", "...": "..." }
  ],
  "pagination": {
    "limit": 50,
    "has_more": true,
    "next_cursor": "cur_eyJvcmRlcmVkX2F0IjoiMjAyNi0xMS0xN1QwODoxNTowMFoifQ"
  }
}

Hız Sınırları (Rate Limiting)

Hız sınırları mağaza başına kayan 1 dakikalık pencerelerle uygulanır. Her HTTP yanıtında kalan kotanızı izleyebileceğiniz standart başlıklar döner:

HTTP BaşlığıAnlamı
X-RateLimit-Limitİlgili uç nokta grubu için dakikada izin verilen toplam istek sayısı (okuma: 120/dk, yazma: 60/dk).
X-RateLimit-RemainingMevcut pencerede kalan istek hakkınız.
X-RateLimit-ResetKotanın sıfırlanacağı Unix epoch saniyesi.
Örnek Rate Limit Yanıt Başlıkları
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 114
X-RateLimit-Reset: 1763372460

# Kota aşıldığında (429 Too Many Requests):
HTTP/1.1 429 Too Many Requests
Retry-After: 18
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1763372460

Genel Hata Kodları

Başarısız isteklerde HTTP durum kodu ile birlikte makine tarafından okunabilir sabit bir error.code döner:

HTTPerror.codeAçıklama
400INVALID_REQUESTİstek gövdesi geçerli bir JSON değil veya sorgu parametreleri hatalı biçimde gönderildi.
401INVALID_API_KEYAuthorization: Basic başlığı eksik, hatalı Base64 kodlanmış veya API Key / Secret Key çifti eşleşmiyor.
401REVOKED_API_KEYKullanılan API anahtarı Mağaza Ayarları panelinden iptal edilmiş veya yenilenmiş.
403INSUFFICIENT_SCOPEAPI anahtarı geçerli ancak çağrılan uç noktanın gerektirdiği yetki kapsamına (scope) sahip değil.
404RESOURCE_NOT_FOUNDİstenen kayıt bulunamadı veya bu API anahtarının bağlı olduğu mağazaya ait değil.
409CONFLICTİş kuralı çakışması (ör. iptal edilmiş siparişe kargo bildirme veya mükerrer SKU/barkod).
422VALIDATION_ERRORAlan doğrulama hatası (ör. sale_price > list_price veya 500 kalemlik batch limitinin aşılması).
429RATE_LIMIT_EXCEEDEDDakikalık istek sınırı aşıldı. X-RateLimit-Reset başlığındaki süre kadar bekleyip tekrar deneyin.
500INTERNAL_ERRORArmonika tarafında beklenmeyen sunucu hatası. Üstel geri çekilmeyle (exponential backoff) yeniden deneyin.
Standart Hata Zarfı
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [
      {
        "field": "items[0].sale_price",
        "issue": "sale_price must be less than or equal to list_price"
      }
    ]
  },
  "request_id": "req_01JCPDF7K9M2N4P6Q8R0"
}