# Kunder (/api/referens/customers)

> Kundregistret – lista, skapa, hämta, uppdatera och inaktivera kunder via /3/customers.

Kundresursen speglar Fortnox `/3/customers`. Kunden adresseras på sitt kundnummer (`CustomerNumber`), inte på ett internt id, och numret kan inte ändras när det väl är satt.

**Scope:** `customer` · <Plan min="ai_pro" />

## Endpoints [#endpoints]

| Metod och sökväg | Beskrivning |
|---|---|
| <Endpoint method="GET" path="/api/v1/3/customers" /> | Lista kunder (reducerad listform) |
| <Endpoint method="POST" path="/api/v1/3/customers" /> | Skapa en kund. Svarar `201`. |
| <Endpoint method="GET" path="/api/v1/3/customers/{CustomerNumber}" /> | Hämta en kund (fullständig form) |
| <Endpoint method="PUT" path="/api/v1/3/customers/{CustomerNumber}" /> | Uppdatera en kund (partiellt) |
| <Endpoint method="DELETE" path="/api/v1/3/customers/{CustomerNumber}" /> | Inaktivera en kund. Svarar `204`. |

Bas-URL: `https://app.klirr.ai/api/v1`. Skrivningar kuverteras i `Customer`.

## Listparametrar [#listparametrar]

Utöver [paginering](/api/paginering) (`page`, `limit`, `offset`) och `sortorder` (`asc`/`desc`, även `ascending`/`descending`):

| Parameter | Värden | Beskrivning |
|---|---|---|
| `filter` | `active`, `inactive` | Utan filter (eller med okänt värde) returneras alla kunder. |
| `sortby` | `customernumber`, `name` | Standard är `customernumber`. |
| `customernumber` | text | Exakt kundnummer. |
| `name` | text | Sökning i namnet. |
| `organisationnumber` | text | Sökning i organisationsnumret. |
| `email` | text | Sökning i e-postadressen. |

Bara **en** av `name`, `organisationnumber` och `email` kan användas per anrop. Skickar du flera, eller någon av de Fortnox-parametrar Klirr inte stöder ännu (`zipcode`, `city`, `phone`, `gln`, `glndelivery`, `lastmodified`), svarar API:t `400` i stället för att tyst returnera ett ofiltrerat svar.

## Fält [#fält]

Fullständig form (`GET /3/customers/{CustomerNumber}`, och svaret på `POST`/`PUT`).

| Fält | Typ | Skrivskyddat | Beskrivning |
|---|---|---|---|
| `@url` | string | ja | Resursens URL i Klirr. |
| `CustomerNumber` | string | efter skapande | Kundnummer. Utelämnas det vid `POST` tilldelas nästa lediga nummer. Kan inte ändras. |
| `Name` | string | nej | **Obligatoriskt vid `POST`.** Max 1024 tecken. |
| `OrganisationNumber` | string | nej | Organisationsnummer (eller personnummer för privatkund). |
| `VATNumber` | string | nej | Momsregistreringsnummer. |
| `Email` | string | nej | E-post. |
| `EmailInvoice` | string | nej | Delar värde med `Email` i Klirr. Skickas båda vinner `Email`. |
| `Phone1` | string | nej | Telefon. |
| `Address1` | string | nej | Adress. |
| `ZipCode` | string | nej | Postnummer. |
| `City` | string | nej | Ort. |
| `Country` | string | ja | Svenskt landsnamn, härlett ur `CountryCode`. |
| `CountryCode` | string | nej | Landskod, två tecken. |
| `Currency` | string | nej | Standard `SEK`. Bärs vidare oförändrat. |
| `Active` | boolean | nej | `false` för inaktiverad kund. |
| `Comments` | string | nej | Anteckning, max 1024 tecken. |
| `Type` | `COMPANY` \| `PRIVATE` | ja | Härleds: `COMPANY` om organisationsnummer finns, annars `PRIVATE`. Värdet du skickar läses inte. |
| `VATType` | `SEVAT` \| `SEREVERSEDVAT` \| `EUREVERSEDVAT` \| `EUVAT` \| `EXPORT` | nej | Standard `SEVAT`. Bärs vidare; momsbehandlingen i Klirr sätts per faktura. |
| `TermsOfPayment` | string | nej | Betalningsvillkorskod, t.ex. `"30"`. Bärs vidare. |
| `DefaultDeliveryTypes` | object | nej | `{ Invoice, Order, Offer }`, vardera `PRINT`, `EMAIL` eller `PRINTSERVICE`. Standard `EMAIL`. |

Fält som Klirr inte modellerar (till exempel `Phone2`, `DeliveryAddress1`, `GLN`, `YourReference`) sparas och returneras oförändrade.

### Listform [#listform]

`GET /3/customers` returnerar en reducerad rad med exakt dessa fält: `@url`, `Address1`, `Address2`, `City`, `CustomerNumber`, `Email`, `Name`, `OrganisationNumber`, `Phone`, `ZipCode`. Observera att telefon heter `Phone` i listan men `Phone1` i den fullständiga formen.

## Skapa en kund [#skapa-en-kund]

<Tabs groupId="lang" persist items={['curl','TypeScript']}>
<Tab value="curl">
```bash
curl -X POST https://app.klirr.ai/api/v1/3/customers \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"Customer":{"Name":"Bergström Bygg AB","OrganisationNumber":"556000-0000","Email":"faktura@bergstrombygg.se","City":"Uppsala"}}'
```
</Tab>
<Tab value="TypeScript">
```ts
const res = await fetch('https://app.klirr.ai/api/v1/3/customers', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <access_token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    Customer: {
      Name: 'Bergström Bygg AB',
      OrganisationNumber: '556000-0000',
      Email: 'faktura@bergstrombygg.se',
      City: 'Uppsala',
    },
  }),
});
const { Customer } = await res.json(); // 201 Created
```
</Tab>
</Tabs>

Svar (`201`):

```json
{
  "Customer": {
    "@url": "https://app.klirr.ai/api/v1/3/customers/1001",
    "CustomerNumber": "1001",
    "Name": "Bergström Bygg AB",
    "OrganisationNumber": "556000-0000",
    "VATNumber": "",
    "Email": "faktura@bergstrombygg.se",
    "EmailInvoice": "faktura@bergstrombygg.se",
    "Phone1": "",
    "Address1": "",
    "ZipCode": "",
    "City": "Uppsala",
    "Country": "Sverige",
    "CountryCode": "SE",
    "Currency": "SEK",
    "Active": true,
    "Comments": "",
    "Type": "COMPANY",
    "VATType": "SEVAT",
    "TermsOfPayment": "",
    "DefaultDeliveryTypes": { "Invoice": "EMAIL", "Order": "EMAIL", "Offer": "EMAIL" }
  }
}
```

## Lista kunder [#lista-kunder]

<Tabs groupId="lang" persist items={['curl','TypeScript']}>
<Tab value="curl">
```bash
curl "https://app.klirr.ai/api/v1/3/customers?filter=active&sortby=name&limit=50" \
  -H "Authorization: Bearer <access_token>"
```
</Tab>
<Tab value="TypeScript">
```ts
const res = await fetch(
  'https://app.klirr.ai/api/v1/3/customers?filter=active&sortby=name&limit=50',
  { headers: { Authorization: 'Bearer <access_token>' } },
);
const { Customers, MetaInformation } = await res.json();
```
</Tab>
</Tabs>

```json
{
  "Customers": [
    {
      "@url": "https://app.klirr.ai/api/v1/3/customers/1001",
      "Address1": "",
      "Address2": "",
      "City": "Uppsala",
      "CustomerNumber": "1001",
      "Email": "faktura@bergstrombygg.se",
      "Name": "Bergström Bygg AB",
      "OrganisationNumber": "556000-0000",
      "Phone": "",
      "ZipCode": ""
    }
  ],
  "MetaInformation": { "@TotalResources": 1, "@TotalPages": 1, "@CurrentPage": 1 }
}
```

## Uppdatera en kund [#uppdatera-en-kund]

`PUT` ändrar bara de fält du skickar. Använd `"API_BLANK"` för att tömma ett textfält. Se [Fortnox-kompatibilitet](/api/fortnox-kompatibilitet).

<Tabs groupId="lang" persist items={['curl','TypeScript']}>
<Tab value="curl">
```bash
curl -X PUT https://app.klirr.ai/api/v1/3/customers/1001 \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"Customer":{"Phone1":"018-000 00 00"}}'
```
</Tab>
<Tab value="TypeScript">
```ts
await fetch('https://app.klirr.ai/api/v1/3/customers/1001', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer <access_token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ Customer: { Phone1: '018-000 00 00' } }),
});
```
</Tab>
</Tabs>

## Inaktivera en kund [#inaktivera-en-kund]

`DELETE` raderar inte kunden. Den inaktiveras (`Active: false`), eftersom bokförda fakturor refererar till den. Svaret är `204`, och kunden finns kvar på sin URL.

## Fel [#fel]

| Status | `Code` | När |
|---|---|---|
| 400 | 9000400 | `Name` saknas, ostödd sökparameter, fler än en sökparameter, eller `API_BLANK` på `Name`. |
| 404 | 9000404 | `Kan inte hitta kunden`. |
| 409 | 9000409 | Kundnumret används redan, eller organisationsnumret används redan av en annan kund. |

Allmänna fel (401, 403, 429) beskrivs under [Felkoder](/api/felkoder).