API-documentatie

Met de API leest en schrijft een ander systeem gegevens in uw Asset Management Systeem. Met webhooks krijgt dat systeem direct bericht als er iets gebeurt.

1. Maak een API-sleutel aan onder Instellingen > Koppelingen en API.
2. Stuur de sleutel mee met elke oproep.
3. Voeg eventueel een webhook toe om berichten te ontvangen.

curl https://dashboard.mjopbeheer.nl/api/v1/assets?limit=2 \
  -H "Authorization: Bearer ams_live_..."

Basisadres: https://dashboard.mjopbeheer.nl/api/v1. Veldnamen zijn Nederlands, zoals in het systeem; foutmeldingen zijn Engels.

Elke oproep heeft de kop Authorization met uw sleutel. Een sleutel hoort bij één organisatie en ziet alleen de gegevens van die organisatie.

Authorization: Bearer ams_live_...

• Een sleutel is alleen-lezen, of lezen en schrijven. Dat kiest u bij het aanmaken.
• U ziet de sleutel één keer. Wij bewaren alleen een afdruk (hash).
• Gebruik één sleutel per systeem, zodat u hem los kunt intrekken.

GET https://dashboard.mjopbeheer.nl/api/v1/<onderdeel>
GET https://dashboard.mjopbeheer.nl/api/v1/<onderdeel>/<id>

• limit (standaard 100, maximaal 500) en offset voor pagina’s; het antwoord bevat paging.next_offset.
• updated_since (datum in ISO 8601) geeft alleen wat sindsdien is gewijzigd; niet voor budgetten en kosten.
• Filters zijn exacte waarden, bijvoorbeeld ?locatie_id=…&status=open.

{
  "data": [ { "id": "…", "nummer": "A-0059", "naam": "…", "locatie_id": "…" } ],
  "paging": { "limit": 100, "offset": 0, "total": 79, "next_offset": null }
}

Schrijven kan met een sleutel met schrijfrecht. Elke wijziging komt in het auditlog, met de naam van de sleutel.

Melding of storing aanmaken

POST https://dashboard.mjopbeheer.nl/api/v1/meldingen

{
  "titel": "Lekkage plafond gang",
  "omschrijving": "Water bij de lift",
  "soort": "melding",            // of "storing"
  "urgentie": "normaal",          // laag | normaal | hoog | spoed
  "asset_nummer": "A-0059",       // of asset_id / asset_extern_id / locatie_id
  "gemeld_door": "Jan Jansen",
  "fotos": ["https://…"]
}

Verplicht: titel, en een asset of locatie_id. De verantwoordelijke uit de procesafspraken krijgt automatisch een taak om de melding te beoordelen. Bij een storing gaat het asset op storing.

Status van een melding bijwerken

PATCH https://dashboard.mjopbeheer.nl/api/v1/meldingen/<id>

{ "status": "in_behandeling", "bericht": "Monteur komt morgen" }
// status: in_behandeling | hersteld_gemeld   ook: oplossing

Werkorder bijwerken

PATCH https://dashboard.mjopbeheer.nl/api/v1/werkorders/<id>

{ "status": "geaccepteerd", "verwachte_datum": "2026-12-03" }
// status: geaccepteerd | in_uitvoering | gereed_gemeld   ook: gereed_tekst, extern_referentie

Een werkorder die nog op akkoord van de manager wacht, kan niet worden bijgewerkt (409). Sluiten en accepteren van de oplevering doet de opdrachtgever in het systeem.

Voeg onder Instellingen > Koppelingen en API een https-adres toe en kies de gebeurtenissen. Wij sturen een POST met JSON zodra er iets gebeurt.

POST https://uw-systeem.example/hook
X-AMS-Event: werkorder.goedgekeurd
X-AMS-Delivery: <id>
X-AMS-Signature: t=1794480000,v1=<hex>

{
  "id": "<id>",
  "type": "werkorder.goedgekeurd",
  "created": "2026-11-12T11:30:00Z",
  "data": { "werkorder": { "id": "…", "nummer": 12, "titel": "…", "status": "gepland" } }
}

Handtekening controleren

Bereken HMAC-SHA256 over "<t>.<body>" met het geheim van de webhook (whsec_…) en vergelijk met v1. Weiger berichten waarvan t ouder is dan vijf minuten.

import { createHmac, timingSafeEqual } from 'crypto';

function geldig(header, body, geheim) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((x) => x.split('=')));
  const verwacht = createHmac('sha256', geheim).update(t + '.' + body).digest('hex');
  return Math.abs(Date.now() / 1000 - Number(t)) < 300
    && timingSafeEqual(Buffer.from(v1), Buffer.from(verwacht));
}

Antwoord binnen vijf seconden met een 2xx-status. Anders proberen we het opnieuw na 1, 5, 30, 120 en 720 minuten. Gebruik X-AMS-Delivery om dubbele berichten te herkennen.

{ "error": { "code": "validation_error", "message": "Field \"titel\" is required." } }

Elke oproep staat 90 dagen in het log onder Instellingen > Koppelingen en API.

Zonder programmeren koppelen kan nu al met de bouwstenen voor webhooks en HTTP in deze platforms:

• Berichten ontvangen: maak in het platform een "Catch hook" of "Custom webhook" en plak dat adres bij Webhooks.
• Gegevens ophalen of een melding aanmaken: gebruik een HTTP-stap met uw sleutel in de kop Authorization.

Kant-en-klare apps voor Zapier en Make, en standaardkoppelingen met Exact Online, AFAS en TOPdesk, zijn in voorbereiding.