3. Parti Uygulamalar ile Gönderi Verisinin Paylaşılması (Shopify Metafield ile)

Kargo Entegratör tarafından Shopify siparişleriniz için oluşturulan kargo barkod bilgilerine, 3. parti uygulamalar üzerinden Shopify Admin GraphQL API'si ile ulaşabilirsiniz. Bu doküman, ilgili ayarın nasıl açılacağını, sorgunun nasıl yapılacağını ve dönen yanıtın nasıl okunacağını adım adım açıklar.

1. İlgili Ayarı Aktif Edin

Barkod bilgisinin siparişin metafield alanına yazılabilmesi için öncelikle ilgili ayarın açık olması gerekir.

Kargo Entegratör panelinde Ayarlar bölümüne gidin.
Diğer Ayarlar sekmesini açın.
"Barkod oluşturduktan sonra siparişin özel alanını (metafield) güncelle" seçeneğini işaretleyin.

Bu seçenek aktif edildiğinde; üçüncü parti uygulamaların okuyabilmesi için, barkod ve kargo firması bilgileri siparişin özel alanına (metafield) eklenir. Bu veriye kargo_entegrator isim alanı (namespace) üzerinden erişilebilir.

⚠️ Dikkat: Bu ayar aktif değilken oluşturulan gönderilerin barkod bilgisi metafield alanına yazılmaz. Ayarı açtıktan sonra oluşturulan gönderiler için barkod verisi paylaşılmaya başlanır.

2. Barkod Verisi Nerede Tutulur?

Kargo Entegratör, oluşturduğu her gönderinin barkod bilgisini ilgili siparişin metafield alanında saklar. Bu veriye erişmek için aşağıdaki namespace ve key kullanılır:

Namespace: kargo_entegrator
Key: shipment_data

Bu metafield içerisinde gönderiye ait shipment_id, barcode ve cargo_company (kargo firması) bilgileri yer alır.

3. Barkod Verisini Çekmek İçin Sorgu

Aşağıdaki GraphQL sorgusu ile bir siparişe ait kargo barkod bilgisine ulaşabilirsiniz. Sorgudaki sipariş ID'sini (gid://shopify/Order/...) kendi siparişinizin ID'si ile değiştirmeniz yeterlidir.

{
  order(id: "gid://shopify/Order/6176180273389") {
    name
    id
    metafield(namespace: "kargo_entegrator", key: "shipment_data") {
      id
      jsonValue
    }
  }
}

⚠️ Dikkat: Sorgudaki order(id: ...) alanındaki değeri, barkod bilgisini almak istediğiniz siparişin kendi ID'si ile güncellemeyi unutmayın.

4. Örnek Yanıt

Sorgu başarıyla çalıştığında, aşağıdakine benzer bir yanıt dönecektir. Barkod bilgisi metafield içindeki jsonValue alanında bulunur.

{
  "data": {
    "order": {
      "name": "#1017",
      "id": "gid://shopify/Order/6176180273389",
      "metafield": {
        "id": "gid://shopify/Metafield/40713851109613",
        "jsonValue": [
          {
            "shipment_id": "72049",
            "barcode": "953932585239",
            "cargo_company": "Dummy Kargo"
          }
        ]
      }
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 2,
      "actualQueryCost": 2,
      "throttleStatus": {
        "maximumAvailable": 2000,
        "currentlyAvailable": 1998,
        "restoreRate": 100
      }
    }
  }
}

5. Yanıttaki Alanların Anlamı

Dönen yanıtta yer alan barkod bilgisini şu şekilde okuyabilirsiniz:

shipment_id → Gönderiye ait benzersiz kimlik numarası (örnek: 72049)
barcode → Kargo firması tarafından oluşturulan gönderi barkodu (örnek: 953932585239)
cargo_company → Gönderinin oluşturulduğu kargo firması (örnek: Dummy Kargo)

💡 Not: jsonValue alanı bir liste (array) olarak döner. Bir siparişte birden fazla gönderi/paket bulunuyorsa, her paket için ayrı bir barkod kaydı bu listede yer alır.