# Sepet Kancaları

https://dev.wisecp.com/tr/sepet-kancalari

Müşteri sepete ürün koyduğu andan siparişi kurduğu ana kadar sekiz kanca: ekleme kapıları, fiyatlama zinciri ve ödeme adımı.

## Genel Bakış

Sepet fiyatlaması **üç aşamalı bir zincirdir** ve her aşamanın kendi filtresi vardır: önce ham girdiler, sonra fiyatlanmış kalemler, en sonunda özet. Zincirin sırasını bilmek, kuralınızı **doğru halkaya** yazmanızı sağlar.

Yanlış halka seçmek sessizce başarısız olur: kalem filtresinde toplamı değiştirirseniz özet onu **yeniden hesaplayıp** ezer.

## Referans

### Sepete eklemeyi durdurma

gateorder.cart_add

`Cart` ürün doğrulanmış

Ürün sepete yazılmadan önce çalışır; ürün ve döngü **doğrulanmış** hâldedir.

Parametreler 3

$productarrayÜrün kaydı: kimlik, tip, ad, stok, ek hizmetler, seçenekler. Satışa açık olduğu doğrulanmıştır.

$cyclestringSeçilen faturalama döngüsü. Ürünün gerçekten sunduğu döngülerden biri olduğu doğrulanmıştır.

$itemarraySepete yazılacak satır: tür, ürün kimliği, döngü, adet, yapılandırılmış işareti, seçenekler.

Dönüş 1

stringBoş olmayan bir string işlemi **durdurur**; metin müşteriye hata olarak gösterilir.

Dinleyici PHP

```php
Hook::add('gate:order.cart_add', 10, function ($product, $cycle, $item) {
    // Stok kontrolu cekirdekte var; siz is kuralinizi ekleyin.
    if (Acme::limitReached($product['id'] ?? 0))
        return 'Bu urun icin gunluk siparis siniri doldu.';

    return null;
});
```

### Ham girdileri değiştirme

filterorder.cart_inputs

`Orders::buildCart()` zincirin ilk halkası

Fiyatlama başlamadan önce, ham sipariş girdileri üzerinde çalışır.

Parametreler 2

$inputsarrayrefHam girdiler; her eleman kendi grubuyla gelir (alan adı, ürün, ek hizmet). Zincirin **başıdır**: buraya kalem eklemek, sonraki iki aşamanın onu **fiyatlamasını** sağlar.

$ucidintFiyatlamanın yapılacağı para birimi.

Dönüş 1

voidDeğer **referansla** değişir; dönüş kullanılmaz.

Dinleyici PHP

```php
Hook::add('filter:order.cart_inputs', 10, function (&$inputs, $ucid) {
    // Zincirin BASI: buraya eklenen kalemi cekirdek fiyatlar.
    if (Acme::freeSslCampaign())
        $inputs[] = ['group' => 'product', 'product_id' => Acme::SSL_ID, 'cycle' => 'annually'];
});
```

### Fiyatlanmış kalemleri değiştirme

filterorder.cart_items

`Orders::buildCart()` zincirin ikinci halkası

Kalemler fiyatlandıktan sonra, özet kurulmadan önce çalışır.

Parametreler 4

$itemsarrayrefFiyatlanmış satırlar: tip, ürün ya da uzantı, birim fiyat, toplam, vergiye tabi tutar, ek hizmetler, bayi indirimi. Satır toplamını değiştirebilirsiniz, ama **genel toplam** bir sonraki aşamada yeniden hesaplanır.

$user_idintSipariş sahibi.

$user_currencyintSipariş para birimi.

$dealershiparrayMüşterinin bayilik ayarları, çözülmüş hâlde.

Dönüş 1

voidDeğer **referansla** değişir; dönüş kullanılmaz.

Dinleyici PHP

```php
Hook::add('filter:order.cart_items', 10,
    function (&$items, $user_id, $user_currency, $dealership) {
        // Satir fiyatini burada degistirin; GENEL toplam bir sonraki asamada kurulur.
        foreach ($items as &$i)
            if (Acme::bundleEligible($i)) $i['price'] = Acme::bundlePrice($i);
    });
```

### Sepet özetini değiştirme

filterorder.cart_totals

`Orders::buildCart()` zincirin son halkası

Fiyat özeti kurulduktan sonra çalışır — müşterinin göreceği **son** rakamlar buradadır.

Parametreler 5

$summaryarrayrefFiyat özeti: ara toplam, gösterim ara toplamı, bayi indirimi, kupon indirimi, vergi. Zincirin **sonu**: buradaki rakam müşteriye gösterilir ve faturaya gider.

$itemsarrayFiyatlanmış kalemler, bir önceki filtreden geçmiş hâlleriyle. Değiştirilemez bağlam.

$subtotalfloatİndirim ve vergi öncesi ara toplam.

$selectedCouponsarrayHesaba giren kuponlar. Sabit tutarlar müşterinin para birimine **önceden çevrilmiştir**.

$ctxarrayFiyatlama bağlamı: para birimi, vergilendirme tipi, vergi oranları, muafiyet.

Dönüş 1

voidDeğer **referansla** değişir; dönüş kullanılmaz.

Dinleyici PHP

```php
Hook::add('filter:order.cart_totals', 10,
    function (&$summary, $items, $subtotal, $selectedCoupons, $ctx) {
        // Zincirin SONU: burada yazdiginiz rakam musteriye gorunur.
        if (Acme::minimumOrder() > (float) $summary['subtotal'])
            $summary['acme_notice'] = Acme::minimumNotice();
    });
```

### Ödeme adımını durdurma

gateorder.checkout

`ClientCheckout` kalemler fiyatsız

Sipariş kurulmadan önce çalışır. **Misafir buraya ulaşamaz**: giriş denetimi daha önce çalışır.

Parametreler 2

$memberarrayGiriş yapmış üyenin kaydı.

$cartItemsarrayHam sepet satırları. **Henüz fiyatlanmamıştır**: tutara bağlı bir kural yazacaksanız fiyatları kendiniz hesaplayın ya da özet filtresini kullanın.

Dönüş 1

stringBoş olmayan bir string işlemi **durdurur**; metin müşteriye hata olarak gösterilir.

Dinleyici PHP

```php
Hook::add('gate:order.checkout', 10, function ($member, $cartItems) {
    // Kalemler HENUZ fiyatsiz: tutara bakan kurali burada yazmayin.
    if (Acme::fraudScore((int) ($member['id'] ?? 0)) > 80)
        return 'Siparisiniz inceleme gerektiriyor; destek ekibi sizinle iletisime gececek.';

    return null;
});
```

### Siparişin kurulduğunu öğrenme

actionorder.checkout_completed

`ClientCheckout` fatura ödenmemiş

Sipariş kurulduktan sonra çalışır. Faturası bu noktada **ödenmemiştir**.

Parametreler 4

$order_idintKurulan siparişin kimliği.

$invoice_idintSiparişin faturası. Şu an ödenmemiştir; sıfır tutarlı ya da bakiyeden ödenen sipariş **bu kancadan sonra** aynı istekte kapanır.

$pmethodstringÇözülmüş ödeme yöntemi. Sıfır tutarlı siparişte `Free`; saklı kartta gerçek kuruluş modülünün adı.

$memberarraySipariş veren üyenin kaydı.

Dönüş 1

voidDönüş yoksayılır.

Dinleyici PHP

```php
Hook::add('action:order.checkout_completed', 10,
    function ($order_id, $invoice_id, $pmethod, $member) {
        // Fatura HENUZ odenmedi: hizmet acmayi odeme kancasina birakin.
        Crm::orderPlaced($order_id, $pmethod, (string) ($member['email'] ?? ''));
    });
```

### Kupon indirimini değiştirme

filterorder.coupon_discount

`Orders` hesaplanmış indirim

Kupon indirimi hesaplandıktan sonra çalışır.

Parametreler 1

$discountarrayrefHesaplanan indirim. Sepet özetine girer; özet filtresinden **önce** çalışır.

Dönüş 1

voidDeğer **referansla** değişir; dönüş kullanılmaz.

Dinleyici PHP

```php
Hook::add('filter:order.coupon_discount', 10, function (&$discount) {
    Acme::capCouponDiscount($discount);
});
```

### Sipariş numarasını değiştirme

filterorder.number

`Orders` benzersiz olmalı

Sipariş numarası üretildikten sonra çalışır.

Parametreler 1

$numberstringrefÜretilen numara. Değiştiriyorsanız **benzersizliği kendiniz garanti edin**: çekirdek sizin ürettiğinizi bir daha denetlemez.

Dönüş 1

voidDeğer **referansla** değişir; dönüş kullanılmaz.

Dinleyici PHP

```php
Hook::add('filter:order.number', 10, function (&$number) {
    // Benzersizlik SIZIN sorumlulugunuzda: cakisma siparisi bozar.
    $number = Acme::prefix() . '-' . $number;
});
```

## Tuzaklar

> **Zincirde yanlış halka sessizce ezilir**
> 
> Fiyatlama üç aşamalıdır: girdiler, kalemler, özet. Kalem aşamasında genel toplama dokunmak boşunadır — özet aşaması onu **yeniden hesaplar**. Satır fiyatı kalem filtresine, nihai rakam özet filtresine, yeni bir ürün ise **girdi filtresine** yazılır.

> **Ödeme kapısında kalemler fiyatsızdır**
> 
> Ödeme adımı kapısı size **ham** sepet satırları verir: tutar, indirim ve vergi henüz hesaplanmamıştır. "Şu tutarın üzerindeki siparişi durdur" kuralını buraya yazmak, **olmayan bir alanı** okumaya çalışmaktır.

> **Sipariş kurulmak ödeme değildir**
> 
> Sipariş tamamlandı kancasında fatura **ödenmemiştir**. Hizmet açmak, ek hizmet etkinleştirmek ya da müşteriye teslim yapmak buraya yazılırsa, ödemeyi hiç tamamlamayan bir sipariş de **teslim edilmiş** olur.

> **Numarayı değiştirirseniz benzersizliği siz taşırsınız**
> 
> Sipariş numarası filtresi size üretilmiş numarayı verir. Değiştirdiğinizde çekirdek yeni değeri **bir daha denetlemez**: çakışan bir numara üretirseniz sipariş kaydı bozulur. Kendi ön ekinizi eklemek güvenlidir, numarayı baştan üretmek değildir.

## İlgili Makaleler

- Sipariş Akışı Kancaları
- [Fatura Yaşam Döngüsü Kancaları](https://dev.wisecp.com/tr/fatura-yasam-dongusu-kancalari)
- [Para Birimi ve Kupon Kancaları](https://dev.wisecp.com/tr/para-birimi-kupon-kancalari)