> 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/zzp/concept-contract-opmaken.md).

# Concept contract opmaken

Een conceptcontract voor een zzp'er aanmaken met alleen een contractnummer, de professional en de bedrijven.

Met een conceptcontract leg je de afspraken met de zzp'er vast voordat het contract definitief is. Een concept kun je stap voor stap aanvullen.

* **Vereist recht:** Contracten kunnen bewerken

Voor een concept is weinig nodig: de soort contract, een contractnummer en de professional. Cootje controleert bij een concept alleen het contractnummer. De rest vul je later aan.

## Stap 1: een contractnummer opvragen

* **Aanroep:** `GET /contracts/contractnumber/next`
* **Verplicht:** niets
* **Optioneel:** niets

```bash
curl "https://mijn.cootje.com/api/contracts/contractnumber/next" \
  -H "Authorization: Bearer JOUW_TOKEN"
```

### Wat je terugkrijgt

Het eerstvolgende vrije nummer, als tekst:

```
CONTRACT-043
```

Het nummer wordt niet gereserveerd. Je krijgt hetzelfde nummer terug tot er een contract mee is aangemaakt.

## Stap 2: het concept aanmaken

* **Aanroep:** `POST /contracts`

### Verplichte velden

| Veld               | Soort | Toelichting                                                                                                                                                                                                  |
| ------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `contractKind`     | getal | De soort contract. Voor een zzp-contract is dat `1`                                                                                                                                                          |
| `contractnumber`   | tekst | Het nummer uit stap 1. Moet passen bij de nummering van jullie omgeving en mag nog niet in gebruik zijn                                                                                                      |
| `professional._id` | tekst | Het `_id` van de zzp'er. Zie [Professional toevoegen](https://docs.cootje.com/cootje-api/zzp/professional-toevoegen.md). Weet je die nog niet, stuur dan een leeg `_id` mee: `"professional": { "_id": "" }` |

### Optionele velden

| Veld                                                                 | Soort | Toelichting                                                                                                                       |
| -------------------------------------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------- |
| `supplier._id`                                                       | tekst | Het `_id` van het bedrijf van de zzp'er. Zie [Bedrijf registreren](https://docs.cootje.com/cootje-api/zzp/bedrijf-registreren.md) |
| `hirer._id`                                                          | tekst | Het `_id` van de klant waar de professional gaat werken                                                                           |
| `authorizedSignatoriesSupplier`                                      | lijst | De tekenbevoegden van het bedrijf van de zzp'er, elk als `{ "_id": "..." }`. Meestal is dat de zzp'er zelf                        |
| `state`                                                              | getal | `1` voor een concept. Dit is de standaardwaarde                                                                                   |
| `contactHirer._id`                                                   | tekst | Het `_id` van de contactpersoon bij de klant                                                                                      |
| `authorizedSignatoriesHirer`                                         | lijst | De tekenbevoegden van de klant, elk als `{ "_id": "..." }`                                                                        |
| `timesheetApprovers`                                                 | lijst | De urenverantwoordelijken, elk als `{ "_id": "..." }`                                                                             |
| `assignment.role`                                                    | tekst | De functie                                                                                                                        |
| `assignment.description`                                             | tekst | De omschrijving van de werkzaamheden                                                                                              |
| `assignment.expectedOutcome`                                         | tekst | Het beoogde resultaat                                                                                                             |
| `assignment.location`                                                | tekst | De plaats waar het werk wordt gedaan                                                                                              |
| `assignment.hoursPerWeek`                                            | getal | Aantal uren per week                                                                                                              |
| `assignment.startDate`, `assignment.endDate`                         | getal | Start- en einddatum, in milliseconden sinds 1970. Cootje zet ze op het begin en het einde van de dag                              |
| `financial.rateCustomer.sum`                                         | getal | Het tarief dat de klant betaalt                                                                                                   |
| `financial.rateProfessional.sum`                                     | getal | Het tarief dat de zzp'er krijgt                                                                                                   |
| `financial.rateCustomer.period`, `financial.rateProfessional.period` | getal | De eenheid van het tarief: `7` per uur, `1` per dag, `4` per maand                                                                |

Bedrijven en personen geef je alleen op met hun `_id`. De overige gegevens haalt Cootje uit de registratie van dat bedrijf of die persoon. Velden die je weglaat, krijgen een standaardwaarde.

### Voorbeeld

Dit is vaak al genoeg om een concept aan te maken:

```bash
curl -X POST "https://mijn.cootje.com/api/contracts" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contractKind": 1,
    "contractnumber": "CONTRACT-043",
    "professional": {
      "_id": "5a1e9c3b-7f2d-4b6a-8e0c-9d4f1a2b3c4d"
    },
    "supplier": {
      "_id": "b1c2d3e4-5f6a-4b7c-8d9e-0a1b2c3d4e5f"
    },
    "hirer": {
      "_id": "0b7c2f6e-3d1a-4f5b-9a8e-1c2d3e4f5a6b"
    }
  }'
```

### Wat je terugkrijgt

Het aangemaakte contract, met het nieuwe `_id`. Alles wat je niet hebt meegestuurd, heeft een standaardwaarde:

```json
{
  "contractKind": 1,
  "_id": "f6a7b8c9-0d1e-4f2a-8b3c-4d5e6f7a8b9d",
  "contractnumber": "CONTRACT-043",
  "financial": {
    "type": 2,
    "budget": null,
    "redemtionAmount": 0,
    "paymentTermCustomer": 0,
    "endDateDeclarations": null,
    "rebatePercentage": 0,
    "fines": [],
    "compensations": [],
    "rateCustomer": {
      "name": "",
      "period": 0,
      "kind": 0,
      "sum": 0,
      "receiverId": ""
    },
    "contractFees": [],
    "additionalProvisions": "",
    "timesheetPeriod": 4,
    "allowedDeclarations": null,
    "maximumCoverage": 0,
    "maximumSum": 0,
    "rateProfessional": {
      "name": "",
      "period": 0,
      "kind": 0,
      "sum": 0,
      "receiverId": ""
    },
    "paymentTermSupplier": 0,
    "paymentDiscount": null
  },
  "state": 1,
  "effectiveState": 1,
  "signedDate": 0,
  "creationDate": 1799746200000,
  "isArchived": false,
  "hirer": {
    "_id": "0b7c2f6e-3d1a-4f5b-9a8e-1c2d3e4f5a6b"
  },
  "hirerDepartment": null,
  "supplier": {
    "_id": "b1c2d3e4-5f6a-4b7c-8d9e-0a1b2c3d4e5f"
  },
  "endCustomer": {
    "_id": ""
  },
  "professional": {
    "_id": "5a1e9c3b-7f2d-4b6a-8e0c-9d4f1a2b3c4d"
  },
  "authorizedSignatoriesSupplier": [],
  "authorizedSignatoriesHirer": [],
  "timesheetApprovers": [],
  "contractManager": {
    "_id": ""
  },
  "recruiter": {
    "_id": ""
  },
  "memo": "",
  "revision": {
    "date": 0
  },
  "invoiceDetails": {
    "customerInvoiceDetails": {
      "vatType": 1,
      "includeTimesheetSummary": null,
      "references": [],
      "email": ""
    },
    "supplierInvoiceDetails": {
      "invoiceNumberProcess": 1,
      "vatType": 1,
      "gBankAccount": null
    }
  },
  "assignment": {
    "hoursPerWeek": 0,
    "startDate": 1799712000000,
    "endDate": 1799798399999,
    "prematureEndDate": null,
    "noticePeriodInDays": 0,
    "role": "",
    "description": "",
    "expectedOutcome": "",
    "location": "",
    "remarks": "",
    "agreementDocumentId": "",
    "exclusions": "",
    "effectiveEndDate": 1799798399999
  },
  "documents": [],
  "grootboek": {
    "_id": "e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7a8c",
    "name": "",
    "inkoopGrootboekId": "",
    "verkoopGrootboekId": "",
    "contractType": 1
  },
  "enabledRates": null,
  "customRates": [],
  "contactHirer": {
    "_id": ""
  },
  "poNumber": "",
  "mode": 3,
  "rejectedReason": null,
  "disableApproval": false,
  "timesheetAttachmentRequired": false,
  "prolongedFrom": null,
  "onboardingInviteId": null,
  "onboardingInviteRecipient": null,
  "budgetUsagePercentage": null
}
```

* In dit voorbeeld staan bedrijven en personen alleen met hun `_id`. In het echte antwoord staan daar ook hun overige velden bij.
* `state` is `1` (concept), `2` (gecontroleerd), `3` (definitief), `4` (afgewezen) of `5` (voortijdig beëindigd).
* `creationDate`, `assignment.startDate` en `assignment.endDate` zijn tijdstippen in milliseconden sinds 1970.
* De start- en einddatum staan standaard op de dag van aanmaken. Is de einddatum voorbij, dan toont `effectiveState` de waarde `4`. Vul de datums daarom in zodra je ze weet.

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

```json
[
  {
    "propertyName": "Contractnumber",
    "errorMessage": "Contractnummer is verplicht"
  }
]
```

Elke fout bevat daarnaast enkele technische velden, zoals `attemptedValue` en `errorCode`.

## Het concept aanvullen

Een concept vul je aan met `PUT /contracts/{id}`. Die aanroep vervangt het hele contract: haal het contract op met `GET /contracts/{id}`, pas aan wat je wilt wijzigen en stuur het geheel terug. Het contract heeft daarbij de vorm die je hierboven ziet.

Bij een zzp-contract is `supplier` het bedrijf van de zzp'er en `professional` de zzp'er zelf.

## Beginnen met de standaardwaarden van je omgeving

Elke omgeving heeft per soort contract een sjabloon met eigen standaardwaarden, zoals betaaltermijnen en vergoedingen. Wil je die overnemen, haal dan eerst het sjabloon op met `GET /contracts/defaultvalues/1` (daarvoor volstaat het recht Contracten kunnen inzien), vul het aan met je eigen velden en stuur het geheel naar `POST /contracts`. Het sjabloon heeft de vorm die je onder "Wat je terugkrijgt" ziet. Dit voorbeeld gebruikt `curl` en `jq`; de velden uit stap 2 staan in het bestand `concept.json`:

```bash
BASIS="https://mijn.cootje.com/api"

# Het sjabloon van je omgeving voor deze soort contract
curl -s "$BASIS/contracts/defaultvalues/1" \
  -H "Authorization: Bearer $TOKEN" > sjabloon.json

# Het sjabloon aanvullen met je eigen velden, zonder het _id van het sjabloon
jq -s '.[0] * .[1] | del(._id)' sjabloon.json concept.json > contract.json

# Het concept aanmaken
curl -s -X POST "$BASIS/contracts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @contract.json
```

## Van concept naar definitief

Een concept maak je in twee stappen definitief. Eerst zet je `state` op `2` met `PUT /contracts/{id}`; Cootje controleert het contract dan volledig. Daarna maak je het definitief met `PUT /contracts/{id}/activate`. Dat lukt alleen als dit in orde is:

* Het bedrijf van de zzp'er heeft minstens één gewone bankrekening en een volledig adres.
* Het beoogde resultaat is ingevuld (`assignment.expectedOutcome`).
* De professional, de contactpersoon, de tekenbevoegden en de urenverantwoordelijken hebben een naam en een e-mailadres.
* Het adres van de klant is volledig.
* Er is minstens één urenverantwoordelijke, tenzij goedkeuring voor dit contract is uitgeschakeld (`disableApproval`).

## Antwoorden

| Code  | Betekenis                                                                                                         |
| ----- | ----------------------------------------------------------------------------------------------------------------- |
| `200` | Het contractnummer of het aangemaakte contract                                                                    |
| `400` | Het contractnummer ontbreekt, past niet bij de nummering of is al in gebruik. Het antwoord is de lijst met fouten |
| `401` | Geen geldig token, of het account mist het recht                                                                  |
