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.
Genel Bakış & Temel Adres (Base URL)
Tüm API istekleri yalnızca HTTPS üzerinden JSON formatında gerçekleştirilir. Düz HTTP istekleri reddedilir ve tüm tarih/saat alanları ISO 8601 (UTC) standardındadır.
Anahtarın bağlı olduğu mağazayı ve aktif pazaryeri kanallarını sorgulayın.
Çok kanallı siparişleri çekin, kargo takip no ve e-Fatura bağlantısı iletin.
Ürün oluşturun, barkod/SKU eşleşmelerini ve stok/fiyat farklarını izleyin.
Tek istekte 500 varyanta kadar toplu stok ve liste/satış fiyatı güncelleyin.
Tekilleştirilmiş müşteri profillerini ve kampanya kırılımlarını okuyun.
Sipariş ve stok değişimlerini X-Armonika-Signature imzasıyla anlık alın.
https://api.armonika.app/v1
# Zorunlu İstek Başlıkları:
Authorization: Basic <base64(apiKey:secretKey)>
Content-Type: application/json
Accept: application/jsonKimlik 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. 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) vearm_sec_...(Secret Key) çiftini oluşturun. - 2. Birleştirme & Base64 Kodlama: İki anahtarı iki nokta üst üste (
:) ileapiKey:secretKeybiçiminde birleştirin ve standart UTF-8 Base64 ile kodlayın. - 3. Header İletimi: Her HTTP isteğinde
Authorization: Basic <base64(apiKey:secretKey)>başlığını gönderin.
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:read | Siparişleri, sipariş kalemlerini ve kampanya/indirim kırılımlarını okuma. |
| orders:write | Sipariş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:write | Yeni ürün oluşturma, ürün bilgilerini güncelleme ve toplu fiyat gönderme (/v1/prices/bulk). |
| inventory:write | SKU veya barkod bazında toplu stok güncelleme (/v1/inventory/bulk) ve batch durumu sorgulama. |
| customers:read | Kanallar arası tekilleştirilmiş müşteri profillerini ve harcama kırılımlarını okuma. |
| webhooks:manage | Giden (outbound) webhook aboneliklerini listeleme, oluşturma ve silme. |
{
"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-Remaining | Mevcut pencerede kalan istek hakkınız. |
| X-RateLimit-Reset | Kotanın sıfırlanacağı Unix epoch saniyesi. |
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: 1763372460Genel Hata Kodları
Başarısız isteklerde HTTP durum kodu ile birlikte makine tarafından okunabilir sabit bir error.code döner:
| HTTP | error.code | Açıklama |
|---|---|---|
| 400 | INVALID_REQUEST | İstek gövdesi geçerli bir JSON değil veya sorgu parametreleri hatalı biçimde gönderildi. |
| 401 | INVALID_API_KEY | Authorization: Basic başlığı eksik, hatalı Base64 kodlanmış veya API Key / Secret Key çifti eşleşmiyor. |
| 401 | REVOKED_API_KEY | Kullanılan API anahtarı Mağaza Ayarları panelinden iptal edilmiş veya yenilenmiş. |
| 403 | INSUFFICIENT_SCOPE | API anahtarı geçerli ancak çağrılan uç noktanın gerektirdiği yetki kapsamına (scope) sahip değil. |
| 404 | RESOURCE_NOT_FOUND | İstenen kayıt bulunamadı veya bu API anahtarının bağlı olduğu mağazaya ait değil. |
| 409 | CONFLICT | İş kuralı çakışması (ör. iptal edilmiş siparişe kargo bildirme veya mükerrer SKU/barkod). |
| 422 | VALIDATION_ERROR | Alan doğrulama hatası (ör. sale_price > list_price veya 500 kalemlik batch limitinin aşılması). |
| 429 | RATE_LIMIT_EXCEEDED | Dakikalık istek sınırı aşıldı. X-RateLimit-Reset başlığındaki süre kadar bekleyip tekrar deneyin. |
| 500 | INTERNAL_ERROR | Armonika tarafında beklenmeyen sunucu hatası. Üstel geri çekilmeyle (exponential backoff) yeniden deneyin. |
{
"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"
}
