Een integratiebriefing invullen met een rapportaanvraag
Leg scope, voorbeeldgegevens, antwoorden en acceptatiegevallen vast voor een koppeling tussen een projectportaal en een documentdienst.
Beschrijf een integratie aan de hand van één volledige stroom voordat u offertes vergelijkt. “Het portaal heeft een API-koppeling nodig” laat open welke gegevens worden overgedragen, wanneer het werk klaar is en wie een fout afhandelt. Een uitgewerkte briefing maakt deze beslissingen bespreekbaar.
Kies één stroom voor de eerste oplevering
In dit fictieve project vraagt een portaal een maandelijks PDF-rapport aan bij een documentdienst. Alle namen, velden en antwoorden zijn eigen voorbeelden, geen API van een leverancier.
Briefingveld | Voorbeeldafspraak |
|---|---|
Doel | Een bevoegde projectmedewerker kan het aangevraagde maandrapport in het portaal downloaden. |
Bron | Het projectportaal levert project, bevestigde rapportmaand en goedgekeurde sjabloonreferentie. Het portaalteam is verantwoordelijk voor die selectie. |
Doelsysteem | De documentdienst maakt de PDF. Het platformteam is verantwoordelijk voor verwerking en foutstatussen. |
Aanleiding | Een uitdrukkelijke aanvraag in het portaal; geen nieuwe taak bij iedere paginaweergave. |
Oplevering | Een taak aanmaken, de status opvragen en het voltooide bestand ophalen. |
Uitgesloten | E-mail versturen en alle historische rapporten overzetten. |
Zo worden ook extra wensen zichtbaar: een latere e-mailfunctie zou een aparte stap zijn met eigen foutafhandeling. Die verdwijnt niet in het woord “koppeling”.
Geef invoer met waarden en betekenis
Voor POST /report-jobs wordt deze voorbeeldinhoud afgesproken:
{"requestId":"R-52","projectId":"P-18","templateId":"monthly-v2","period":"2026-10"}Het aanvraag-ID duidt dit aanmaakverzoek aan. Project en sjabloon zijn stabiele referenties; de periode is hier een kalendermaand in jaar–maandnotatie. Weergavenamen of een vrij omschreven periode vervangen deze waarden niet. Het portaal moet met de documentdienst afstemmen welke sjablonen zijn goedgekeurd.
Toegang tot taak, status en bestand blijft beperkt tot het bevoegde project. Alleen een link kennen geeft geen downloadrecht. Rollen en toegangsmethode horen in de briefing; echte tokens en wachtwoorden blijven buiten het document.
Beschrijf acceptatie en resultaat apart
Na duurzame registratie antwoordt de voorbeelddienst met HTTP 202 en Location: /report-jobs/J-52:
{"jobId":"J-52","status":"queued"}MDN beschrijft 202 als acceptatie van verwerking die nog niet voltooid is. Ons eigen contract kent daarom de statussen queued (wachtend), running (in verwerking), succeeded (geslaagd) en failed (mislukt). De taak slaagt pas als het bestand is gemaakt en op het moment van afronding met de juiste bevoegdheid kan worden opgehaald. Microsoft beschrijft een aparte statusopvraag voor asynchroon werk; de specifieke statusnamen hier zijn onze keuze.
Hetzelfde aanvraag-ID met identieke inhoud binnen dezelfde toegestane scope verwijst naar dezelfde taak. Voor afwijkende inhoud wordt in het voorbeeld HTTP 409 afgesproken. Deze herhaalregel moet worden geïmplementeerd en gecontroleerd; de veldnaam alleen maakt een bewerking niet idempotent.
Vul vóór de bouw vier acceptatiegevallen in
Geval | Verwacht resultaat |
|---|---|
Geldige aanvraag | Acceptatie, zichtbaar verloop en uiteindelijk een opvraagbaar rapport voor het afgesproken project en de maand. |
Sjabloonreferentie ontbreekt | HTTP |
Het antwoord op een aangenomen aanvraag gaat verloren | Herhaling met dezelfde inhoud en hetzelfde aanvraag-ID vindt de bestaande taak; geen tweede rapportgeneratie. |
Het sjabloon wordt na acceptatie verwijderd | Verwerking eindigt met |
In het laatste geval onderzoekt het platformteam het sjabloon. Een gecorrigeerde nieuwe aanvraag krijgt een nieuw aanvraag-ID; de mislukte taak blijft traceerbaar. Is alleen de statusopvraag gestoord, dan toont het portaal dat de actuele status onbekend is en beweert het geen succes of mislukking.
Los open beheervragen op vóór een toezegging
Vul verwacht taakvolume, gebruikelijke bestandsgrootte, aanvaardbare wachttijd, opvraaginterval en bewaartermijn van bestanden en statusgegevens in op basis van het werkelijke gebruik. Deze waarden staan in het voorbeeld nog open en moeten vóór een betrouwbare toezegging worden verduidelijkt. Een geschatte duur geldt niet als gemeten eigenschap.
Een OpenAPI-beschrijving kan bewerkingen, invoer en verwachte antwoorden nauwkeurig vastleggen. Ook de functionele resultaatdefinitie en teamverantwoordelijkheden moeten vaststaan. Met de uitgewerkte gevallen kunnen portaal- en platformteam vervolgens dezelfde oplevering beoordelen.
Bronnen
Verder lezen
Alle artikelen
Koppelingen & integratie met ASES
ERP, CRM en webshop netjes gekoppeld