# Adresler

Her kişinin, her biri `shipping`, `billing` veya `work` türünde olan bir adres listesi vardır. Tür başına en fazla bir adres varsayılandır ve API bunu transaksiyonel olarak uygular: bir adreste `is_default: true` ayarlamak, aynı işlemde aynı türün önceki varsayılanını temizler. Dört endpoint de kişi kimliği doğrulanmış endpoint'lerdir (tenant API anahtarı artı `X-Customer-Token`); listeleme `contacts:read`, yazma işlemleri `contacts:write` scope'una ihtiyaç duyar (`customers:read` / `customers:write` kabul edilir).

Adres nesnesi:

| Alan | Tür | Açıklama |
| --- | --- | --- |
| `id` | string (uuid) | Adres id'si. |
| `type` | string | `shipping`, `billing` veya `work`. |
| `label` | string or null | Kişiye dönük etiket, örneğin `Home`. |
| `is_default` | boolean | Bu adresin kendi türünün varsayılanı olup olmadığı. |
| `name` | string | Alıcı adı. |
| `street` | string | Sokak ve kapı numarası. |
| `postal_code` | string | Posta kodu. |
| `city` | string | Şehir. |
| `country` | string | ISO 3166-1 alpha-2 ülke kodu, tam olarak 2 karakter (örneğin `NL`). |
| `phone` | string or null | Telefon numarası. |

## GET /v1/api/contacts/me/addresses

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

Kimliği doğrulanmış kişinin adreslerini listeler. Varsayılan adresler önce sıralanır. Liste sayfalanmaz; response düz bir `data` dizisidir.

### Header'lar

| Ad | Tür | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `X-Customer-Token` | string | Evet | Kişi oturum token'ı. |

Query parametresi yoktur.

```bash title="Request"
curl https://api.borkol.com/v1/api/contacts/me/addresses \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz"
```

Durum: `200 OK`.

```json title="Response"
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "shipping",
      "label": "Home",
      "is_default": true,
      "name": "Jane Doe",
      "street": "Keizersgracht 123",
      "postal_code": "1015 CJ",
      "city": "Amsterdam",
      "country": "NL",
      "phone": "+31612345678"
    }
  ]
}
```

### Hatalar

- `X-Customer-Token` eksik veya geçersiz olduğunda `401` `{"message":"Invalid customer token."}`.

## POST /v1/api/contacts/me/addresses

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

Kimliği doğrulanmış kişi için bir adres oluşturur. `is_default` `true` ise, aynı türün önceki varsayılanı aynı transaksiyonda atomik olarak temizlenir.

### Header'lar

| Ad | Tür | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `X-Customer-Token` | string | Evet | Kişi oturum token'ı. |

### Body parametreleri

| Ad | Tür | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `type` | string | Hayır | `shipping`, `billing` veya `work`. Varsayılan `shipping`. |
| `label` | string or null | Hayır | Etiket, en fazla 50 karakter. |
| `is_default` | boolean | Hayır | Bu adresi kendi türünün varsayılanı yapar. |
| `name` | string | Evet | Alıcı adı, en fazla 150 karakter. |
| `street` | string | Evet | Sokak ve kapı numarası, en fazla 255 karakter. |
| `postal_code` | string | Evet | Posta kodu, en fazla 20 karakter. |
| `city` | string | Evet | Şehir, en fazla 100 karakter. |
| `country` | string | Evet | ISO 3166-1 alpha-2 kodu, tam olarak 2 karakter. |
| `phone` | string or null | Hayır | Telefon numarası, en fazla 50 karakter. |

```bash title="Request"
curl -X POST https://api.borkol.com/v1/api/contacts/me/addresses \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz" \
  -H "Content-Type: application/json" \
  -d '{"type":"shipping","label":"Home","is_default":true,"name":"Jane Doe","street":"Keizersgracht 123","postal_code":"1015 CJ","city":"Amsterdam","country":"NL","phone":"+31612345678"}'
```

Durum: `201 Created`.

```json title="Response"
{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "type": "shipping",
    "label": "Home",
    "is_default": true,
    "name": "Jane Doe",
    "street": "Keizersgracht 123",
    "postal_code": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "phone": "+31612345678"
  }
}
```

### Hatalar

- Alan doğrulama hataları için `422`, örneğin `errors.country` `["The country field must be 2 characters."]`.
- `X-Customer-Token` eksik veya geçersiz olduğunda `401` `{"message":"Invalid customer token."}`.

## PATCH /v1/api/contacts/me/addresses/{id}

Mevcut entegrasyonlar için `/v1/api/customers/me/addresses/{id}` üzerinde de sunulur; request ve response birebir aynıdır.

Kimliği doğrulanmış kişinin adreslerinden birini kısmen günceller. Oluşturmayla aynı alanlar, tümü isteğe bağlı; yalnızca gönderdiğiniz alanlar değişir. Sonuçta oluşan adres varsayılansa (ya `is_default: true` ayarladığınız için ya da adres zaten varsayılanken `type` alanını değiştirdiğiniz için), sonuç türünün önceki varsayılanı aynı transaksiyonda temizlenir.

### Path parametreleri

| Ad | Tür | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `id` | string (uuid) | Evet | Adres id'si. Kimliği doğrulanmış kişiye ait olmalıdır. |

### Header'lar

| Ad | Tür | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `X-Customer-Token` | string | Evet | Kişi oturum token'ı. |

### Body parametreleri

| Ad | Tür | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `type` | string | Hayır | `shipping`, `billing` veya `work`. |
| `label` | string or null | Hayır | Etiket, en fazla 50 karakter. |
| `is_default` | boolean | Hayır | Bu adresi kendi türünün varsayılanı yapar. |
| `name` | string | Hayır | Alıcı adı, en fazla 150 karakter. |
| `street` | string | Hayır | Sokak, en fazla 255 karakter. |
| `postal_code` | string | Hayır | Posta kodu, en fazla 20 karakter. |
| `city` | string | Hayır | Şehir, en fazla 100 karakter. |
| `country` | string | Hayır | ISO 3166-1 alpha-2 kodu, tam olarak 2 karakter. |
| `phone` | string or null | Hayır | Telefon numarası, en fazla 50 karakter. |

```bash title="Request"
curl -X PATCH https://api.borkol.com/v1/api/contacts/me/addresses/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz" \
  -H "Content-Type: application/json" \
  -d '{"label":"Office","is_default":false}'
```

Durum: `200 OK`. Güncellenmiş adresi döner.

```json title="Response"
{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "type": "shipping",
    "label": "Office",
    "is_default": false,
    "name": "Jane Doe",
    "street": "Keizersgracht 123",
    "postal_code": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "phone": "+31612345678"
  }
}
```

### Hatalar

- Adres yoksa veya başka bir kişiye aitse `404`.
- Alan doğrulama hataları için `422`.
- `X-Customer-Token` eksik veya geçersiz olduğunda `401` `{"message":"Invalid customer token."}`.

## DELETE /v1/api/contacts/me/addresses/{id}

Mevcut entegrasyonlar için `/v1/api/customers/me/addresses/{id}` üzerinde de sunulur; request ve response birebir aynıdır.

Kimliği doğrulanmış kişinin adreslerinden birini siler (soft delete: API'den kaybolur ancak dahili olarak saklanır).

### Path parametreleri

| Ad | Tür | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `id` | string (uuid) | Evet | Adres id'si. Kimliği doğrulanmış kişiye ait olmalıdır. |

### Header'lar

| Ad | Tür | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `X-Customer-Token` | string | Evet | Kişi oturum token'ı. |

```bash title="Request"
curl -X DELETE https://api.borkol.com/v1/api/contacts/me/addresses/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz"
```

Durum: `204 No Content`. Response'un gövdesi yoktur.

### Hatalar

- Adres yoksa veya başka bir kişiye aitse `404`.
- `X-Customer-Token` eksik veya geçersiz olduğunda `401` `{"message":"Invalid customer token."}`.