REST API v1

Wat is een service token?

Een service token is een Sanctum personal access token dat hoort bij een applicatie (geen mens). Externe systemen zoals KM Desk gebruiken zo'n token om, namens bekende eindgebruikers, tickets aan te maken in het Korporaal Media platform, zonder dat die eindgebruikers handmatig hoeven in te loggen.

Tokens hebben abilities (scopes). Een KM Desk token heeft bijvoorbeeld tickets:create-on-behalf , daarmee mag het ticket-endpoint aangeroepen worden, maar bijvoorbeeld geen orders aanmaken of klanten verwijderen.

Tokens worden via een artisan command op de server aangemaakt en moeten direct na aanmaak bewaard worden, ze zijn daarna niet meer op te vragen. Wel kunnen ze worden ingetrokken.

KM Desk integratie, stap voor stap

1. Token aanvragen. Vraag de beheerder om een token via:

   php artisan api:issue-token --name="KM Desk"

   Bewaar de output (formaat 1|abc...) als KM_PLATFORM_TOKEN in de KM Desk config.
2. Ticket aanmaken namens een gebruiker. Roep POST /api/v1/tickets/on-behalf aan met het emailadres van de KM Desk gebruiker. Het platform zoekt die op in zijn eigen userlijst (matching op email).
3. Foutafhandeling. Krijgt KM Desk een 404 user_not_found? Dan bestaat de gebruiker niet in het portaal (of heeft hij geen email). Toon dan in KM Desk de melding: "Vraag de hoofdgebruiker van uw organisatie om dit ticket aan te maken." Eindgebruikers zonder email kunnen geen tickets aanmaken, die loopt via hun primaire contactpersoon.
4. Status terug naar KM Desk. Registreer een webhook (via POST /api/v1/webhooks) voor de events ticket.replied, ticket.status_changed, ticket.resolved en ticket.closed. KM Desk kan dan in real-time tonen wat de status van het ticket is.

Voorbeeld request

curl -X POST https://korporaal.media/api/v1/tickets/on-behalf \
  -H "Authorization: Bearer $KM_PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "subject": "Printer doet het niet",
    "description": "De HP LaserJet op de eerste verdieping start niet meer op.",
    "priority": "high",
    "user_email": "jan@bedrijf.nl",
    "user_name": "Jan Jansen",
    "external_reference": "kmdesk-ticket-4821"
  }'

Voorbeeld response (201)

{
  "data": {
    "id": 1234,
    "subject": "Printer doet het niet",
    "status": "open",
    "status_label": "Open",
    "priority": "high",
    "priority_label": "Hoog",
    "source": "kmdesk",
    "customer": { "id": 17, "name": "Bedrijf B.V." },
    "assignee": { "id": 1, "name": "Sanne Jansen" },
    "created_at": "2026-04-08T14:23:11+02:00"
  }
}

Beschikbare events

Payload-formaat

Elke webhook is een POST naar de geregistreerde URL met JSON body en de headers X-Webhook-Event en X-Webhook-Signature (HMAC-SHA256 van de body met het webhook-secret).

{
  "event": "ticket.replied",
  "timestamp": "2026-04-08T14:23:11+02:00",
  "data": {
    "ticket": {
      "id": 1234,
      "subject": "Printer doet het niet",
      "status": "in_progress",
      "priority": "high",
      "source": "kmdesk",
      "requester_email": "jan@bedrijf.nl",
      "requester_name": "Jan Jansen",
      "customer_id": 17,
      "customer_name": "Bedrijf B.V.",
      "assignee_name": "Sanne Jansen",
      "url": "https://korporaal.media/admin/tickets/1234"
    },
    "reply": {
      "id": 9876,
      "message": "Ik heb het ticket opgepakt en ga ermee aan de slag.",
      "is_from_customer": false,
      "is_internal": false,
      "sender_name": "Sanne Jansen",
      "created_at": "2026-04-08T14:23:11+02:00"
    }
  }
}