# Parola sıfırlama

Parola sıfırlama iki adımlı bir akıştır: `forgot-password` kişiye bir sıfırlama bağlantısı e-postalar, `reset-password` o bağlantıdaki token'ı tüketir. İkisi de `contacts:write` scope'unu gerektirir (`customers:write` kabul edilir); hiçbiri `X-Customer-Token` gerektirmez. İkisi de IP başına dakikada 10 request'lik ek kimlik bilgisi endpoint'i rate limitini taşır.

Sıfırlama token'ları tek kullanımlıktır, hash'lenerek (SHA-256) saklanır ve verildikten 60 dakika sonra süresi dolar. Sıfırlama bağlantısı, mağazanızın yapılandırılmış storefront URL'sine `{storefront_url}/account/reset?token=...&email=...` biçiminde işaret eder; o path'teki storefront sayfanız her iki query parametresini okuyup `reset-password` endpoint'ine göndermelidir. Mağazada yapılandırılmış bir `storefront_url` yoksa e-posta gönderilmez (endpoint yine de 202 döner).

## POST /v1/api/contacts/forgot-password

Mevcut entegrasyonlar için `/v1/api/customers/forgot-password` üzerinde de sunulur; request ve response birebir aynıdır.

Parola sıfırlama e-postası ister. O e-postaya sahip bir hesap olsun ya da olmasın her zaman aynı gövdeyle 202 döner; böylece endpoint hesapları saymak (enumerate etmek) için kullanılamaz.

### Body parametreleri

| Ad | Tür | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `email` | string | Evet | Geçerli e-posta adresi. Aramadan önce sunucu tarafında küçük harfe çevrilir. |

```bash title="Request"
curl -X POST https://api.borkol.com/v1/api/contacts/forgot-password \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com"}'
```

Durum: `202 Accepted`.

```json title="Response"
{
  "message": "If the account exists, a reset link has been sent."
}
```

### Hatalar

- `email` eksik veya geçerli bir e-posta adresi değilse `422`.
- IP başına dakikada 10 request limiti aşıldığında `429`.

## POST /v1/api/contacts/reset-password

Mevcut entegrasyonlar için `/v1/api/customers/reset-password` üzerinde de sunulur; request ve response birebir aynıdır.

E-postayla gönderilen bağlantıdaki token ile parola sıfırlamayı tamamlar. Başarı durumunda yeni parolayı ayarlar, hesabı misafir olmayan olarak işaretler, ayarlanmamışsa `email_verified_at` alanını ayarlar ve kişinin tüm oturum token'larını iptal eder (tüm cihazların oturumu kapatılır). Geçersiz veya süresi dolmuş bir token hesaba dokunmaz.

### Body parametreleri

| Ad | Tür | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `email` | string | Evet | Geçerli e-posta adresi. Token'ın verildiği hesapla eşleşmelidir. |
| `token` | string | Evet | Sıfırlama bağlantısının `token` query parametresindeki düz token. |
| `password` | string | Evet | Yeni parola. En az 8 karakter. |

```bash title="Request"
curl -X POST https://api.borkol.com/v1/api/contacts/reset-password \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","token":"kJ8s...64-char-token...Qw2","password":"new-s3cret-pass"}'
```

Durum: `200 OK`.

```json title="Response"
{
  "message": "Password updated."
}
```

### Hatalar

- Bilinmeyen e-posta, yanlış token, zaten kullanılmış token veya 60 dakikadan eski token için `errors.token` `["This reset link is invalid or expired."]` ile `422`.
- Alan doğrulama hataları için `422` (eksik alanlar, 8 karakterden kısa parola).
- IP başına dakikada 10 request limiti aşıldığında `429`.