Question 1

Wat is de MeldingsMonitor API?

Accepted Answer

## Wat is de MeldingsMonitor API?

De MeldingsMonitor API is een RESTful interface waarmee je programmatisch toegang krijgt tot P2000-meldingen, capcodes en voertuigen. De API is ontworpen voor ontwikkelaars die MeldingsMonitor-data willen integreren in eigen applicaties, dashboards of systemen.

### Wat kun je met de API?

- **Meldingen ophalen** — Haal P2000-meldingen op, filter op datum, discipline, stad, capcode en meer
- **Capcodes doorzoeken** — Zoek en bekijk capcodes met hun gekoppelde discipline en locatie
- **Voertuigen opvragen** — Haal voertuigdata op, filter op type of zoek op roepnaam
- **Webhooks instellen** — Ontvang automatisch notificaties bij nieuwe meldingen of wijzigingen via webhooks

### Wie kan de API gebruiken?

De API is beschikbaar voor gebruikers met een **Developer** of **Developer Pro** abonnement. Elk plan heeft eigen limieten voor het aantal requests, historische data en webhook-endpoints.

### Hoe begin ik?

1. Upgrade naar een Developer-abonnement via de abonnementenpagina
2. Ga naar **Instellingen** → **API** om een API-token aan te maken
3. Gebruik het token om requests te doen naar `https://meldingsmonitor.test/api/v1/`
4. Bekijk de [API-documentatie](/api/docs) voor alle endpoints en voorbeelden

### API-versioning

De API gebruikt versienummering in de URL (`/api/v1/`). Dit garandeert dat bestaande integraties blijven werken, zelfs als we nieuwe versies uitbrengen.

Question 2

API-tokens aanmaken en beheren

Accepted Answer

## API-tokens aanmaken en beheren

API-tokens worden gebruikt om je te authenticeren bij de MeldingsMonitor API. Elk token geeft toegang tot de API namens jouw account.

### Token aanmaken

1. Ga naar **Instellingen** → **API** (of klik op **API** in de zijbalk)
2. Klik op **Token aanmaken**
3. Geef het token een herkenbare naam (bijv. "Mijn Dashboard" of "Home Assistant")
4. Het token wordt eenmalig getoond — **kopieer het direct en sla het veilig op**

> **Let op:** Het token wordt slechts één keer getoond. Als je het kwijtraakt, moet je een nieuw token aanmaken.

### Token gebruiken

Stuur je token mee als `Authorization` header bij elk API-request:

```
Authorization: Bearer jouw-api-token-hier
```

### Voorbeeld met cURL

```bash
curl -H "Authorization: Bearer jouw-api-token" \
     https://meldingsmonitor.test/api/v1/incidents
```

### Token intrekken

Als een token gecompromitteerd is of niet meer nodig is:

1. Ga naar **Instellingen** → **API**
2. Klik op **Intrekken** naast het betreffende token
3. Het token is direct ongeldig

### Limieten

- Je kunt maximaal **5 tokens** per account aanmaken
- Elk token heeft dezelfde rechten en limieten als je abonnement
- Tokens verlopen niet automatisch, maar kunnen handmatig worden ingetrokken

### Veiligheid

- Deel je tokens **nooit** openbaar (bijv. in GitHub repositories)
- Gebruik per integratie een apart token, zodat je ze individueel kunt intrekken
- Roteer tokens periodiek voor extra veiligheid

Question 3

API-webhooks instellen

Accepted Answer

## API-webhooks instellen

Met API-webhooks ontvang je automatisch een HTTP POST-request wanneer er nieuwe meldingen binnenkomen of wanneer voertuigen of capcodes worden gewijzigd.

### Beschikbare events

| Event | Beschrijving |
|-------|-------------|
| `incident.created` | Nieuwe P2000-melding ontvangen |
| `incident.updated` | Bestaande melding bijgewerkt |
| `vehicle.updated` | Voertuiggegevens gewijzigd |
| `capcode.updated` | Capcodegegevens gewijzigd |

### Webhook aanmaken via de website

1. Ga naar **Instellingen** → **API**
2. Scroll naar het **Webhooks** gedeelte
3. Klik op **Webhook toevoegen**
4. Vul de URL in waarnaar de notificaties moeten worden gestuurd
5. Selecteer de events waarvoor je notificaties wilt ontvangen
6. Klik op **Opslaan**
7. Noteer het **webhook-secret** dat wordt getoond — dit heb je nodig om de handtekening te verifiëren

### Webhook aanmaken via de API

Je kunt webhooks ook programmatisch beheren via de API:

```bash
curl -X POST https://meldingsmonitor.test/api/v1/webhooks \
  -H "Authorization: Bearer jouw-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://jouw-server.nl/webhook",
    "events": ["incident.created", "incident.updated"]
  }'
```

### Webhook payload

Bij elk event ontvang je een JSON-payload:

```json
{
  "event": "incident.created",
  "data": {
    "id": 12345,
    "occurred_at": "2026-02-13T10:30:00+00:00",
    "message": "P 1 BRT-01 Brandmelding industrie Hoofdstraat 1 Gemeente",
    "priority": "1",
    "city": "Amsterdam",
    "latitude": 52.3676,
    "longitude": 4.9041
  },
  "timestamp": "2026-02-13T10:30:05+00:00"
}
```

### Handtekening verifiëren

Elke webhook bevat een `X-Webhook-Signature` header met een HMAC-SHA256 handtekening. Verifieer deze met je webhook-secret:

```php
$signature = hash_hmac('sha256', $requestBody, $webhookSecret);
$isValid = hash_equals($signature, $receivedSignature);
```

### Foutafhandeling en retries

- Als je server een niet-2xx statuscode teruggeeft, wordt het verzoek opnieuw geprobeerd
- Retries gebeuren met backoff (10s, 60s, 300s)
- Na 10 opeenvolgende mislukte leveringen wordt de webhook automatisch gedeactiveerd
- Je kunt een gedeactiveerde webhook weer activeren via **Instellingen** → **API**

### E-mail bij automatische deactivatie

Wanneer een webhook-endpoint automatisch wordt gedeactiveerd na opeenvolgende mislukte leveringen, ontvang je standaard een e-mail op het adres van je account. Daarin staan het betreffende endpoint, het aantal mislukte pogingen en een link naar je API-instellingen.

Zo hoef je niet continu te controleren of je webhooks nog actief zijn — je krijgt een seintje zodra MeldingsMonitor stopt met leveren aan een endpoint.

**Voorkeur beheren:**

1. Ga naar **Instellingen** → **API**
2. Scroll naar het **Webhooks**-gedeelte
3. Vink **E-mail bij gedeactiveerde webhook** aan of uit

Deze e-mail wordt alleen verstuurd bij **automatische** deactivatie (na 10 mislukte pogingen). Als je een webhook zelf deactiveert via het dashboard, ontvang je geen e-mail.

### Limieten

Het aantal webhook-endpoints dat je kunt aanmaken hangt af van je abonnement:

| Plan | Max. webhook-endpoints |
|------|----------------------|
| Developer | 3 |
| Developer Pro | 10 |

Question 4

API rate limits en limieten

Accepted Answer

## API rate limits en limieten

Om de API snel en betrouwbaar te houden voor iedereen, hanteren we rate limits per abonnement.

### Limieten per plan

| Limiet | Developer | Developer Pro |
|--------|-----------|--------------|
| Requests per minuut | 30 | 60 |
| Requests per dag | 5.000 | 25.000 |
| Max. resultaten per pagina | 50 | 100 |
| Historische data | 30 dagen | 90 dagen |
| Webhook-endpoints | 3 | 10 |

### Rate limit headers

Bij elke API-response ontvang je headers die aangeven hoeveel requests je nog kunt doen:

```
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 28
X-RateLimit-Reset: 1707820800
```

### Wat gebeurt er bij overschrijding?

Als je het limiet bereikt, ontvang je een `429 Too Many Requests` response:

```json
{
  "message": "Too Many Attempts.",
  "retry_after": 42
}
```

Wacht het aangegeven aantal seconden (`retry_after`) voordat je een nieuw verzoek doet.

### Historische data beperking

Je kunt alleen meldingen ophalen binnen de historische periode van je plan. Als je een `date_from` parameter opgeeft die ouder is dan toegestaan, ontvang je een `422` fout met de vroegst toegestane datum.

### Paginering

De API gebruikt cursor-based paginering voor efficiënte navigatie door grote datasets:

```bash
# Eerste pagina
curl -H "Authorization: Bearer token" \
     "https://meldingsmonitor.test/api/v1/incidents?per_page=25"

# Volgende pagina (gebruik de cursor uit de response)
curl -H "Authorization: Bearer token" \
     "https://meldingsmonitor.test/api/v1/incidents?cursor=abc123&per_page=25"
```

### Tips voor efficiënt API-gebruik

- Gebruik filters om alleen relevante data op te halen
- Cache responses waar mogelijk
- Gebruik webhooks in plaats van polling voor real-time notificaties
- Houd je requests per minuut in de gaten via de rate limit headers

Question 5

API-documentatie en endpoints

Accepted Answer

## API-documentatie en endpoints

De volledige API-documentatie is beschikbaar op [/api/docs](/api/docs). Hier vind je een overzicht van de belangrijkste endpoints.

### Base URL

```
https://meldingsmonitor.test/api/v1/
```

### Authenticatie

Alle requests vereisen een Bearer token in de `Authorization` header:

```
Authorization: Bearer jouw-api-token
```

### Beschikbare endpoints

#### Meldingen (Incidents)

| Methode | Endpoint | Beschrijving |
|---------|----------|-------------|
| GET | `/incidents` | Lijst van meldingen (gepagineerd) |
| GET | `/incidents/{id}` | Details van een specifieke melding |

**Filters voor `/incidents`:**
- `priority` — Filter op prioriteit (1, 2, 3)
- `city` — Filter op stad
- `discipline_id` — Filter op discipline
- `capcode_id` — Filter op capcode
- `date_from` / `date_to` — Filter op datum
- `search` — Zoek in meldingtekst

#### Capcodes

| Methode | Endpoint | Beschrijving |
|---------|----------|-------------|
| GET | `/capcodes` | Lijst van capcodes (gepagineerd) |
| GET | `/capcodes/{id}` | Details van een specifieke capcode |

**Filters voor `/capcodes`:**
- `discipline_id` — Filter op discipline
- `search` — Zoek op capcode of beschrijving

#### Voertuigen (Vehicles)

| Methode | Endpoint | Beschrijving |
|---------|----------|-------------|
| GET | `/vehicles` | Lijst van voertuigen (gepagineerd) |
| GET | `/vehicles/{id}` | Details van een specifiek voertuig |

**Filters voor `/vehicles`:**
- `type` — Filter op voertuigtype
- `search` — Zoek op roepnaam of beschrijving

#### Webhooks

| Methode | Endpoint | Beschrijving |
|---------|----------|-------------|
| GET | `/webhooks` | Lijst van je webhook-endpoints |
| POST | `/webhooks` | Nieuw webhook-endpoint aanmaken |
| PATCH | `/webhooks/{id}` | Webhook-endpoint bijwerken |
| DELETE | `/webhooks/{id}` | Webhook-endpoint verwijderen |

### Voorbeeld: Laatste meldingen ophalen

```bash
curl -H "Authorization: Bearer jouw-token" \
     "https://meldingsmonitor.test/api/v1/incidents?per_page=10"
```

### Voorbeeld response

```json
{
  "data": [
    {
      "id": 12345,
      "occurred_at": "2026-02-13T10:30:00+00:00",
      "message": "P 1 BRT-01 Brandmelding industrie",
      "priority": "1",
      "city": "Amsterdam",
      "latitude": 52.3676,
      "longitude": 4.9041,
      "disciplines": [{"id": 1, "name": "Brandweer"}],
      "capcodes": [{"id": 100, "capcode": "0120901", "description": "Kazerne Centrum"}],
      "vehicles": [{"id": 50, "call_sign": "AB 13-1", "type": "TS"}]
    }
  ],
  "meta": {
    "per_page": 10,
    "next_cursor": "abc123",
    "prev_cursor": null
  }
}
```

### Volledige documentatie

Bekijk de volledige API-documentatie met alle details, voorbeelden en foutcodes op [/api/docs](/api/docs).

Onderwerpen

API & Developer

Wat is de MeldingsMonitor API?

API-tokens aanmaken en beheren

API-webhooks instellen

API rate limits en limieten

API-documentatie en endpoints

Staat je antwoord er niet bij?

Cookies