Shopify siparişleri

Shopify kullanan bir mağazada siparişlerin Sayproof’a ulaşması için kod yazılması gerekmez. Sayproof, mağazanıza kurduğunuz bir Shopify uygulamasının bilgileriyle Shopify Admin API’sine bağlanır ve yeni ya da değişen siparişleri belli aralıklarla (varsayılan olarak 15 dakikada bir) kendisi okur. Okunan siparişler, mağaza sisteminden gönderilen siparişlerle aynı biçimde kaydedilir; yorum yazma hakkı ve davetler aynı kurallarla çalışır.

Bu sayfadaki Shopify ekran adları İngilizce yönetim panelindeki adlardır; Shopify yönetiminiz Türkçeyse aynı yerler Türkçe adlarıyla görünür.

Ne zaman kullanılır

• Mağazanız Shopify üzerindeyse bu sayfadaki bağlantıyı kurun.
• Hazır bağlantısı olmayan bir sistem kullanıyorsanız siparişleri mağaza sisteminiz gönderir: Sipariş ve teslimat aktarımı.

Panelde iki yol Entegrasyon › Sipariş aktarımı sekmesinde alt alta gösterilir: Platformdan okuma ve Mağazadan gönderim.

Gerekenler

Bilgi	Açıklama
Shopify mağaza adresi	Mağazanızın myshopify.com adresi, örneğin markaniz.myshopify.com. Shopify yönetiminde Settings › Domains altında görünür. https:// yazmanız gerekmez; yazılırsa yalnızca alan adı kullanılır. Kendi alan adınız (markaniz.com) ya da admin.shopify.com adresi kabul edilmez.
Client ID ve Client secret	Bu iş için Shopify Dev Dashboard’da açtığınız ve mağazanıza kurduğunuz uygulamanın bilgileri. Uygulamanın yalnızca read_orders izni olması yeterlidir.
Sayproof kanalı	Okunan siparişlerin yazılacağı kanal. Siparişin pazarı bu kanalın pazarıdır.

• Shopify uygulamalara varsayılan olarak son 60 günün siparişlerini verir. İlk okumada kaç gün geriye gidilsin alanına 60’tan büyük bir değer yazılsa da daha eski siparişler gelmez; bunlar için uygulamanın Shopify onayına bağlı read_all_orders iznine de sahip olması gerekir.
• Müşteri e-posta adresi Shopify’ın korunan müşteri verilerindendir. Dev Dashboard’da açılan uygulamalar bu alana erişebilir; mağaza yönetiminde eski yöntemle açılmış özel uygulamalarda erişim mağazanın Shopify planına bağlıdır. Denemede E-posta var mı sütunu Yok gösteriyorsa uygulama e-postayı okuyamıyordur ve bu siparişler için davet gönderilemez. Siparişin telefon numarası da korunan müşteri verisidir; uygulama okuyamıyorsa alan boş gelir ve okuma durmaz.

Bir Sayproof kanalı için her platformda tek bağlantı kurulabilir.

Shopify’da uygulama oluşturma

Shopify yönetiminde yeni özel uygulama açılamaz; uygulama Shopify Dev Dashboard’da oluşturulur:

1. Dev Dashboard’da Apps bölümünde Create app düğmesine basın, Start from Dev Dashboard seçeneğini seçin ve uygulamaya bir ad verin (örneğin “Sayproof”).
2. Uygulamanın Versions sayfasında Scopes alanına read_orders yazın ve Release ile sürümü yayınlayın.
3. Uygulamayı açın, Installs kartındaki Install app düğmesiyle mağazanızı seçip kurun.
4. App settings sayfasındaki Client ID ve Client secret değerlerini kopyalayın.

Uygulama ile mağaza Shopify’da aynı organizasyona ait olmalıdır; Sayproof token’ı bu bilgilerle mağazanızdan ister. Bir izin sonradan eklenirse yeni sürüm yayınlanır ve değişiklik mağazada onaylanır.

Mağaza yönetiminde daha önce açılmış bir özel uygulamanız varsa (Apps › Develop apps) onun read_orders izinli Admin API access token değerini de kullanabilirsiniz: Client ID alanını boş bırakın ve token’ı Client secret alanına yazın.

Panelde kurulum

1. Entegrasyon › Sipariş aktarımı sekmesinin Platformdan okuma bölümünde Bağlantı kur düğmesine basın.
2. Nereden okunacak adımında platform olarak Shopify seçeneğini ve Sayproof kanalını seçin.
3. Bağlantı bilgileri adımında Shopify mağaza adresi, Client ID ve Client secret alanlarını doldurun. İlk okumada kaç gün geriye gidilsin alanı 1 ile 365 arasında bir değer alır; varsayılan 30 gündür.
4. Deneyin adımında Bağlantıyı dene düğmesine basın. Sayproof Shopify’a bağlanır ve seçilen gün sayısı içindeki siparişlerin ilk sayfasını (en fazla 25 sipariş) okur. Sonuçta okunan sipariş sayısı, okunamayan siparişler ve en fazla beş örnek sipariş gösterilir: Sipariş no, Sipariş tarihi, Ödeme, Ürün sayısı, Kargo durumu, E-posta var mı. Müşteri e-posta adresi gösterilmez. Bu adımda hiçbir şey kaydedilmez.
5. Kaydet ve okumayı başlat düğmesi yalnızca başarılı bir denemeden sonra açılır. Deneme sonrasında bir bilgi değiştirilirse bağlantı yeniden denenmelidir.

Kayıttan sonra bağlantı Platform bağlantıları kartında görünür. Kartta Okuma sıklığı, Son okuma, Son okumada (okunan ve yeni gelen sipariş sayısı), Okunamayan ve Son hata bilgileri yer alır. Düğmeler:

Düğme	İşlevi
Şimdi oku	Sıradaki okumayı beklemeden okumayı başlatır. Duraklatılmış bağlantıda ve kanal kapalıyken kullanılamaz.
Bağlantıyı dene	Kayıtlı bilgilerle denemeyi tekrarlar; hiçbir şey kaydetmez.
Duraklat / Sürdür	Okumayı durdurur ya da yeniden başlatır.
Bağlantıyı düzenle	Shopify mağaza adresi ve Okuma sıklığı (5 ile 1440 dakika arası) değiştirilir. Okuma kaldığı yerden sürer; daha önce aktarılan siparişler yeniden okunmaz. Adres başka bir mağazayı gösteriyorsa Client ID ve Client secret da aynı formda yeniden girilir; kayıtlı bilgiler yeni adrese gönderilmez (400 invalid / address_needs_credentials). Sayproof kanalı bu formda değişmez.
Giriş bilgilerini değiştir	Yeni Client secret değerini kaydeder; Client ID boş bırakılırsa mevcut değer korunur.
Bağlantıyı kaldır	Okumayı sonlandırır. Daha önce okunan siparişler ve gönderilen davetler silinmez.

Okuma

• Okuma varsayılan olarak 15 dakikada bir yapılır; sıklık Bağlantıyı düzenle ile 5 ile 1440 dakika arasında değiştirilebilir. İlk okuma, değişiklik zamanı seçilen gün sayısı içinde kalan siparişleri alır.
• Sonraki okumalar, bir önceki okumanın başladığı andan 10 dakika öncesine kadar değişen siparişleri alır. Aynı siparişin tekrar okunması güvenlidir: sipariş güncellenir, kopyası oluşmaz.
• Bir bağlantı için aynı anda tek okuma çalışır.
• Bir okuma en fazla 50 sayfa (sayfa başına en fazla 25 sipariş) alır. Shopify bir sayfanın sorgu maliyetini fazla bulursa sayfa daha az siparişle yeniden istenir. Siparişler bitmeden sınıra ulaşılırsa kartta “Son okuma sayfa sınırına takıldı” notu görünür ve sonraki okuma son okunan siparişin değişiklik zamanından (10 dakika payla) devam eder.
• Shopify istek sınırına ulaşıldığını bildirirse okuma o sayfada durur ve sonraki okuma kaldığı yerden devam eder. Bu ilk sayfada olursa okuma başarısız sayılır.
• Okuma başarısız olursa kaldığı yer ilerlemez; sonraki okuma, okuma sıklığı kadar sonra aynı aralığı yeniden dener ve nedeni Son hata satırında görünür.

Client ID girildiyse her okumanın başında Sayproof uygulama bilgileriyle mağazanızdan bir token alır; Client ID boşsa Client secret alanındaki eski özel uygulama token’ı doğrudan kullanılır. Token 24 saat geçerlidir ve Sayproof tarafından saklanmaz.

POST https://markaniz.myshopify.com/admin/oauth/access_token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client id>&client_secret=<client secret>

Siparişler GraphQL Admin API’sinin 2026-10 sürümünden, değişiklik zamanına göre sıralı okunur:

POST https://markaniz.myshopify.com/admin/api/2026-10/graphql.json
Content-Type: application/json
X-Shopify-Access-Token: <token>

{"query": "query SayproofOrders($first: Int!, $after: String, $query: String!) { orders(first: $first, after: $after, query: $query, sortKey: UPDATED_AT) { … } }", "variables": {"first": 25, "after": null, "query": "updated_at:>='2026-09-02T12:00:00Z'"}}

• Sonraki sayfalara yanıttaki pageInfo.endCursor değeriyle geçilir.
• Token kabul edilmezse (401) ve Client ID girildiyse Sayproof bir kez yeni token alır; eski özel uygulama token’ı kabul edilmezse okuma api_credentials_refused ile durur.
• Her isteğin zaman aşımı 30 saniye, yanıt sınırı 20 MB’tır.

Okunan alanlar

Sayproof’taki bilgi	Shopify’da okunan alan
Sipariş numarası	name (örneğin #1001)
Ödeme durumu	displayFinancialStatus
Sipariş tarihi	createdAt
Değişiklik zamanı	updatedAt
İptal	cancelledAt
Müşteri e-postası	email
Müşteri telefonu	phone
Dil	customerLocale (yalnızca ilk bölüm; tr-TR → tr)
Ürün satırları	lineItems; siparişin ilk 50 satırı
Satır kimliği	Satırın id değerinin sonundaki numara
Ürün kodu	Satırın sku değeri; boşsa varyantın legacyResourceId değeri
Grup kodu	Ürünün legacyResourceId değeri (Liquid’de product.id)
Ürün adı	Satırın name değeri
Adet	currentQuantity; sıfırsa quantity
Satır durumu	Satırın bulunduğu gönderilerin (fulfillments, siparişin ilk 5 gönderisi) displayStatus değeri; bkz. Teslim kuralı

• Müşteri e-postası, mağaza sisteminden gönderilen sipariş verisindeki customer_email alanıyla aynı işi görür: davet bu adrese gönderilir ve sipariş doğrulamasında bu adres kullanılır.
• Müşteri telefonu, sipariş verisindeki customer_phone alanıyla aynı işi görür: numara WhatsApp ile davet için kullanılacak. WhatsApp ile davet v2 sürümüyle gelene kadar telefon numarası saklanmaz.
• Ürün kodu, ürün kaynağınızdaki ürün anahtarıyla ve ürün sayfasındaki container’a verilen kodla aynı olmalıdır.
• Müşteri kaydı okunmaz; bu nedenle uygulamanın read_customers iznine ihtiyacı yoktur. Siparişin adres, fiyat ve ödeme bilgileri Sayproof’a kaydedilmez.

Durum eşlemesi

Ödeme durumu siparişin displayFinancialStatus değerinden gelir:

Shopify’daki değer	Anlamı	Ödeme
PENDING	Ödeme bekleniyor	Ödeme bekliyor
AUTHORIZED	Ödeme onaylandı, henüz tahsil edilmedi	Ödeme bekliyor
PARTIALLY_PAID	Kısmen ödendi	Ödeme bekliyor
PAID	Ödendi	Ödendi
PARTIALLY_REFUNDED	Kısmen iade edildi	Kısmen iade edildi
REFUNDED	İade edildi	İade edildi
VOIDED	Onay iptal edildi	İptal edildi
EXPIRED	Onayın süresi doldu	İptal edildi

Her satırın kargo durumu, satırın bulunduğu gönderinin displayStatus değerinden ya da aşağıdaki Sayproof kodlarından gelir:

Kod	Ne zaman	Kargo durumu
UNFULFILLED	Satır henüz bir gönderide değil	Sipariş verildi
SUBMITTED, LABEL_PURCHASED, LABEL_PRINTED, LABEL_VOIDED	Gönderi hazırlanıyor	Hazırlanıyor
FULFILLED, MARKED_AS_FULFILLED, CONFIRMED, FAILURE	Gönderi oluşturuldu; gönderinin displayStatus değeri boşsa da FULFILLED sayılır	Kargoya verildi
CARRIER_PICKED_UP, IN_TRANSIT, OUT_FOR_DELIVERY, DELAYED, ATTEMPTED_DELIVERY, NOT_DELIVERED, READY_FOR_PICKUP	Gönderi yolda ya da teslim almaya hazır	Yolda
DELIVERED, PICKED_UP	Gönderi teslim edildi ya da müşteri teslim aldı	Teslim edildi
CANCELLED	Sipariş iptal edildi (cancelledAt dolu)	İptal edildi
REMOVED	Satırın tamamı gönderilmeden iade edildi ya da siparişten çıkarıldı	İptal edildi
REFUNDED	Satırın tamamı bir gönderide yer aldıktan sonra iade edildi	İade edildi

• İptal edilmiş, hata vermiş ya da başarısız olmuş gönderiler (status değeri CANCELLED, ERROR ya da FAILURE) ve displayStatus değeri CANCELED olan gönderiler hesaba katılmaz.
• Tablo panelde bağlantı kartındaki Durumların karşılığı bölümünde de görünür.
• Tabloda olmayan bir değer gelirse sipariş ya da satır okunmaz ve Okunamayan satırında sayılır.

Teslim kuralı

• Bir satır, içinde bulunduğu gönderinin durumu DELIVERED ya da PICKED_UP olduğunda Teslim edildi sayılır. Teslim tarihi gönderinin deliveredAt değeri, boşsa updatedAt değeridir.
• Bir satır birden fazla gönderiye bölünmüşse en ileri durumdaki gönderi esas alınır.
• Gönderinin durumu Shopify’a kargo takip bilgisinden ya da gönderiye teslim bilgisi ekleyen uygulamalardan gelir. Shopify’da teslim bilgisi oluşmayan gönderiler Kargoya verildi ya da Yolda olarak kalır ve bu satırlar için davet gönderilmez.
• Davet ve yorum yazma hakkı için satırın Teslim edildi, siparişin Ödendi ya da Kısmen iade edildi olması gerekir. Davet, Davet gönderimi ekranındaki bekleme süresi dolduğunda gönderilir.

Okunamayan siparişler

Panelde	Nedeni
numarası ya da tarihi eksik	Siparişte name, createdAt ya da ürün satırları listesi yok
durumu tanınmıyor	Siparişin ödeme durumu tabloda yoksa sipariş, satırın gönderi durumu tabloda yoksa yalnızca o satır atlanır
ürün satırında ürün kodu eksik	Satırda kimlik yok ya da hem sku hem varyant boş; satır atlanır
okunabilen ürün satırı yok	Siparişin okunabilen hiçbir satırı kalmadı
50’den fazla ürün satırı var; ilk 50 satır okundu	Siparişin ilk 50 satırı kaydedildi, kalan satırlar okunmadı
Sayproof’a kaydedilemedi	Sipariş okundu ama Sayproof’ta kaydedilemedi (örneğin kanalın pazarı için tanımlı kural yok)

Okunamayan ya da kaydedilemeyen siparişler okumayı durdurmaz; diğer siparişler kaydedilir. Okunan siparişlerin hiçbiri kaydedilemezse okuma başarısız sayılır ve kaldığı yer ilerlemez; neden Son hata satırında görünür.

Hata durumları

Panelde	Anlamı
adres bir Shopify mağaza adresi değil; markaniz.myshopify.com biçiminde yazın	Adres <mağaza>.myshopify.com biçiminde değil; istek gönderilmez
bağlantı için gereken anahtar bilgileri eksik	Client secret boş
platform anahtar bilgilerini kabul etmedi	Shopify token isteğini reddetti (400, 401, 403) ya da token’ı kabul etmedi (401)
uygulamanın ya da anahtarın siparişleri okuma izni yok	Uygulamanın read_orders izni yok ya da izin mağazada onaylanmadı
çok sık istek gönderildi	Shopify istek sınırına ulaşıldığını bildirdi (ilk sayfada)
alan adına ulaşılamadı	Mağaza adresi çözümlenemedi
sunucuya bağlanılamadı, güvenli bağlantı kurulamadı	Bağlantı ya da TLS el sıkışması başarısız
kaynak zamanında yanıt vermedi	İstek 30 saniyede yanıt almadı
adres başka bir yere yönlendiriyor; doğrudan adresi yazın	Shopify yönlendirme döndürdü; yönlendirmeler izlenmez
karşı sistem hata verdi, durum kodu	Shopify 200 dışında bir yanıt verdi (örneğin mağaza dondurulduysa http_status: 402, kapalıysa http_status: 423)
platformun yanıtı okunamadı, platformun yanıtı çok büyük	Yanıt JSON değil, beklenen sipariş listesini içermiyor ya da 20 MB’tan büyük
kayıtlı giriş bilgileri okunamadı; yeniden girin	Kayıtlı bilgiler çözülemedi; Giriş bilgilerini değiştir ile yeniden girin
okuma beklenmeyen bir hatayla durdu	Beklenmeyen bir hata oluştu; okuma, okuma sıklığı kadar sonra yeniden denenir

Ürün sayfasında gösterim

Yorumlar ürün sayfasında script ile gösterilir. Shopify’da script ve container temanın ürün şablonuna bir Custom Liquid bloğuyla eklenir:

1. Shopify yönetiminde Online Store › Themes altında temanızın Customize düğmesine basın.
2. Üstteki sayfa seçiciden ürün şablonunu (Products › Default product) açın.
3. Yorumların görüneceği bölümde Add block ile bir Custom Liquid bloğu ekleyin, aşağıdaki kodu yapıştırın ve Save ile kaydedin.

<script type="module"
        src="https://cdn.sayproof.example/sayproof.js"
        data-review-site-key="SITE-ANAHTARINIZ"
        data-review-base="https://api.sayproof.example"
        data-review-locale="tr"></script>
<div data-review-mount
     data-review-product="{{ product.selected_or_first_available_variant.sku | default: product.selected_or_first_available_variant.id }}"
     data-review-product-name="{{ product.title | escape }}"></div>

• src ve data-review-site-key değerleri panelde Entegrasyon › Sitede gösterim sekmesindeki Yorumları ürün sayfasında gösterin kartında, Script (tarayıcıda) yolu seçildiğinde Kurulumda kullanılacak değerler listesinde yer alır.
• data-review-product, sayfa açıldığında seçili (yoksa ilk satılabilir) varyantın SKU’sudur; SKU boşsa varyant numarası kullanılır. Bu, Sayproof’un siparişten okuduğu ürün koduyla aynıdır.
• Varyant seçildiğinde tema container’ı güncellemez. Ürünün tüm varyantlarının yorumlarını birlikte göstermek için data-review-scope="group" ekleyin ve data-review-product değerini {{ product.id }} yapın; grup kodu Shopify’daki ürün numarasıdır.

Alan adı doğrulama

Yorumlar yalnızca doğrulanmış alan adlarındaki sayfalarda görünür. Shopify’da sitenin köküne dosya konulamadığı için alan adı DNS kaydıyla doğrulanır:

1. Panelde alan adını ekleyin; örneğin www.markaniz.com. Bkz. Alan adı doğrulama.
2. “<alan adı> nasıl doğrulanır?” bölümünde Doğrulama yolu olarak DNS kaydı’nı seçin. Alan adınızın DNS yönetiminde panelin gösterdiği Ad (_sayproof-verification.www.markaniz.com) ve Değer ile bir TXT kaydı ekleyin. Alan adı Shopify’dan alındıysa DNS kayıtları Shopify yönetiminde Settings › Domains altından düzenlenir.
3. Kayıt eklendikten sonra panelde Doğrula düğmesine basın. Kaydın görünmesi birkaç dakika ile birkaç saat sürebilir.

Yorumların gösterileceği her alan adı ayrı doğrulanır. Müşterilere myshopify.com adresi yerine kendi alan adınız gösteriliyorsa bu alan adını doğrulayın.

Güvenlik

• Client secret (ya da eski özel uygulamanın Admin API access token değeri) şifreli saklanır ve panelde ya da API yanıtlarında bir daha gösterilmez. Okuma sırasında Shopify’dan alınan token saklanmaz.
• Yalnızca https://<mağaza>.myshopify.com adresine bağlanılır; özel ağ adresleri ve yönlendirmeler reddedilir.
• Uygulamanın yalnızca okuma izni vardır; Sayproof Shopify’da hiçbir şeyi değiştirmez. Bağlantıyı tamamen kesmek için uygulamayı mağazanızdan kaldırın.
• Bağlantılar yalnızca panelde oturum açmış ve “Ayarları değiştirebilir” iznine sahip bir kullanıcı tarafından görülür ve yönetilir; API anahtarıyla bu işlemler yapılamaz.
• Kurma, değiştirme, deneme, elle okuma ve kaldırma işlemleri İşlem geçmişi ekranına kaydedilir.