> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# Versiyonlama

> API versiyon politikası ve geriye dönük uyumluluk.

Payven API'leri **URL tabanlı versiyonlama** kullanır. Şu an aktif tek versiyon `v1`'dir.

## URL formatı

```
https://vpos.payven.com.tr/api/v1/payments
                                ^^^
                            versiyon segmenti
```

## Geriye dönük uyumluluk

Bir versiyon içinde aşağıdaki değişiklikler **breaking change** kabul edilmez ve önceden duyurulmadan yapılabilir:

* Yeni opsiyonel alan eklenmesi (request veya response)
* Yeni endpoint eklenmesi
* Yeni opsiyonel header eklenmesi
* Yeni hata kodu eklenmesi
* Yeni webhook olayı eklenmesi
* Yanıt alanlarının sıralamasının değişmesi
* Hata yanıtındaki `title` ve `detail` metinlerinde dil/ifade değişiklikleri (kod (`code`) sabit kalır)

İstemcinizi bu tip değişikliklere **toleranslı** yazın:

<Check>Bilmediğiniz alanları yok sayın.</Check>
<Check>Bilmediğiniz hata kodlarında HTTP durum kodu kategorisine (4xx / 5xx) göre fallback davranış tanımlayın.</Check>
<Check>Webhook payload'unda bilmediğiniz `type` değerlerini yok sayın, hata fırlatmayın.</Check>

## Breaking change'ler

Aşağıdaki değişiklikler **breaking change** kabul edilir ve **yalnızca yeni bir major versiyonda** yapılır:

* Mevcut alanın silinmesi veya isminin değişmesi
* Mevcut alanın tipinin değişmesi
* Mevcut endpoint'in URL'sinin değişmesi
* Mevcut zorunlu alanın eklenmesi
* Yanıt yapısının yeniden organize edilmesi

## Versiyon yaşam döngüsü

| Aşama       | Süre        | Açıklama                                               |
| ----------- | ----------- | ------------------------------------------------------ |
| Aktif       | Süresiz     | Yeni özellikler eklenir, üretimde tam destekle çalışır |
| Deprecation | En az 12 ay | Yeni versiyon yayınlandıktan sonra uyarı süresi        |
| Sunset      | —           | Tamamen kapatılır (en az 12 aylık geçişten sonra)      |

Deprecation döneminde ilgili endpoint'ler `Deprecation` ve `Sunset` HTTP başlıkları döner:

```http theme={null}
Deprecation: Sun, 01 Jan 2027 00:00:00 GMT
Sunset:      Sun, 01 Jan 2028 00:00:00 GMT
```

## Yeni versiyon nasıl duyurulur?

<Steps>
  <Step title="Beta yayını">
    Yeni versiyon `v2-beta` olarak duyurulur, yorum/feedback toplanır.
  </Step>

  <Step title="Stabil versiyon yayını">
    Geri bildirim sonrası `v2` stabil sürüm olarak yayına alınır (GA — Generally Available). `v1` aktif kalmaya devam eder.
  </Step>

  <Step title="Migration rehberi">
    Tüm breaking change'lerin listesi ve geçiş adımları yayınlanır. [Changelog](/resources/changelog) takip edilir.
  </Step>

  <Step title="Deprecation süreci">
    `v1` deprecation süresine alınır (minimum 12 ay).
  </Step>
</Steps>

<Tip>
  [Changelog](/resources/changelog) sayfasını izleyin ve [destek ekibinize](/resources/support) güncel iletişim kanalı (e-posta, webhook bildirim listesi) bildirin — kritik değişikliklerde önceden uyarılırsınız.
</Tip>