# Klanten

`GET` en `POST /api/v1/customers`. Klanten zijn de ontvangers van facturen en checkouts.

## Klanten ophalen

`GET /api/v1/customers` vraagt `customers:read` en geeft de honderd nieuwste klanten terug.

```json
{
  "data": [
    {
      "id": "c0a8…",
      "company_name": "Bakkerij De Korenaar",
      "contact_name": null,
      "email": "sanne@korenaar.nl",
      "city": "Utrecht"
    }
  ]
}
```

## Klant aanmaken

`POST /api/v1/customers` vraagt `customers:write` en accepteert `Idempotency-Key`.

| Veld | Type | Verplicht | Toelichting |
| --- | --- | --- | --- |
| `name` | string | of `companyName` | Naam van de klant |
| `companyName` | string | of `name` | Bedrijfsnaam, komt op de factuur |
| `email` | string | nee | E-mailadres voor verzending |
| `externalId` | string | nee | Jouw eigen id, zie dedupe hieronder |
| `addressLine1` | string | nee | Straat en huisnummer |
| `postalCode` | string | nee | Postcode |
| `city` | string | nee | Plaats |
| `countryCode` | string | nee | ISO-landcode, standaard `NL` |
| `btwId` | string | nee | Btw-identificatienummer |
| `kvkNumber` | string | nee | KvK-nummer |

```bash
curl https://api.cijfr.com/api/v1/customers \
  -H "Authorization: Bearer $CIJFR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: customer-sync-42" \
  -d '{
    "companyName": "Bakkerij De Korenaar",
    "email": "sanne@korenaar.nl",
    "addressLine1": "Dorpsstraat 12",
    "postalCode": "3511 AB",
    "city": "Utrecht",
    "kvkNumber": "12345678",
    "externalId": "shop-customer-42"
  }'
```

```json
{ "data": { "id": "c0a8…" } }
```

> Dedupe: stuur je `externalId` én `email` mee en bestaat er al een klant met dat e-mailadres, dan krijg je de bestaande `id` terug met status `200` in plaats van een duplicaat.