Van API-contract
naar werkende koppeling.

Bouwen en lokaal installeren

Je hebt toegang tot de bronrepository en Node.js 22.18 of nieuwer nodig. De pakketten zijn vanuit de repository te bouwen en als lokale npm-tarballs te installeren. Deze pagina veronderstelt geen publicatie in een openbare npm-registry.

npm ci
npm run build:developer-tools
npm run test:developer-tools
npm run pack:developer-tools

De tarballs verschijnen in output/developer-tools. Installeer de drie bij elkaar horende versies samen, zodat CLI en MCP dezelfde SDK gebruiken. Voor versie 0.1.0, vanuit de repository:

npm install --global ./output/developer-tools/dont4get-sdk-0.1.0.tgz ./output/developer-tools/dont4get-cli-0.1.0.tgz ./output/developer-tools/dont4get-mcp-server-0.1.0.tgz
dont4get help
dont4get version

De voorbeelden hieronder gebruiken de bronbuild node packages/dont4get-cli/dist/cli.js. Na globale installatie kun je dit vervangen door dont4get. Installeer de SDK voor een eigen applicatie ook als lokale projectdependency met npm install /absoluut/pad/naar/dont4get-sdk-0.1.0.tgz; een globale installatie maakt de SDK niet automatisch importeerbaar in je project.

Een eigen identiteit en een beperkte sleutel

1. Log in bij Dont4get. Een nieuwe platformhouder begint met Microsoft-aanmelding; daarmee ontstaat de eigen conceptorganisatie. Een recipient gebruikt een bestaande, gecontroleerde koppeling aan een actief recipient-ID.
2. Open API-sleutels rechtstreeks. Dit werkt ook voor een conceptorganisatie voordat onboarding is afgerond. Alleen een echte browsersessie van de accounthouder mag een sleutel uitgeven.
3. Maak een beperkte sleutel met een herkenbare naam, vervaldatum en de benodigde scopes. Bewaar het eenmalig getoonde geheim in je secret manager.
4. Laat je procesomgeving DONT4GET_API_KEY injecteren en stel DONT4GET_BASE_URL in op de vertrouwde, canonieke HTTPS-origin van je omgeving. Controleer de live identiteit voordat je verdergaat.

node packages/dont4get-cli/dist/cli.js auth
node packages/dont4get-cli/dist/cli.js identity

auth geeft instructies; het logt je niet automatisch in. De tools lezen geen browsercookies, slaan geen credentials op en laden geen .env-bestand automatisch. Zet de sleutel niet in argumenten, voorbeeldbestanden of gesprekken met een AI-client.

Een eerste aanroep vanuit Node.js

De SDK gebruikt de operationId uit Swagger. Elke aanroep ontvangt een object met waar nodig path, query en body. De eigen platformhouder-ID wordt uit de live identiteit afgeleid.

import { createClientFromEnv, Dont4getError } from "@dont4get/sdk";

const client = createClientFromEnv();

try {
  const identity = await client.identity();
  const operationId = identity.role === "platform_holder_user"
    ? "getHolderProfile"
    : "getRecipientProfile";
  const result = await client.call(operationId);
  // Verwerk result.data in je applicatie; log geen profielgegevens.
  console.info({ operationId, requestId: result.requestId });
} catch (error) {
  if (!(error instanceof Dont4getError)) throw error;
  console.error({ code: error.code, status: error.status, requestId: error.requestId });
  process.exitCode = 1;
}

Een resultaat bevat data, status en, indien beschikbaar, requestId. Ook de bestaande intake-response wordt door de SDK in deze vorm teruggegeven. Ongeldige invoer wordt lokaal geweigerd; de API valideert daarna zelfstandig. Een afwijkende response geeft INVALID_RESPONSE, zodat een gewijzigde contractversie niet ongemerkt wordt verwerkt.

Gebruik de SDK in een vertrouwde serveromgeving. Een API-sleutel hoort niet in een publieke browserbundle. Er zijn geen automatische retries van mutaties.

Ontdek het contract en lever JSON aan

node packages/dont4get-cli/dist/cli.js operations list
node packages/dont4get-cli/dist/cli.js operations describe updateHolderProfile
node packages/dont4get-cli/dist/cli.js call updateHolderProfile --input ./operation-input.json --confirm

Voor de generieke call bevat operation-input.json de operation-invoer inclusief body:

{
  "body": {
    "displayName": "Voorbeeld"
  }
}

Gebruik --input - voor JSON op stdin. Bestanden zijn UTF-8 en maximaal 64 KiB; query- en pathwaarden zijn strings. Ieder non-GET-commando vereist --confirm of --yes, ook bedrijfszoeken via POST. Deze vlag voegt nooit betaaltoestemming of menselijke beoordeling aan de invoer toe.

Succes levert één JSON-document op stdout; voortgang en veilige fouten verschijnen als JSON-regels op stderr. De exitcode is 0 bij succes en 1 bij fouten. De gevraagde profiel- en afspraakgegevens kunnen persoonsgegevens bevatten: stuur stdout niet ongericht naar gedeelde logs. Bescherm ook tijdelijke Stripe- en OAuth-URL’s.

Afspraakpresentatie voor ontvangers

Gebruik een ontvangerssleutel met recipient:appointments:read. De algemene ontwikkelaars-URL en toolstandaard zijn https://platform.dont4get.io. DONT4GET_BASE_URL bevat alleen de origin, zonder /api/v1; de tools voegen het API-pad toe.

Gebruik alleen voor expliciete betatests of TestFlight-integratietests DONT4GET_BASE_URL=https://beta-platform-dont4get.vercel.app, met de bijbehorende beta-identiteit en credentials. TestFlight blijft beta-gebonden. Behoud deployment protection en verwerk onbereikbaarheid als een fout.

De gekozen omgeving moet bronrelease a4c9226 of een corresponderende nieuwere release bevatten. Controleer in het live OpenAPI-contract of het presentatie-endpoint en schemaVersion="2" beschikbaar zijn. Een lokale toolbuild maakt een endpoint niet beschikbaar op de server.

Haal eigen afspraken op met listRecipientAppointments, volg nextPageToken en gebruik de ontvangen platformHolderId en afspraak-id voor de presentatie. De server bepaalt het afspraaktype en levert de opgeslagen ontvangerscomponenten van de bijbehorende platformhouder in de ingestelde volgorde. De lijst- en detailoperaties leveren daarnaast hun vaste basisvelden; ontvangersvinkjes sturen de presentatie.

Maak recipient-presentation.json met de werkelijke IDs uit de lijst; onderstaande IDs zijn voorbeelden:

{
  "path": {
    "platformHolderId": "holder_from_list",
    "appointmentId": "appointment_from_list"
  },
  "query": { "schemaVersion": "2" }
}

node packages/dont4get-cli/dist/cli.js operations describe getRecipientAppointmentPresentation
node packages/dont4get-cli/dist/cli.js call getRecipientAppointmentPresentation --input ./recipient-presentation.json

Via MCP gebruik je de tool getRecipientAppointmentPresentation met hetzelfde JSON-object als arguments. Deze leesactie vereist geen schrijfopt-in; de tool is alleen beschikbaar voor de juiste ontvangersrol en scope. Via de Node.js-SDK gebruik je client.call("getRecipientAppointmentPresentation", input).

De querywaarde "2" vraagt expliciet schema-versie 2 aan, inclusief geselecteerde location.map-componenten. Zonder query, of met "1", behoudt de API het bestaande versie-1-contract zonder kaart. Verwerk data.components op basis van fieldKey, label, dataType, kind, icon en tone. Bij availability="unavailable" is value=null; maak geen voorbeeldinhoud of actie aan.

Een beschikbare kaart bevat destination en currentLocationSource="device". De actuele locatie blijft op het apparaat en vereist OS-toestemming. Vrije bestemmingstekst is geen geverifieerd adres of route. De echte app moet de kaartweergave en veilige bestemmingverwerking nog implementeren; native ondersteuning van de Node.js-SDK is niet aangetoond.

Bouw en installeer SDK, CLI en MCP samen opnieuw vanuit commit a4c9226 of een nieuwere gecontroleerde release. Een webdeployment werkt bestaande lokale toolinstallaties niet bij en publiceert geen npm-pakketten. Raadpleeg het actuele OpenAPI-contract voor alle veldtypen en grenzen.

Van conceptorganisatie naar actieve platformhouder

Na aanmelding en sleuteluitgifte kun je de eigen organisatie via de CLI invullen. Maak organization.json met het profiel dat de verantwoordelijke persoon heeft gecontroleerd. Het onboardingcommando verwacht de profielbody rechtstreeks, zonder de generieke body-wrapper:

{
  "legalName": "Voorbeeld B.V.",
  "displayName": "Voorbeeld",
  "websiteUrl": "https://example.com",
  "billingEmail": "finance@example.com",
  "communicationInboxEmail": "team@example.com",
  "branch": "Zakelijke dienstverlening",
  "registrationCountryCode": "NL",
  "defaultLocale": "nl-NL",
  "defaultTimezone": "Europe/Amsterdam"
}

node packages/dont4get-cli/dist/cli.js onboard --profile ./organization.json --confirm
node packages/dont4get-cli/dist/cli.js onboard check

De eerste zes velden zijn nodig voor afronding. Geldige branches zijn Horeca, Zakelijke dienstverlening, Ziekenhuizen en Zorg. Een PATCH bewaart overige profielvelden; geef geen rol, tenant-ID of activatiestatus mee. De controle toont ontbrekende velden en betaalstatus; de server beslist uiteindelijk of activatie is toegestaan.

Betaaltoestemming en Stripe

Een bevoegde persoon leest en accepteert eerst de toepasselijke voorwaarden voor terugkerende betalingen. Leg alleen na die toestemming in billing-consent.json vast:

{ "consentAccepted": true }

node packages/dont4get-cli/dist/cli.js onboard billing --input ./billing-consent.json --confirm
node packages/dont4get-cli/dist/cli.js onboard status --wait

Open de geretourneerde Stripe-URL in de browser en rond daar de betaalinrichting af. De keuze voor kaart of SEPA vindt plaats in Stripe; de request bevat geen paymentMethodType. De CLI vult geen betaalgegevens in en opent de browser niet automatisch. Vooraf ingerichte enterprise- en connected-contracten volgen hun bestaande inrichting en kunnen niet met dit commando worden omgezet.

De statusaanroep volgt de opgeslagen Stripe-webhookuitkomst, standaard maximaal 120 seconden met een interval van 5 seconden. Gebruik bijvoorbeeld --timeout-seconds 300 --interval-seconds 5 voor langer wachten; het maximum is 900 seconden. Bij WAIT_TIMED_OUT stopt alleen het wachten. Lees de status opnieuw om observatie te hervatten; start niet blind een nieuwe checkout.

Expliciet afronden

node packages/dont4get-cli/dist/cli.js onboard --complete --confirm

Dit activeert uitsluitend de bestaande eigen conceptorganisatie zodra profiel en betaalinrichting voldoen. Een al actieve organisatie wordt als afgerond getoond zonder de activatie opnieuw te versturen. Een opgeslagen profiel blijft opgeslagen als een volgende stap faalt.

Agenda’s koppelen is optioneel: authorizeHolderIntegration geeft een Google- of Microsoft-autorisatie-URL terug; de gebruiker geeft toestemming in de browser. Controleer daarna listHolderIntegrations. Stripe- en OAuth-terugkeeradressen komen uit de canonieke Dont4get-configuratie; je kunt geen willekeurige callback-URL meegeven.

Sluit je AI-client lokaal aan via MCP

De MCP-server draait als lokaal proces via stdio. Je MCP-client start dit proces; er is geen afzonderlijke publieke MCP-HTTP-server. De toolnamen zijn de API-operationIds. De server filtert ze op de actuele rol en scopes van de sleutel en controleert die opnieuw bij elke toolaanroep.

Onderstaand is een configuratievoorbeeld voor clients die mcpServers gebruiken. Vervang het pad door het absolute pad naar jouw build en gebruik de canonieke origin van jouw omgeving:

{
  "mcpServers": {
    "dont4get": {
      "command": "node",
      "args": ["C:/path/to/dont4get-platform/packages/dont4get-mcp-server/dist/bin.js"],
      "env": {
        "DONT4GET_BASE_URL": "https://platform.dont4get.io"
      }
    }
  }
}

Injecteer DONT4GET_API_KEY vanuit de omgeving van het ouderproces of de secretvoorziening van je MCP-client. De client moet de sleutel doorgeven aan het serverproces. Het voorbeeld bewaart daarom geen sleutel in JSON. Plaats de sleutel ook niet in prompts of toolargumenten.

Standaard zijn alleen toegestane GET-tools beschikbaar. Een beheerder van het lokale proces kan bewust DONT4GET_MCP_ALLOW_WRITES="1" instellen om de goedgekeurde mutaties beschikbaar te maken. Die instelling geeft geen extra API-scopes. Ook bedrijfszoeken via POST vereist deze opt-in.

Laat de client eerst getApiIdentity aanroepen en de resource dont4get://guides/onboarding lezen. Die gids legt per rol de beschikbare stappen en menselijke overdrachten uit. Een ontbrekende tool kan wijzen op de verkeerde rol, een ontbrekende scope of uitgeschakelde schrijfacties. Nieuwe API-operaties worden pas na expliciete beoordeling als MCP-tool toegelaten.

Verleen alleen gegevensinzage die past bij de gekozen AI-client en het model. MCP-resultaten bevatten de opgevraagde gegevens; een aangesloten modelprovider kan die ontvangen. Kies je provider en gegevensverwerking bewust voordat je echte profiel- of afspraakgegevens beschikbaar maakt.

Voortgang, fouten en versiebeheer

De opgeslagen API-status is de bron voor voortgang. Bedrijfszoeken kent fases en statuscontrole via getHolderCompanyProgress; MCP kan bij een meegestuurd progress-token fasewijzigingen doorgeven. Vergelijk het eigen requestId met de voortgang. Een nieuwe bewuste lookup krijgt een nieuwe UUID. Een ontvangersverzoek met pending_review wacht op menselijke beoordeling en is geen lopende provideractie.

Een netwerkfout of timeout bewijst niet dat een mutatie is teruggedraaid. Lees eerst de resource of voortgang. Gebruik uitsluitend de per operatie beschreven clientRequestId of expectedVersion voor herhaling of gelijktijdige wijzigingen; er is geen algemene idempotencygarantie voor alle POST-aanroepen.

Bewaar alleen veilige foutcodes, status en correlatie-ID’s voor ondersteuning. Roteer sleutels via de accounthouder en trek oude sleutels in nadat de vervanging werkt. Werk SDK, CLI en MCP samen bij en voer de tests opnieuw uit na een contractwijziging.