# Shopify siparişleri

> Sayproof'un siparişleri Shopify'dan kendisinin okuması; uygulama bilgileri, kurulum, durum eşlemesi, teslim kuralı ve ürün sayfasında gösterim.

Kaynak: /tr/integrate/shopify/

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](/tr/integrate/orders.md) 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ı](/tr/integrate/orders.md).

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.

```http
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:

```http
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ı](#teslim-kurali) |

- 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](/tr/features/invitations.md#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](/tr/integrate/script.md) 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.

```html
<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](/tr/integrate/channels-and-keys.md#alan-adi-dogrulama).
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.