# Adressen

Elk contact heeft een lijst met adressen, elk getypeerd als `shipping`, `billing` of `work`. Per type is hoogstens één adres het standaardadres, en de API dwingt dit transactioneel af: het zetten van `is_default: true` op een adres wist het vorige standaardadres van hetzelfde type in dezelfde operatie. Alle vier de endpoints zijn contact-geauthenticeerd (tenant-API-key plus `X-Customer-Token`); voor het opvragen is de `contacts:read` scope nodig, voor schrijfacties `contacts:write` (`customers:read` / `customers:write` geaccepteerd).

Het adresobject:

| Veld | Type | Beschrijving |
| --- | --- | --- |
| `id` | string (uuid) | Adres-id. |
| `type` | string | `shipping`, `billing` of `work`. |
| `label` | string of null | Contactgericht label, bijvoorbeeld `Home`. |
| `is_default` | boolean | Of dit het standaardadres van zijn type is. |
| `name` | string | Naam van de ontvanger. |
| `street` | string | Straat en huisnummer. |
| `postal_code` | string | Postcode. |
| `city` | string | Plaats. |
| `country` | string | ISO 3166-1 alpha-2-landcode, exact 2 tekens (bijvoorbeeld `NL`). |
| `phone` | string of null | Telefoonnummer. |

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

Ook aangeboden op `/v1/api/customers/me/addresses` voor bestaande integraties; identiek request en response.

Vraag de adressen van het geauthenticeerde contact op. Standaardadressen staan eerst. De lijst is niet gepagineerd; de respons is een gewone `data`-array.

### Headers

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `X-Customer-Token` | string | Ja | Contactsessietoken. |

Geen query-parameters.

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

Status: `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"
    }
  ]
}
```

### Fouten

- `401` `{"message":"Invalid customer token."}` wanneer `X-Customer-Token` ontbreekt of ongeldig is.

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

Ook aangeboden op `/v1/api/customers/me/addresses` voor bestaande integraties; identiek request en response.

Maak een adres aan voor het geauthenticeerde contact. Als `is_default` `true` is, wordt het vorige standaardadres van hetzelfde type atomair gewist in dezelfde transactie.

### Headers

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `X-Customer-Token` | string | Ja | Contactsessietoken. |

### Body-parameters

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `type` | string | Nee | `shipping`, `billing` of `work`. Standaard `shipping`. |
| `label` | string of null | Nee | Label, maximaal 50 tekens. |
| `is_default` | boolean | Nee | Maak dit het standaardadres van zijn type. |
| `name` | string | Ja | Naam van de ontvanger, maximaal 150 tekens. |
| `street` | string | Ja | Straat en huisnummer, maximaal 255 tekens. |
| `postal_code` | string | Ja | Postcode, maximaal 20 tekens. |
| `city` | string | Ja | Plaats, maximaal 100 tekens. |
| `country` | string | Ja | ISO 3166-1 alpha-2-code, exact 2 tekens. |
| `phone` | string of null | Nee | Telefoonnummer, maximaal 50 tekens. |

```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"}'
```

Status: `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"
  }
}
```

### Fouten

- `422` bij veldvalidatiefouten, bijvoorbeeld `errors.country` `["The country field must be 2 characters."]`.
- `401` `{"message":"Invalid customer token."}` wanneer `X-Customer-Token` ontbreekt of ongeldig is.

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

Ook aangeboden op `/v1/api/customers/me/addresses/{id}` voor bestaande integraties; identiek request en response.

Werk een van de adressen van het geauthenticeerde contact gedeeltelijk bij. Dezelfde velden als bij aanmaken, allemaal optioneel; alleen de velden die je stuurt worden gewijzigd. Als het resulterende adres standaard is (ofwel omdat je `is_default: true` hebt gezet, ofwel omdat het adres al standaard was en je zijn `type` hebt gewijzigd), wordt het vorige standaardadres van het resulterende type gewist in dezelfde transactie.

### Pad-parameters

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `id` | string (uuid) | Ja | Adres-id. Moet van het geauthenticeerde contact zijn. |

### Headers

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `X-Customer-Token` | string | Ja | Contactsessietoken. |

### Body-parameters

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `type` | string | Nee | `shipping`, `billing` of `work`. |
| `label` | string of null | Nee | Label, maximaal 50 tekens. |
| `is_default` | boolean | Nee | Maak dit het standaardadres van zijn type. |
| `name` | string | Nee | Naam van de ontvanger, maximaal 150 tekens. |
| `street` | string | Nee | Straat, maximaal 255 tekens. |
| `postal_code` | string | Nee | Postcode, maximaal 20 tekens. |
| `city` | string | Nee | Plaats, maximaal 100 tekens. |
| `country` | string | Nee | ISO 3166-1 alpha-2-code, exact 2 tekens. |
| `phone` | string of null | Nee | Telefoonnummer, maximaal 50 tekens. |

```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}'
```

Status: `200 OK`. Retourneert het bijgewerkte adres.

```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"
  }
}
```

### Fouten

- `404` wanneer het adres niet bestaat of van een ander contact is.
- `422` bij veldvalidatiefouten.
- `401` `{"message":"Invalid customer token."}` wanneer `X-Customer-Token` ontbreekt of ongeldig is.

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

Ook aangeboden op `/v1/api/customers/me/addresses/{id}` voor bestaande integraties; identiek request en response.

Verwijder een van de adressen van het geauthenticeerde contact (soft delete: het verdwijnt uit de API maar wordt intern bewaard).

### Pad-parameters

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `id` | string (uuid) | Ja | Adres-id. Moet van het geauthenticeerde contact zijn. |

### Headers

| Naam | Type | Verplicht | Beschrijving |
| --- | --- | --- | --- |
| `X-Customer-Token` | string | Ja | Contactsessietoken. |

```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"
```

Status: `204 No Content`. De respons heeft geen body.

### Fouten

- `404` wanneer het adres niet bestaat of van een ander contact is.
- `401` `{"message":"Invalid customer token."}` wanneer `X-Customer-Token` ontbreekt of ongeldig is.