> For the complete documentation index, see [llms.txt](https://docs.cootje.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cootje.com/cootje-api/klant-inlener/klant-registreren.md).

# Klant registreren

Een klant registreren met het KvK-nummer, als het bedrijf nog niet in Cootje staat.

De klant, ook wel inlener, is het bedrijf waar de professional gaat werken. Dat bedrijf registreer je in Cootje als klant. Deze stap is alleen nodig als het bedrijf er nog niet in staat.

* **Vereist recht:** Bedrijfsinformatie bewerken (voor het zoeken volstaat Bedrijfsinformatie inzien)

## Stap 1: controleren of het bedrijf al bestaat

* **Aanroep:** `POST /organizations/companies/query`
* **Verplicht:** niets
* **Optioneel:** `filter`, `sortBy`, `top` en `select`

Een KvK-nummer met hetzelfde vestigingsnummer kan maar één keer in een omgeving voorkomen. Zoek daarom eerst op het KvK-nummer:

```bash
curl -X POST "https://mijn.cootje.com/api/organizations/companies/query" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "filter": {
        "field": "kvkNummer",
        "op": "eq",
        "value": "12345678"
      }
    }
  }'
```

Een voorwaarde in `filter` bestaat uit `field` (het veld), `op` (de vergelijking, hier `eq` voor "gelijk aan") en `value` (de waarde).

Bestaat het bedrijf al, dan krijg je een lijst met dat bedrijf terug, in de vorm die je onderaan deze pagina ziet. Gebruik dan het `_id` uit dat antwoord en sla stap 2 over. Bestaat het nog niet, dan is de lijst leeg:

```json
[]
```

## Stap 2: het bedrijf registreren

* **Aanroep:** `POST /organizations/companies`

Naam, rechtsvorm en adres haalt Cootje zelf op bij de KvK.

### Verplichte velden

| Veld             | Soort  | Toelichting                               |
| ---------------- | ------ | ----------------------------------------- |
| `kvK`            | tekst  | Het KvK-nummer: 8 cijfers, zonder spaties |
| `phone`          | tekst  | Telefoonnummer                            |
| `billingAddress` | tekst  | Het e-mailadres voor facturen             |
| `genericAddress` | tekst  | Het algemene e-mailadres                  |
| `isCustomer`     | ja/nee | `true`: het bedrijf is klant              |

### Verplicht in bepaalde gevallen

| Situatie                                          | Dan verplicht                       |
| ------------------------------------------------- | ----------------------------------- |
| Je stuurt een bankrekening mee (`bankAccount`)    | `iban` (een geldig IBAN) en `type`  |
| Je stuurt `wtta` mee met `status` `1` (toelating) | `wtta.number`, het toelatingsnummer |

### Optionele velden

| Veld               | Soort           | Toelichting                                                                                                                                  |
| ------------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `vestigingsNummer` | tekst           | Het vestigingsnummer. Laat je het weg, dan kiest Cootje de eerste vestiging die bij het KvK-nummer hoort                                     |
| `btw`              | tekst           | Het btw-nummer. Cootje controleert het en zet `btwValidated`                                                                                 |
| `bankAccount`      | object          | Bankrekening van het bedrijf: `iban` en `type` (`1` gewone rekening, `2` G-rekening)                                                         |
| `isSupplier`       | ja/nee          | `true` als het bedrijf ook leverancier is                                                                                                    |
| `wtta`             | object          | Vastlegging voor de Wet toelating terbeschikkingstelling van arbeidskrachten: `status` (`0` geen, `1` toelating, `2` ontheffing) en `number` |
| `departments`      | lijst met tekst | Namen van afdelingen                                                                                                                         |

### Voorbeeld

```bash
curl -X POST "https://mijn.cootje.com/api/organizations/companies" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kvK": "12345678",
    "phone": "0301234567",
    "billingAddress": "facturen@voorbeeld.nl",
    "genericAddress": "info@voorbeeld.nl",
    "isCustomer": true
  }'
```

### Wat je terugkrijgt

Het aangemaakte bedrijf, met het nieuwe `_id` en de gegevens van de KvK:

```json
{
  "kvkNummer": "12345678",
  "indNonMailing": "Nee",
  "naam": "Voorbeeld Zorg B.V.",
  "formeleRegistratiedatum": "20150622000000000",
  "materieleRegistratie": {
    "datumAanvang": "20150601"
  },
  "totaalWerkzamePersonen": 25,
  "handelsnamen": [
    {
      "naam": "Voorbeeld Zorg B.V.",
      "volgorde": 0,
      "isStatutaireNaamFallback": false
    }
  ],
  "sbiActiviteiten": [
    {
      "sbiCode": "86101",
      "sbiOmschrijving": "Universitair medische centra",
      "indHoofdactiviteit": "Ja"
    }
  ],
  "_id": "0b7c2f6e-3d1a-4f5b-9a8e-1c2d3e4f5a6b",
  "btw": "",
  "btwValidated": false,
  "phone": "0301234567",
  "statutaireNaam": "Voorbeeld Zorg B.V.",
  "legalName": "Voorbeeld Zorg B.V.",
  "genericAddress": "info@voorbeeld.nl",
  "billingAddress": "facturen@voorbeeld.nl",
  "vestigingsNummer": "000012345678",
  "departments": [],
  "rechtsvorm": 1,
  "address": {
    "street": "Voorbeeldlaan",
    "houseNumber": "100",
    "houseNumberAddition": "",
    "city": "Utrecht",
    "zipcode": "3584 CX",
    "country": "NL"
  },
  "kvkAddress": {
    "isBezoekAdres": true,
    "type": "bezoekadres",
    "indAfgeschermd": "Nee",
    "volledigAdres": "Voorbeeldlaan 100 3584CX Utrecht",
    "straatnaam": "Voorbeeldlaan",
    "huisnummer": 100,
    "huisnummerToevoeging": null,
    "huisletter": null,
    "toevoegingAdres": null,
    "postcode": "3584CX",
    "plaats": "Utrecht",
    "straatHuisnummer": "Voorbeeldlaan 100",
    "postcodeWoonplaats": "3584CX Utrecht",
    "regio": "Utrecht",
    "land": "Nederland",
    "postbusnummer": null,
    "isHidden": false,
    "isEmpty": false
  },
  "isAddressIncomplete": false,
  "isSupplier": false,
  "isCustomer": true,
  "snaCertified": false,
  "wtta": {
    "status": 0,
    "number": ""
  },
  "isForeign": false,
  "isValidated": true
}
```

* `billingAddress` en `genericAddress` zijn e-mailadressen: het adres voor facturen en het algemene adres. Het postadres staat in `address`.
* De velden bovenaan (`kvkNummer` tot en met `sbiActiviteiten`) en `kvkAddress` komen rechtstreeks van de KvK, in de vorm waarin de KvK ze levert.
* `rechtsvorm` is een getal, bijvoorbeeld `1` voor een bv, `2` voor een nv, `3` voor een vof, `4` voor een eenmanszaak en `5` voor een stichting.
* `wtta.status` is `0` (geen), `1` (toelating) of `2` (ontheffing).
* `btwValidated` is `true` als het btw-nummer is bevestigd.

Klopt de invoer niet, dan is het antwoord een lijst met fouten:

```json
[
  {
    "propertyName": "Phone",
    "errorMessage": "Telefoonnummer is verplicht"
  }
]
```

## Nodig voor een contract

Een contract kan pas definitief worden als de klant aan dit punt voldoet:

* Het adres van het bedrijf is volledig (`isAddressIncomplete` is `false`).

In een contract verwijs je naar de klant in het veld `hirer`. Een vacature verwijst naar de klant in het veld `companyId`.

Staat in het antwoord `isAddressIncomplete` op `true`, dan kon Cootje het adres van de KvK niet omzetten. Vul het adres dan zelf aan met `PUT /organizations/companies/{companyId}/address`. Daarvoor is het recht **Contracten kunnen bewerken** nodig.

```bash
curl -X PUT "https://mijn.cootje.com/api/organizations/companies/0b7c2f6e-3d1a-4f5b-9a8e-1c2d3e4f5a6b/address" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "street": "Voorbeeldlaan",
      "houseNumber": "100",
      "houseNumberAddition": "",
      "zipcode": "3584 CX",
      "city": "Utrecht",
      "country": "NL"
    }
  }'
```

In die aanroep zijn `street`, `zipcode`, `city` en `country` verplicht, en bij een Nederlands adres ook `houseNumber`. Het antwoord is het bijgewerkte bedrijf, in dezelfde vorm als hierboven.

## Buitenlands bedrijf

Een bedrijf dat niet bij de KvK staat, registreer je met `POST /organizations/companies/register-foreign`. Omdat Cootje de gegevens dan niet kan ophalen, geef je ze zelf mee.

| Veld                                                   | Verplicht | Toelichting                                                                    |
| ------------------------------------------------------ | --------- | ------------------------------------------------------------------------------ |
| `cocNumber`                                            | ja        | Het registratienummer in het eigen land. Mag nog niet in de omgeving voorkomen |
| `phone`                                                | ja        | Telefoonnummer                                                                 |
| `billingAddress`                                       | ja        | Het e-mailadres voor facturen                                                  |
| `genericAddress`                                       | ja        | Het algemene e-mailadres                                                       |
| `isCustomer`                                           | ja        | `true`: het bedrijf is klant                                                   |
| `name`                                                 | nee       | De naam van het bedrijf. Niet afgedwongen, maar geef hem altijd mee            |
| `traderName`                                           | nee       | De handelsnaam                                                                 |
| `legalForm`                                            | nee       | De rechtsvorm, als getal: bijvoorbeeld `8` voor een Ltd en `9` voor een Inc    |
| `country`, `address`, `houseNumber`, `zipCode`, `city` | nee       | Het postadres: land, straat, huisnummer, postcode en plaats                    |
| `btw`                                                  | nee       | Het btw-nummer                                                                 |
| `bankAccount`                                          | nee       | `iban` en `type` (`1` gewone rekening, `2` G-rekening)                         |

```bash
curl -X POST "https://mijn.cootje.com/api/organizations/companies/register-foreign" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cocNumber": "HRB 123456",
    "name": "Beispiel GmbH",
    "country": "DE",
    "address": "Musterstraße",
    "houseNumber": "5",
    "zipCode": "10115",
    "city": "Berlin",
    "phone": "+49301234567",
    "billingAddress": "rechnungen@beispiel.de",
    "genericAddress": "info@beispiel.de",
    "isCustomer": true
  }'
```

Het antwoord heeft dezelfde vorm als bij een Nederlands bedrijf, met `isForeign` op `true`.

## Antwoorden

| Code  | Betekenis                                                      |
| ----- | -------------------------------------------------------------- |
| `200` | Bij zoeken: de lijst. Bij registreren: het aangemaakte bedrijf |
| `400` | De invoer klopt niet. Het antwoord is de lijst met fouten      |
| `401` | Geen geldig token, of het account mist het recht               |
