API-integratie: InControl API koppelen aan je eigen systeem

Wat is een API?

Een API (Application Programming Interface) is een set van regels waarmee softwareprogramma’s met elkaar kunnen communiceren. Denk aan een API als een ober in een restaurant: jij plaatst een bestelling, de ober brengt deze naar de keuken en komt terug met je eten. In dit geval is de API de ober, jouw systeem de klant en InControl de keuken.

Authenticatie en Autorisatie

Voordat je API-verzoeken kunt uitvoeren, moet je zorgen voor een correcte authenticatie. De InControl API maakt gebruik van tokens voor autorisatie. Dit token is als een digitale sleutel die ervoor zorgt dat alleen geautoriseerde gebruikers toegang krijgen.

Hoe verkrijg je een API-token?

Log in op het InControl-platform.
Ga naar de API-instellingen en genereer een nieuwe API-key.
1. Ga naar het onderste overzicht door naar "organisatie" --> "Service accounts" te navigeren.
2. Druk op de plus knop zoals links onder op de foto te zien

Je krijgt vervolgens een API token, sla deze op! Wanneer je op "Oké" drukt zal deze niet meer zichtbaar zijn.

Gebruik deze key in je aanvragen via de Authorization-header:
```
Authorization: Bearer <jouw_api_token>
```
Test of je token werkt door deze eenvoudige aanvraag uit te voeren:
```
GET /api/v1/testtoken
```
Een succesvolle response bevestigt dat je API-token geldig is.

Cases beheren

Met de Cases API kun je cases (dossiers) ophalen, aanmaken en bijwerken. Cases zijn handig voor het registreren en opvolgen van problemen, verzoeken of workflows binnen je systeem.

Lijst van cases ophalen:
```
GET /api/v1/case?page=1&perPage=10
```
Een specifieke case ophalen:
```
GET /api/v1/case/{id}
```

Een nieuwe case aanmaken:

POST /api/v1/case
{
  "name": "Nieuwe case",
  "status": "open",
  "priority": "high"
}

Taken (Tasks) beheren

Met de Tasks API kun je taken aanmaken en beheren. Dit is handig om workflows te automatiseren en taken aan specifieke gebruikers toe te wijzen.

Lijst van taken ophalen:
```
GET /api/v1/task
```
Een taak voltooien:
```
POST /api/v1/task/{id}/finish
```

Een taak toewijzen aan een gebruiker:

POST /api/v1/task/{id}/assign
{
  "user": "<user_id>"
}

Formulieren (Forms) integreren

De Forms API helpt bij het ophalen en beheren van formulieren en hun resultaten. Dit is nuttig voor het verzamelen en structureren van data.

Een lijst van formulieren ophalen:
```
GET /api/v1/form
```

Een formulier invullen en opslaan als concept (draft):

POST /api/v1/draft
{
  "form": "<form_id>",
  "user": "<user_id>",
  "values": {
    "vraag1": "antwoord"
  }
}

Een formulier definitief indienen:
```
POST /api/v1/form/{id}/submit
```

Organisaties beheren

De Organizations API geeft je toegang tot organisatiestructuren binnen InControl. Dit is belangrijk voor multi-organisatiebeheer.

Lijst van organisaties ophalen:
```
GET /api/v1/organization
```
Details van een organisatie ophalen:
```
GET /api/v1/organization/{id}
```

Een nieuwe organisatie aanmaken:

POST /api/v1/organization
{
  "name": "Nieuwe organisatie"
}

Concepten (Drafts) beheren

Drafts zijn tijdelijke gegevens die nog niet definitief zijn opgeslagen. Ze zijn handig voor conceptdocumenten of onvolledige invoer.

Lijst van drafts ophalen:
```
GET /api/v1/draft
```
Een draft verwijderen:
```
DELETE /api/v1/draft/{id}
```

Documenten beheren

Met de Documents API kun je documenten ophalen, beheren en downloaden. Dit is handig voor het opslaan van rapporten, contracten of andere administratieve bestanden.

Lijst van documenten ophalen:
```
GET /api/v1/document
```
Een specifiek document ophalen:
```
GET /api/v1/document/{id}
```
Een document verwijderen:
```
DELETE /api/v1/document/{id}
```

Een document uploaden:

POST /api/v1/document/{id}
{
  "file": "<bestand_data>"
}

Een document downloaden in PDF-formaat:

GET /api/v1/document/{id}/download?fileType=pdf

Bestanden (Files) beheren

De Files API helpt bij het beheren van documenten en bestanden, vooral als je bijlagen aan cases of formulieren wilt koppelen.

Een bestand uploaden naar een case:

POST /api/v1/file
{
  "case": "<case_id>",
  "file": "<bestand_data>"
}

Een bestand downloaden:
```
GET /api/v1/file/{id}/download
```

Veelvoorkomende problemen en oplossingen

Probleem	Mogelijke oorzaak	Oplossing
401 Unauthorized	Ongeldig of ontbrekend token	Controleer of je API-token correct is ingesteld.
400 Bad Request	Onjuiste parameterwaarden	Controleer of alle verplichte velden correct zijn ingevuld.
404 Not Found	Ongeldig ID of verkeerd endpoint	Controleer of het ID correct is en of het record bestaat.

Conclusie

Door gebruik te maken van de InControl API kun je efficiënte integraties bouwen binnen je eigen systeem. Of je nu cases, taken, formulieren, documenten of bestanden wilt beheren, de API biedt een breed scala aan mogelijkheden.

Door de juiste authenticatie en API-aanroepen te implementeren, zorg je ervoor dat je data altijd up-to-date en correct wordt verwerkt binnen je applicatie. Mocht je verdere vragen hebben over de implementatie, raadpleeg dan de InControl API-documentatie of neem contact op met support.