Temel Ticaret APIorders:readorders:write

Siparişler API

Trendyol, Hepsiburada, Shopify, Boyner ve Beymen siparişlerini tek bir ortak finansal şemada okuyun; kargo takip numaralarını ve e-Fatura / e-Arşiv belgelerinizi ilgili kanallara iletin.

Ortak Sipariş Ciro & İndirim Formülü

Pazaryerlerinde alıcının ödediği tutar ile satıcının hak ettiği fatura/ciro tutarı, pazaryerinin kendi bütçesinden uyguladığı kampanyalar nedeniyle farklılaşabilir. Armonika tüm kanallarda standart bir muhasebe kuralı uygular:

total_amount = subtotal − seller_discount
AlanMuhasebe Karşılığı
subtotalİndirim öncesi brüt satış tutarı.
seller_discountSatıcının kendi bütçesinden yaptığı indirim / kupon — satıcı cirosunu düşürür.
platform_discountPazaryerinin kendi bütçesinden karşıladığı indirim — satıcı faturasını/cirosunu düşürmez.
total_amountSatıcının müşteriye keseceği net fatura / satış cirosu tutarı.
Artımlı Senkronizasyon Önerisi
Periyodik ERP çekimlerinde son başarılı eşitleme zamanınızı saklayıp GET /v1/orders?updated_after=<ISO_TARIH> parametresiyle yalnızca yeni ve durumu değişen siparişleri çekin; anlık bildirimler için Webhook aboneliği kurun.
Sipariş Durum Yaşam Döngüsü
pending -> Ödeme / onay bekliyor
processing -> Hazırlanıyor / paketleniyor
shipped -> Kargoya verildi
delivered -> Müşteriye teslim edildi
cancelled -> İptal edildi
returned -> İade alındı
GET/v1/orders

Siparişleri Listele

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

Mağazanın tüm bağlı kanallarından gelen siparişleri tek bir ortak şemada (NormalizedOrder) imleçli sayfalama ile döndürür. ERP veya muhasebe entegrasyonlarında artımlı çekim için updated_after filtresini kullanın.

İstek Parametreleri

AlanKonumTipZorunlulukAçıklama
channelQuerystringOpsiyonelKanal filtresi: trendyol, hepsiburada, shopify, boyner, beymen (virgülle çoklu verilebilir).
statusQuerystringOpsiyonelSipariş durumu: pending, processing, shipped, delivered, cancelled, returned.
created_afterQueryISO 8601 datetimeOpsiyonelBelirtilen tarihten sonra oluşturulan siparişleri getirir (örn. 2026-11-01T00:00:00Z).
updated_afterQueryISO 8601 datetimeOpsiyonelBelirtilen tarihten sonra durumu veya kargo bilgisi güncellenen siparişleri getirir.
cursorQuerystringOpsiyonelBir önceki yanıtın pagination.next_cursor alanından alınan sayfalama imleci.
limitQueryinteger (1–100)Vars: 50Sayfa başına döndürülecek maksimum sipariş sayısı.

Olası Hata Kodları

HTTPHata KoduAçıklama & Çözüm
403INSUFFICIENT_SCOPEAPI anahtarında orders:read yetki kapsamı tanımlı değil.
GET/v1/orders
curl -X GET "https://api.armonika.app/v1/orders?channel=trendyol,shopify&status=processing&limit=25" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j"
Yanıt (Response)
HTTP/1.1 200 OK
{
"success": true,
"data": [
{
"id": "ord_01JCP7Y8N2K4M6R8T0V2",
"channel": "trendyol",
"channel_order_id": "918273645",
"order_number": "1029384756",
"status": "processing",
"currency": "TRY",
"subtotal": 1500.0,
"seller_discount": 150.0,
"platform_discount": 100.0,
"shipping_total": 0.0,
"total_amount": 1350.0,
"customer": {
"id": "cus_01JB8W4X9Z1A3C5E7G9",
"full_name": "Zeynep Kaya",
"city": "İstanbul",
"district": "Kadıköy"
},
"ordered_at": "2026-11-17T08:15:00Z",
"updated_at": "2026-11-17T08:16:10Z"
}
],
"pagination": {
"limit": 25,
"has_more": true,
"next_cursor": "cur_eyJvcmRlcmVkX2F0IjoiMjAyNi0xMS0xN1QwODoxNTowMFoifQ"
}
}
GET/v1/orders/{order_id}

Tekil Sipariş Detayını Getir

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

Siparişin satır kalemlerini (SKU, barkod, KDV oranı, birim fiyat), satıcı/pazaryeri indirim kırılımlarını, teslimat/fatura adresini ve mevcut kargo/fatura durumunu döndürür.

İstek Parametreleri

AlanKonumTipZorunlulukAçıklama
order_idPathstringZorunluArmonika tekil sipariş kimliği (örn. ord_01JCP7Y8N2K4M6R8T0V2).

Olası Hata Kodları

HTTPHata KoduAçıklama & Çözüm
404ORDER_NOT_FOUNDSipariş bulunamadı veya bu API anahtarının bağlı olduğu mağazaya ait değil.
GET/v1/orders/{order_id}
curl -X GET "https://api.armonika.app/v1/orders/ord_01JCP7Y8N2K4M6R8T0V2" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j"
Yanıt (Response)
HTTP/1.1 200 OK
{
"success": true,
"data": {
"id": "ord_01JCP7Y8N2K4M6R8T0V2",
"channel": "trendyol",
"order_number": "1029384756",
"status": "processing",
"currency": "TRY",
"subtotal": 1500.0,
"seller_discount": 150.0,
"platform_discount": 100.0,
"total_amount": 1350.0,
"shipping_address": {
"recipient_name": "Zeynep Kaya",
"phone": "+905551234567",
"address_line": "Caferağa Mah. Moda Cad. No: 24 D: 5",
"district": "Kadıköy",
"city": "İstanbul",
"postal_code": "34710",
"country_code": "TR"
},
"items": [
{
"line_id": "lin_991827",
"sku": "ARM-SWT-BLK-M",
"barcode": "8680001234567",
"title": "Oversize Pamuklu Sweatshirt - Siyah / M",
"quantity": 1,
"unit_price": 1500.0,
"seller_discount": 150.0,
"net_total": 1350.0,
"vat_rate": 10
}
],
"discounts": [
{ "source": "coupon", "code": "YAZ10", "amount": 150.0 },
{ "source": "platform", "code": null, "amount": 100.0 }
],
"shipment": null,
"invoice": null
}
}
POST/v1/orders/{order_id}/shipment

Kargo Takip Bilgisi Bildir

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

Siparişin kargo firmasını, takip numarasını ve opsiyonel takip bağlantısını Armonika'ya ve ilgili satış kanalına (Shopify, Trendyol, Hepsiburada vb.) iletir; sipariş durumunu shipped olarak günceller.

İstek Parametreleri

AlanKonumTipZorunlulukAçıklama
order_idPathstringZorunluKargo bildirimi yapılacak siparişin kimliği.
carrier_codeBody (JSON)stringZorunluKargo firması kodu: yurtici, aras, hepsijet, mng, surat, ptt, ups, dhl.
tracking_numberBody (JSON)stringZorunluKargo takip numarası.
tracking_urlBody (JSON)string (url)OpsiyonelMüşterinin kargoyu izleyebileceği doğrudan takip bağlantısı (opsiyonel).
notify_customerBody (JSON)booleanVars: trueDestekleyen kanallarda (örn. Shopify) müşteriye kargo bildirimi gönderilsin mi.

Olası Hata Kodları

HTTPHata KoduAçıklama & Çözüm
409ORDER_NOT_SHIPPABLEİptal edilmiş (cancelled) veya iade edilmiş (returned) siparişe kargo bildirilemez.
POST/v1/orders/{order_id}/shipment
curl -X POST "https://api.armonika.app/v1/orders/ord_01JCP7Y8N2K4M6R8T0V2/shipment" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j" \
-H "Content-Type: application/json" \
-d '{
"carrier_code": "yurtici",
"tracking_number": "908172635412",
"tracking_url": "https://www.yurticikargo.com/tr/online-servisler/gonderi-sorgula?code=908172635412",
"notify_customer": true
}'
Yanıt (Response)
HTTP/1.1 200 OK
{
"success": true,
"data": {
"order_id": "ord_01JCP7Y8N2K4M6R8T0V2",
"status": "shipped",
"shipment": {
"carrier_code": "yurtici",
"tracking_number": "908172635412",
"synced_to_channel": true,
"shipped_at": "2026-11-17T09:30:00Z"
}
}
}
POST/v1/orders/{order_id}/invoice

Siparişe e-Fatura / e-Arşiv Bağlantısı İşle

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

ERP veya entegratör yazılımınızda kesilen resmi e-Fatura / e-Arşiv belgesinin numarasını ve PDF/XML erişim adresini siparişe kaydeder ve zorunlu tutan pazaryerlerine (Trendyol, Hepsiburada vb.) otomatik iletir.

İstek Parametreleri

AlanKonumTipZorunlulukAçıklama
order_idPathstringZorunluFatura eklenecek sipariş kimliği.
invoice_numberBody (JSON)string (16 karakter GİB no)ZorunluResmi fatura numarası (örn. ARM2026000001482).
invoice_typeBody (JSON)'e_archive' | 'e_invoice'ZorunluFatura türü (e-Arşiv veya Kurumsal e-Fatura).
pdf_urlBody (JSON)string (https url)ZorunluPazaryerinin indirebileceği HTTPS fatura PDF adresi.
issued_atBody (JSON)ISO 8601 datetimeZorunluFatura düzenlenme tarihi ve saati.

Olası Hata Kodları

HTTPHata KoduAçıklama & Çözüm
422INVALID_INVOICE_URLpdf_url geçerli bir HTTPS adresi değil veya pazaryeri tarafından erişilemiyor.
POST/v1/orders/{order_id}/invoice
curl -X POST "https://api.armonika.app/v1/orders/ord_01JCP7Y8N2K4M6R8T0V2/invoice" \
-u "arm_9f8a7b6c5d4e:arm_sec_1a2b3c4d5e6f7g8h9i0j" \
-H "Content-Type: application/json" \
-d '{
"invoice_number": "ARM2026000001482",
"invoice_type": "e_archive",
"pdf_url": "https://cdn.ornek-erp.com/invoices/ARM2026000001482.pdf",
"issued_at": "2026-11-17T09:25:00Z"
}'
Yanıt (Response)
HTTP/1.1 200 OK
{
"success": true,
"data": {
"order_id": "ord_01JCP7Y8N2K4M6R8T0V2",
"invoice_number": "ARM2026000001482",
"synced_to_channel": true
}
}