Siparişler - Piyodo

Siparişleri oku, dışarıdan sipariş aç, hazırla, kargola, teslim et, iptal et ve iade yap. Durum değişiklikleri panelle aynı kuralları izler, müşteriye aynı e-postalar gider. Dövizli siparişin charge alanı da burada anlatılır.

Uçlar

Yöntem ve adres	Kapsam	Ne yapar
`GET /orders`	`orders.read`	En yeniden listeler
`GET /orders/{id}`	`orders.read`	Tek sipariş
`POST /orders`	`orders.write`	Dışarıdan sipariş açar
`POST /orders/{id}/prepare`	`orders.write`	Hazırlanıyor yapar
`POST /orders/{id}/ship`	`orders.write`	Kargolandı yapar, müşteriye e-posta gider
`POST /orders/{id}/deliver`	`orders.write`	Teslim edildi yapar
`POST /orders/{id}/cancel`	`orders.write`	Para alınmamış siparişi iptal eder
`POST /orders/{id}/refund`	`orders.write`	Para iadesi yapar

Liste süzgeçleri: status, email, updated_since.

Durumlar

Durum	Anlamı
`pending`	Ödeme bekliyor
`paid`	Ödendi
`confirmed`	Kapıda ödeme onaylandı
`preparing`	Hazırlanıyor
`shipped`	Kargolandı
`delivered`	Teslim edildi
`failed`	Ödeme başarısız
`cancelled`	İptal edildi
`refunded`	Tamamı iade edildi

Siparişin durumu işleme uygun değilse 422 döner.

İşlem	Geçerli durumlar
`prepare`	`paid`, `confirmed`
`ship`	`paid`, `confirmed`, `preparing`
`deliver`	`shipped`
`cancel`	`pending`, `failed`, `confirmed`. Kapıda ödemede `preparing` ve `shipped` da olur. Tamamı krediyle ödenmişse `paid`, `preparing`, `shipped`, `delivered` da olur, bakiye geri döner
`refund`	`paid`, `preparing`, `shipped`, `delivered`. Kapıda ödemede yalnız `delivered`

Ödenmiş sipariş iptal edilmez, iade edilir.

İade talepleri

Müşteri teslim edilen siparişten iade talebi açabilir. Talep return_request alanında döner, karar panelden verilir. Para POST /orders/{id}/refund ile iade edilince açık talep kapanır.

Alan	Anlamı
`status`	`pending`, `approved`, `rejected`, `completed`
`reason`	`changed_mind`, `wrong_item`, `damaged`, `not_as_described`, `other`
`quantities`	Kalem kimliğine göre iade adedi

Yeni talepte return.requested webhook'u gider.

Dijital ürünler

Kalemde digital: true ise dosya müşterinin sipariş sayfasından indirilir. Yalnız dijital ürün içeren sipariş ödeme alınınca delivered olur. Kapıda ödemeyle alınamaz.

Sipariş açma

Pazaryeri ya da telefon siparişi için. Kartla ödeme bu yoldan alınamaz: para dışarıda alınmıştır ya da kapıda alınacaktır.

bash

curl -X POST "https://piyodo.com/api/store/v1/orders" \
  -H "Authorization: Bearer psk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Mehmet Yılmaz",
    "customer_email": "[email protected]",
    "customer_phone": "+905551112233",
    "address": "Moda Cad. 1",
    "city": "İstanbul",
    "district": "Kadıköy",
    "country": "TR",
    "items": {"01JPRODUCT": 2, "01JPRODUCT2:01JVARIANT": 1},
    "payment_method": "manual",
    "shipping_method": "standard",
    "discount": "100.00"
  }'

Alan	Not
`customer_name`, `customer_email`	Zorunlu
`country`	Zorunlu, iki harfli ülke kodu
`address`, `city`	Zorunlu. Mağazadan teslim yönteminde gerekmez
`district`	Türkiye'de zorunlu. Türkiye'de il ve ilçe resmî listeden olmalı
`items`	Zorunlu. `{"ürün id": adet}`, varyantlı üründe `{"ürün id:varyant id": adet}`. En çok 50 satır, satırda en çok 99 adet
`payment_method`	Zorunlu. `manual`: para dışarıda alındı, sipariş hemen ödenmiş olur. `cod`: kapıda ödeme, sipariş onaylı açılır
`shipping_method`	`GET /store` içindeki yöntem kimliği
`discount`	Elle indirim tutarı
`customer_phone`, `note`	İsteğe bağlı

Stok düşülür. Yanıt 201 ve sipariş kaydıdır; source değeri manual olur. Mağaza aboneliği aktif değilse 422 döner.

Yeniden deneme yapan sistemlerde Idempotency-Key gönder, aynı sipariş iki kez açılmaz. Bkz. Tekrar eden istekler.

Kargolama

Üç alan da isteğe bağlıdır. Bilinen firmalarda takip adresi kendiliğinden oluşur.

bash

curl -X POST "https://piyodo.com/api/store/v1/orders/01J.../ship" \
  -H "Authorization: Bearer psk_..." \
  -H "Content-Type: application/json" \
  -d '{"carrier": "yurtici", "tracking_number": "1234567890"}'

tracking_url ile kendi takip adresini verebilirsin. Müşteriye takip bilgisiyle e-posta gider.

İade

Kartla ödenmiş siparişte para gerçekten karta döner, bu işlem geri alınamaz. Kısmi iadede aynı istek iki kez işlenirse iki iade yapılır: her iadede Idempotency-Key gönder. Bkz. Tekrar eden istekler.

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", "quantities": {"42": 1}, "restock": true, "reason": "Beden uymadı"}'

Alan	Not
`amount`	Zorunlu. Mağaza para biriminde, kalan iade edilebilir tutarı geçemez
`quantities`	`{"kalem id": adet}`. Kalem kimliği siparişin `items[].id` değeridir
`restock`	`true` ise `quantities` içindeki adetler stoğa döner
`reason`	En çok 300 karakter

Toplam iade sipariş tutarına ulaşınca durum refunded olur. Kısmi iadede durum değişmez, refunded_total artar.

Yanıt

json

{
  "data": {
    "id": "01J...",
    "number": 1042,
    "status": "paid",
    "url": "https://ayse.example.com/siparis/...",
    "source": null,
    "external_id": null,
    "note": null,
    "currency": "TRY",
    "customer": {"name": "Mehmet Yılmaz", "email": "[email protected]", "phone": null, "id": null},
    "shipping_address": {"address": "Moda Cad. 1", "district": "Kadıköy", "city": "İstanbul", "country": "TR"},
    "billing": null,
    "items": [
      {
        "id": 42,
        "product_id": "01J...",
        "variant_id": null,
        "name": "Keten Gömlek",
        "variant_title": null,
        "unit_price": "1000.00",
        "quantity": 1,
        "refunded_quantity": 0,
        "total": "1000.00",
        "options": []
      }
    ],
    "subtotal": "1000.00",
    "discount_total": "0.00",
    "discount_code": null,
    "shipping_total": "0.00",
    "payment_adjustment": "0.00",
    "credit_used": "0.00",
    "gift_card_used": "0.00",
    "total": "1000.00",
    "refunded_total": "0.00",
    "charge": {"currency": "USD", "rate": 0.025, "total": "25.00", "refunded": "0.00"},
    "payment": {"method": "card", "provider": "stripe", "reference": "..."},
    "shipping": {"method": "Standart kargo", "pickup": false, "carrier": null, "tracking_number": null, "tracking_url": null},
    "tags": [],
    "created_at": "2026-11-05T10:00:00+00:00",
    "updated_at": "2026-11-05T10:00:00+00:00",
    "paid_at": "2026-11-05T10:00:00+00:00",
    "shipped_at": null,
    "delivered_at": null
  }
}

payment.method değerleri: card, transfer, cod, manual, credit.

source siparişin nereden açıldığını söyler: null vitrin, manual panel ya da API, pos mağaza içi satış ekranı. Satış ekranı siparişi teslim edilmiş (delivered) açılır, payment.method manual, payment.reference ödeme tipidir (cash, card, other). Müşteri bilgisi isteğe bağlıdır: customer.email null gelebilir, customer.name Misafir olur, shipping_address satış yapılan lokasyonu ya da mağazayı gösterir.

Pazaryerinden alınan siparişte source pazaryerinin adıdır (trendyol), external_id pazaryerindeki paket numarası, payment.reference pazaryeri sipariş numarasıdır. payment.method manual olur, customer.email null gelir, tutarlar pazaryerinin bildirdiğidir. Bu siparişlerde hazırlama, kargolama, teslim, takip, iptal ve iade uçları 422 döner: işlem pazaryerinde yapılır, durum buraya kendiliğinden gelir. Webhook olayları normal çıkar.

Dövizli sipariş: charge

Müşteri dövizle ödediyse sipariş yine mağaza para biriminde kalır: currency, total, subtotal ve diğer tutarlar mağaza para birimindedir. Karttan çekilen para charge alanındadır. Müşteri mağaza para biriminde ödediyse charge değeri null olur.

Alan	Anlamı
`charge.currency`	Karttan çekilen para birimi, ör. `USD`
`charge.rate`	Ödeme anında kilitlenen kur. Mağaza para biriminin 1 birimi kaç döviz eder
`charge.total`	Karttan çekilen toplam tutar
`charge.refunded`	Karta döviz olarak iade edilen tutar

Hesap: charge.total = total × charge.rate. Örnekte 1000.00 × 0.025 = 25.00.

Muhasebe ve ciro için total kullan. Banka mutabakatı ya da müşteriye gösterilen tutar için charge kullan.

Dövizli siparişte iade tutarı (amount) mağaza para biriminde gönderilir, müşteriye kilitli kurla döner. Tam iadede çekilen dövizin tamamı geri gider, kur yuvarlaması kalmaz. Havale ve kapıda ödeme mağaza para biriminde kalır.