WooCommerce API Nedir? Nasıl Kullanılır?

WordPress üzerine kurularak websitene e-ticaret yeteneği kazandıran WooCommerce eklentisi API desteği ile farklı çözümler ve servis erişim imkanları da sunmaktadır.
AA

Peki, bu API imkanları nelerdir ve nasıl kullanırlar?

WooCommerce

WooCommerce

WooCommerce tarafıdan sunulan API erişimlerinden önce WooCommerce ile ilgili detaylı bilgi almak isteyebilirsiniz. WooCommerce bize ürün sayfası, ürün türleri ve satış özellikleri sunan, kampanyalar kurgulamamızı sağlayan oldukça başarılı ve popüler WordPress eklentilerinden biridir. Son bilgilere göre WooCommerce 3,317,205 web sitesinde kullanılmaktadır ve bu online e-ticaret sitelerinin 28.19%’lik bir dilimine karşılık gelmektedir1.

Google Analytics ile ilgili destek talebinde bulunabilirsin.

WooCommerce, özelleştirmeler ve ihtiyaç duyulan yetenekler çerçevesinde WebHooks, Legacy API ve REST APIimkanları sunmaktadır. Daha önce, PHP cURL aracılığıyla örnek bir işlem olarak GET ile ürünlerin listelenmesi, PUT ile de yeni ürün eklenmesi hususuna değinmiştim. Bu yazıda ilgili işlemleri adım adım yürütüp yapılabilecek işlemleri detaylandıracağız.

REST API (WOO REST API)

WOO REST API, WooCommerce (WC) tarafından sunulan, WordPress REST API ile tamamen entegre olan, standart HTTP isteklerinin JSON formatında işleme alındığı (oluşturma, okuma, güncelleme ve silme) ve WordPress REST API kimlik doğrulama metotlarının kullanıldığı bir REST API servisidir2. Kullanım için WooCommerce 3.5+ ve WordPress 4.4+ sürümleri gereklidir. Son olarak v3 sürümü duyurulan WOO REST API /wp-json/wc/v3 yolunu kullanır. Gereksinimler, hatalar ve örnek sorgular için API dokümantasyonunu inceleyebilirsiniz3.

Öncelikle index’i görüntüyelelim. Örnek işlemler için Postman kullanacağım. Doğrudan alan adı üzerinden URI tanımını yaparak ilerleyelim.

GET alanadi.com/wp-json/wc/v3

GET request sonucunda bize JSON formatında metotlar, veri tipleri, ilgili uç nokta için izin verilen istek türleri gibi bilgilerin yer aldığı uzunca bir response dönecektir.

{
    "namespace": "wc/v3",
    "routes": {
        "/wc/v3": {
            "namespace": "wc/v3",
            "methods": [
                "GET"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": {
                        "namespace": {
                            "required": false,
                            "default": "wc/v3"
                        },
                        "context": {
                            "required": false,
                            "default": "view"
                        }
                    }
                }
            ],

Kimlik Oluşturma

En temel şekilde WooCommerce > Ayarlar > REST API > Add Key adımlarını izleyerek belirtilen kullanıcı ile ilişkili farklı amaçlarla kullanabilmek amacıyla bir veya daha fazla key oluşturabiliriz4.

Woo API Key Oluşturma

Bir diğer yöntem ise Application Authentication Endpoint üzerinden otomatik olarak API key oluşturmak. Bu işlem için şu tanımlara ihtiyaç duyulmakta.

WOO API Kullanıcı Oluşturma

app_name ile uygulama adı, scope ile oluşturacağımız anahtar ile anahtarın ne amaçla kullanılacağı; read (okuma), read_write (okuma/yazma), write (yazma), return_url işlemin başarı ile sonuçlanmasının ardından kullanıcının nereye yönlendirileceği ve son olarak callback_url ile oluşturulan API key’i alacak URL’i belirtmemiz gerekir. Unutmadan, callback_url HTTPS üzerinden olmalıdır. Şimdi, bu bilgileri bir örnek satır ile ifade edelim5.

https://alanadi.com/wc-auth/v1/authorize?app_name= &scope=read_write&user_id= &return_url=https://alanadi.com/return-page
&callback_url=https://alanadi.com/callback-endpoint

API erişimi için gerekli bilgilere de sahip olduğumuza göre HTTP Basic Auth tanımı ile bu bilgileri kullanabiliriz. şimdi kısaca parametrelere göz atalım6.

Parametreler

WOO API üzerinden bir istekte bulunduğunuzda bu istek parametrelerin belirli ön tanımlı değerleri üzerinden size döndürülecektir3. Örneğin, ürünleri listelediğinizde alacağınız JSON çıktısı 10 adet ürün içerir. 10 adet üzerinde ürün mevcut ise sayfada görüntülenecek item sayısı, sayfalama, hariç tutma (offet) gibi parametrelerden faydalanabilmekteyiz. Sayfalama da kendi içinde next, last, first ve prev kullanımlarını sunmakta7.

Örnek bir sorgu olarak 21-30 aralığındaki siparişleri listeleyelim.

GET /orders?per_page=15&page=2&offset=5

Parametre kullanımında toplam item ve per_page ile ilişkili olarak HEADER içeriğinde 2 özelleştirilmiş alan bize iletilir; X-WP-Total ve X-WP-TotalPages. Bu tanımlarla birlikte toplam item sayısını ve bu sayısının kaç sayfa üzerinden iletildiğini öğrenebiliriz. Örneğin, R İle WordPress REST API Erişimi başlıklı yazımda tüm içerikleri bir veri tablosuna bu bilgiler üzerinden sayfalama yaparak kayıt etmiştim.

Şimdi, gelelim asıl konumuz olan uç noktalara (endpoints).

Uç Noktalar (en: Endpoint)

Uç noktalar (enpoints) özelleştirilmiş sorgu adresleridirler. Temel mantığına daha önce routing konusunda değiniştim. Bu adresler aracılığıyla oldukça kolay bir şekilde tanımlı işlemlerin gerçekleştirilmesi sağlayabiliriz. Örneğin, WooCommerce ürünü eklemek istediğimizi varsayalım. Öncelikle ilgili ürünün daha önce eklenmiş olup olmadığını kontrol etmemiz gerekir. Eğer var ise ürünü yeniden eklemek yerine ekli ürünün bilgilerini karşılaştırmalıyız ve fark var ise amacımız yeni ürün olarak eklemek yerine bu farklılığı düzenlemek olacaktır. Tüm bu işlemler için farklı ve/veya komplike SQL sorguları ya da hook’lar yazmamız gerekir. Fakat, API aracılığıyla bir kaç satırda bu işlemi hata ihtimali oldukça düşük bir şekilde gerçekleştirilebilmekte8.

Örneğin, XML2WOO eklentisi belirtilen XML dosyasını alıp, içeriğindeki bilgilere göre WooCommere API aracılığıyla ürünleri sorgular. Benzer ürünler var ise bir tablo üzerinden belirtir ve istendiği taktirde XML verilerini WooCommerce altındaki ürünlere aktarır. Şayet, benzer bir ürün yok ise XML içeriğindeki ürün yeni bir ürün olarak eklenir. Hatta, eklenti zamanlanarak bu işlemin otomatik bir şekilde belirtilen zaman aralıklarında gerçekleştirilmesini sağlar9.

Products

/wp-json/wc/v3/products ile erişebileceğimiz uç noktaya GET isteğinde bulunarak ürünleri (ön tanımlı olarak 10 adet) listeleyebiliriz (view). Spesifik bir ürünü görüntülemek için id tanımını da belirtebiliriz; /wp-json/wc/v3/products/. Listeleme ya da tek ürün fark etmeksizin bize id, name, slug, permalink, date_created, date_modified, type, status gibi ürüne ait pek çok bilgi iletilecektir. Yine bu uç nokta üzerinden POST request ile bir veya daha fazla ürünün listele eklenmesini sağlayabiliriz.

curl -X POST https://alanadi.com/wp-json/wc/v3/products \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "name": "Premium Quality",
  "type": "simple",
  "regular_price": "21.99",
  "description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
  "short_description": "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
  "categories": [
    {
      "id": 9
    },
    {
      "id": 14
    }
  ],
  "images": [
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
    },
    {
      "src": "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg"
    }
  ]
}'

Bir ürünün bilgilerini güncellemek istersek PUT request ile id üzerinden işlem yapılmasını sağlayabiliriz. Şayet, PUT request ile ilettiğimiz id karşılığı yok ise ürünler yeni ürün olarak eklenecektir. Ancak, bu durumda güncellenmesini istediğimiz ürün bilgisi eklenir, diğer alanlar elbette boş bırakılır.

PUT /wp-json/wc/v3/products/

Yine id belirterek DELETE request ile belirtilen ürünün silinmesini sağlayabiliriz.

DELETE /wp-json/wc/v3/products/

Tek istekte toplu olarak işlemlerin (silme, ekleme, güncelleme vb.) gerçekleştirilebilmesi için POST request ile içeriğimizi /wp-json/wc/v3/products/batch noktasına iletmemiz gerekir3.

Orders

Yapılan siparişleri listelemek için /wp-json/wc/v3/orders yolunu kullanabiliriz. Yapılan sorgularda id, order_key, status, currency, date_created, discount_total, total, customer_id, billing, shipping, customer_note, payment_method, refunds gibi pek çok bilgi işleme alınabilir. Tüm siparişleri listelemek için bu yola GET isteğinde bulunmamız yeterli olacaktır.

GET /wp-json/wc/v3/orders/

Yeni bir sipariş oluşturmak için /wp-json/wc/v3/orders yoluna POST request gerçekleştirmek yeterli olacaktır.

curl -X POST https://alanadi.com/wp-json/wc/v3/orders \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "payment_method": "bacs",
  "payment_method_title": "Direct Bank Transfer",
  "set_paid": true,
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@alanadi.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "address_2": "",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "line_items": [
    {
      "product_id": 93,
      "quantity": 2
    },
    {
      "product_id": 22,
      "variation_id": 23,
      "quantity": 1
    }
  ],
  "shipping_lines": [
    {
      "method_id": "flat_rate",
      "method_title": "Flat Rate",
      "total": 10
    }
  ]
}'

Bu isteğin işlenmesinin ardından bize eklenen ürünle ilgili ön tanımlı diğer bilgilerin de eklendiği daha detaylı bir bilgi dönecektir. Bir siparişin detaylarına id aracılığıyla GET request ile ulaşabiliriz.

GET /wp-json/wc/v3/orders/

Bir siparişe ait bilgileri güncellemek istersek yine id aracılığıyla PUT isteğinde bulunmamız yeterli.

curl -X PUT https://alanadi.com/wp-json/wc/v3/orders/<id> \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "status": "completed"
}'

Siparişi silmek için ise yine id içerir şekilde DELETE isteğini kullanabiliriz. Sipariş işlemleriyle ilgili daha detaylı bilgi ve örnekler için woocommerce-rest-api-docs incelenebilir.

Refunds

WOO API aracılığıyla iade işlemleri de kolayca yönetilebilmektedir. Bu işlemler için kullanılan uç nokta ise /wp-json/wc/v3/orders//refunds. Görüldüğü üzere sipariş id bilgisi üzerinden iade işlemi gerçekleştirilmekte. Dolayısıyla, öncesinde ilgili siparişe ait id bilgisinin edinilmesi gerekmekte. Aşağıdaki POST request ile iade işlemini başlatabiliriz.

POST /wp-json/wc/v3/orders/refunds

Tüm iade işlemlerini listelemek istersek refunds yoluna GET isteğinde bulunmamız yeterli olacaktır.

GET /wp-json/wc/v3/orders/refunds

Oluşturulan bir iade işlemine dair detayları ise refund_id üzerinden görüntüleyebiliriz.

GET /wp-json/wc/v3/orders/refunds/

Son olarak, bir iade işlemini silmek istersek yine refund_id üzerinden DELETE request gerçekleştirmeliyiz.

DELETE /wp-json/wc/v3/orders/refunds/

Müşteriler, kuponlar, ürün özellikleri, ürün kategorileri, tanımlı kargo sınıfları, ürün etiketleri, vergi oranları, vergi sınıfları, ödeme yolları, kargo bölgeleri gibi diğer uç noktalar için WOO REST API dokümantasyonunu inceleyebilirsiniz3.

İlgili Öneriler
İleri Okumalar
  1. Getting started with the REST API ↩
  2. WOO REST API ↩
  3. WooCommerce REST API Documentation ↩ ↩ ↩ ↩
  4. 21+ WooCommerce Stats – The Leader in WordPress eCommerce ↩
  5. Builtwith – Trends. WooCommerce Usage Statistics ↩
  6. Basic access authentication. Wikipedia ↩
  7. W3Techs. Usage statistics and market share of WooCommerce ↩
  8. Datanyze. Top Competitors of WooCommerce in Datanyze Universe ↩
  9. Torque. The Beginner’s Guide to the WooCommerce REST API ↩
Yorum alanını göster
Beğendim
Beğenmedim