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:
| Alan | Muhasebe Karşılığı |
|---|---|
| subtotal | İndirim öncesi brüt satış tutarı. |
| seller_discount | Satıcının kendi bütçesinden yaptığı indirim / kupon — satıcı cirosunu düşürür. |
| platform_discount | Pazaryerinin kendi bütçesinden karşıladığı indirim — satıcı faturasını/cirosunu düşürmez. |
| total_amount | Satıcının müşteriye keseceği net fatura / satış cirosu tutarı. |
/v1/ordersSiparişleri Listele
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
| Alan | Konum | Tip | Zorunluluk | Açıklama |
|---|---|---|---|---|
| channel | Query | string | Opsiyonel | Kanal filtresi: trendyol, hepsiburada, shopify, boyner, beymen (virgülle çoklu verilebilir). |
| status | Query | string | Opsiyonel | Sipariş durumu: pending, processing, shipped, delivered, cancelled, returned. |
| created_after | Query | ISO 8601 datetime | Opsiyonel | Belirtilen tarihten sonra oluşturulan siparişleri getirir (örn. 2026-11-01T00:00:00Z). |
| updated_after | Query | ISO 8601 datetime | Opsiyonel | Belirtilen tarihten sonra durumu veya kargo bilgisi güncellenen siparişleri getirir. |
| cursor | Query | string | Opsiyonel | Bir önceki yanıtın pagination.next_cursor alanından alınan sayfalama imleci. |
| limit | Query | integer (1–100) | Vars: 50 | Sayfa başına döndürülecek maksimum sipariş sayısı. |
Olası Hata Kodları
| HTTP | Hata Kodu | Açıklama & Çözüm |
|---|---|---|
| 403 | INSUFFICIENT_SCOPE | API anahtarında orders:read yetki kapsamı tanımlı değil. |
/v1/orders/v1/orders/{order_id}Tekil Sipariş Detayını Getir
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
| Alan | Konum | Tip | Zorunluluk | Açıklama |
|---|---|---|---|---|
| order_id | Path | string | Zorunlu | Armonika tekil sipariş kimliği (örn. ord_01JCP7Y8N2K4M6R8T0V2). |
Olası Hata Kodları
| HTTP | Hata Kodu | Açıklama & Çözüm |
|---|---|---|
| 404 | ORDER_NOT_FOUND | Sipariş bulunamadı veya bu API anahtarının bağlı olduğu mağazaya ait değil. |
/v1/orders/{order_id}/v1/orders/{order_id}/shipmentKargo Takip Bilgisi Bildir
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
| Alan | Konum | Tip | Zorunluluk | Açıklama |
|---|---|---|---|---|
| order_id | Path | string | Zorunlu | Kargo bildirimi yapılacak siparişin kimliği. |
| carrier_code | Body (JSON) | string | Zorunlu | Kargo firması kodu: yurtici, aras, hepsijet, mng, surat, ptt, ups, dhl. |
| tracking_number | Body (JSON) | string | Zorunlu | Kargo takip numarası. |
| tracking_url | Body (JSON) | string (url) | Opsiyonel | Müşterinin kargoyu izleyebileceği doğrudan takip bağlantısı (opsiyonel). |
| notify_customer | Body (JSON) | boolean | Vars: true | Destekleyen kanallarda (örn. Shopify) müşteriye kargo bildirimi gönderilsin mi. |
Olası Hata Kodları
| HTTP | Hata Kodu | Açıklama & Çözüm |
|---|---|---|
| 409 | ORDER_NOT_SHIPPABLE | İptal edilmiş (cancelled) veya iade edilmiş (returned) siparişe kargo bildirilemez. |
/v1/orders/{order_id}/shipment/v1/orders/{order_id}/invoiceSiparişe e-Fatura / e-Arşiv Bağlantısı İşle
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
| Alan | Konum | Tip | Zorunluluk | Açıklama |
|---|---|---|---|---|
| order_id | Path | string | Zorunlu | Fatura eklenecek sipariş kimliği. |
| invoice_number | Body (JSON) | string (16 karakter GİB no) | Zorunlu | Resmi fatura numarası (örn. ARM2026000001482). |
| invoice_type | Body (JSON) | 'e_archive' | 'e_invoice' | Zorunlu | Fatura türü (e-Arşiv veya Kurumsal e-Fatura). |
| pdf_url | Body (JSON) | string (https url) | Zorunlu | Pazaryerinin indirebileceği HTTPS fatura PDF adresi. |
| issued_at | Body (JSON) | ISO 8601 datetime | Zorunlu | Fatura düzenlenme tarihi ve saati. |
Olası Hata Kodları
| HTTP | Hata Kodu | Açıklama & Çözüm |
|---|---|---|
| 422 | INVALID_INVOICE_URL | pdf_url geçerli bir HTTPS adresi değil veya pazaryeri tarafından erişilemiyor. |
/v1/orders/{order_id}/invoice
