Kimlik doğrulama ve anahtarlar

Piyodo mağazanı kendi yazılımına, depo sistemine ya da pazaryerine Admin API ile bağla: anahtar üretimi, kapsamlar, hız sınırı, tutar biçimi, sayfalama ve hata kodları.

Neler var

Bağlantı	Ne için	Plan
Admin API (`https://piyodo.com/api/store/v1`)	Ürün, stok, sipariş, müşteri, kampanya ve webhook yönetimi	Ölçek
MCP (`https://piyodo.com/mcp/store`)	Claude gibi yapay zekâ araçlarını mağazaya bağlama	Ölçek
Uygulama (OAuth)	Başka mağazalara kurulan uygulama yazma	Tüm planlar, abonelik geçerliyse
Webhook	Olay olunca adresine imzalı JSON	Tüm planlar, panelden
Vitrin olayları ve özel script	Ziyaretçinin tarayıcısında çalışan kod	Tüm planlar, panelden

Anahtar üretme

Mağazam → Ayarlar → Geliştirici sayfasını aç. Sayfayı mağaza sahibi ve yöneticiler görür.
Anahtara bir ad ver ve yalnız gereken kapsamları seç.
Anahtarı hemen kopyala. psk_ ile başlar, bir kez gösterilir; sunucuda yalnız özeti saklanır.

Bir mağazada en çok 20 anahtar olur. İptal ettiğin anahtarı kullanan bağlantılar hemen durur. Abonelik biterse ya da plan Ölçek'in altına inerse anahtarlar 403 döner; plan yükselince yeniden çalışır. Bir uygulamanın kurulumuyla gelen anahtar plan sınırına takılmaz, yalnız abonelik geçerli olmalıdır; bu anahtar listede işaretlidir ve Uygulamalar sayfasından kaldırılır.

İstek yapma

Anahtarı her istekte Authorization başlığında gönder. Anahtar mağazayı belirler: adreste mağaza seçilmez, başka mağazanın verisine ulaşılamaz.

bash

curl "https://piyodo.com/api/store/v1/store" \
  -H "Authorization: Bearer psk_..."

Tüm yanıtlar JSON'dur. Gövde gönderirken Content-Type: application/json kullan.

Mağaza bilgisi

GET /store anahtarın hangi mağazaya ait olduğunu, yetkilerini ve kargo yöntemlerini döner. Herhangi bir kapsamla çalışır, bağlantıyı denemek için de uygundur.

json

{
  "data": {
    "id": "01J...",
    "name": "Ayşe Butik",
    "slug": "ayse",
    "currency": "TRY",
    "kind": "store",
    "url": "https://ayse.example.com/",
    "domain": null,
    "plan": "scale",
    "scopes": ["products.read", "orders.read"],
    "shipping_methods": [
      {
        "id": "standard",
        "name": "Standart kargo",
        "fee": "50.00",
        "per_kg": "0.00",
        "free_over": null,
        "cities": [],
        "pickup": false,
        "pickup_city": null,
        "address": null,
        "note": null
      }
    ]
  }
}

Dışarıdan sipariş açarken shipping_method alanına buradaki id yazılır.

Kapsamlar

Eksik kapsamla yapılan istek 403 döner.

Kapsam	İzin
`products.read`	Ürünleri ve stoğu okuma
`products.write`	Ürün ve stok değiştirme
`orders.read`	Siparişleri okuma
`orders.write`	Sipariş açma, kargolama, iptal, iade
`customers.read`	Müşterileri okuma
`customers.write`	Müşteri değiştirme
`discounts.read`	Kampanyaları okuma
`discounts.write`	Kampanya değiştirme
`webhooks.read`	Webhook aboneliklerini okuma
`webhooks.write`	Webhook aboneliği değiştirme

orders.write para iadesi de yapabilir. Bu kapsamı yalnız güvendiğin sisteme ver.

Hız sınırı

Anahtar başına dakikada 120, IP başına dakikada 600 istek. Sınır aşılınca 429 döner; Retry-After başlığı kaç saniye bekleneceğini söyler.

Tekrar eden istekler

Yanıt yolda kaybolursa isteğin işlenip işlenmediğini bilemezsin; körlemesine yeniden göndermek ikinci sipariş ya da ikinci iade doğurur. POST /orders ve POST /orders/{id}/refund çağrılarında Idempotency-Key başlığı gönder, yeniden denerken aynı değeri kullan. Başlık isteğe bağlıdır, en çok 255 karakterdir; her yeni işlem için yeni bir değer üret (ör. UUID).

bash

curl -X POST "https://piyodo.com/api/store/v1/orders/01J.../refund" \
  -H "Authorization: Bearer psk_..." \
  -H "Idempotency-Key: 6f1c2b7e-0d4a-4a53-9a51-2f5d3f0c8b11" \
  -H "Content-Type: application/json" \
  -d '{"amount": "250.00"}'

Anahtar mağaza başına 24 saat geçerlidir.

Durum	Yanıt
Aynı anahtar, aynı istek, ilki tamamlanmış	İşlem tekrarlanmaz, ilk yanıt döner, `Idempotent-Replayed: true` başlığı eklenir
Aynı anahtar, ilki hâlâ işleniyor	`409`, `Retry-After` kadar bekleyip yeniden dene
Aynı anahtar, farklı adres ya da gövde	`422`
İlk istek `4xx` döndüyse	Anahtar serbest kalır: hatayı düzeltip aynı anahtarla gönderebilirsin
İlk istek `5xx` döndüyse	Aynı `5xx` yanıtı döner. İşlem tamamlanmış olabilir: `GET /orders/{id}` ile bak, yapılmamışsa yeni anahtarla gönder

409 uzun sürerse istek yarıda kesilmiş olabilir: yine sipariş kaydına bak, işlem yapılmamışsa yeni anahtarla gönder.

Tutarlar

Tutarlar ana birimde ondalık metindir: "899.90". Kayan nokta hatası olmaz, gönderirken de aynı biçim kullanılır. Hepsi mağaza para birimindedir (GET /store içindeki currency).

Müşteri dövizle ödediyse siparişteki charge alanı karttan çekilen tutarı verir. Ayrıntı Siparişler sayfasında.

Sayfalama

Liste uçları sayfalıdır. page sayfa numarası, per_page sayfa başına kayıt (varsayılan 25, en çok 100).

bash

curl "https://piyodo.com/api/store/v1/products?page=2&per_page=50" \
  -H "Authorization: Bearer psk_..."

Yanıtta data kayıtları taşır. meta içinde current_page, last_page, per_page ve total, links içinde first, last, prev ve next adresleri vardır. Son sayfada links.next değeri null olur.

Ürün, sipariş ve müşteri listeleri updated_since süzgeci alır. Eşitleme yaparken son çalıştığın zamandan bu yana değişenleri çekmek için kullan:

bash

curl "https://piyodo.com/api/store/v1/orders?updated_since=2026-11-05T10:00:00Z" \
  -H "Authorization: Bearer psk_..."

Hatalar

Kod	Anlamı
`401`	Anahtar yok ya da geçersiz
`403`	Kapsam eksik, abonelik bitmiş, mağaza kapalı ya da planda API yok
`404`	Kayıt bulunamadı ya da başka mağazaya ait
`409`	Aynı `Idempotency-Key` ile gönderilen istek hâlâ işleniyor
`422`	Doğrulama hatası ya da bu durumda yapılamayan işlem
`429`	Hız sınırı aşıldı

Doğrulama hatasında errors alan bazında iletileri verir:

json

{
  "message": "...",
  "errors": {"name": ["..."], "price": ["..."]}
}

Diğer hatalarda yalnız message döner. İletiler insan içindir; yazılımında durum koduna ve errors anahtarlarına bak.