Bouw een koppeling voor een platformhouder of voor een reguliere ontvanger. Ontdek de beschikbare acties, hun gegevensmodellen en precies welke toestemming nodig is.
Stel de canonieke URL van je omgeving in en lees je sleutel uit een secret manager.
curl --fail-with-body "$DONT4GET_BASE_URL/api/v1/me" \ --header "Authorization: Bearer $DONT4GET_API_KEY" \ --header "Accept: application/json"
GET /api/v1/me toont de identiteit, rol en scopes die daadwerkelijk voor deze sleutel gelden.
De router, invoervalidatie en OpenAPI gebruiken dezelfde endpointdefinities. Stabiele operationIds en expliciete schema’s vormen de basis voor SDK’s, CLI en MCP.
Controleer info.version in OpenAPI JSON om API-wijzigingen te herkennen. Het contractnummer volgt startjaar, maanden sinds de eerste release en releasevolgnummer. Appversies en de gekozen presentatie-schemaVersion staan hiervan los.
Een beperkte sleutel geeft alleen de gekozen acties vrij. Een volledige sleutel bevat de vastgelegde scopes van je eigen reguliere rol. Iedere sleutel heeft een vervaldatum.
Platformhouders werken binnen hun eigen organisatie. Recipients zien uitsluitend hun eigen gegevens. God-user beheer, impersonatie en globale instellingen vallen buiten deze API.
Authorization: Bearer …. Bewaar het niet in broncode, URL’s, logs of browseropslag.GET /api/v1/me. Gebruik daarna de relevante platformhouder- of recipient-endpoints. Trek een oude sleutel in zodra een vervangende sleutel werkt.De rol, actorstatus, toewijzing en sleutelstatus worden server-side gecontroleerd. Een sleutel kan geen god-user worden, geen tenant kiezen en geen andere sleutel aanmaken. Nieuwe sleutels vereisen een echte ingelogde browsersessie. Een volledige sleutel heeft expliciete scopes; nieuwe toekomstige rechten worden niet automatisch toegevoegd.
Recipienttoegang ontstaat via een gecontroleerde koppeling van de externe provideridentiteit aan een actieve actor en recipient. Een telefoonnummer, e-mailadres, URL-parameter of meegestuurd recipient-ID bewijst geen eigenaarschap. Er is geen openbare zoek- of claimfunctie op contactgegevens.
Behoud de bestaande aanmelding. Voor de geverifieerde TestFlight-release blijft de loginserver https://test.dont4get.io, met POST /api/v1/recipient/auth/challenges en POST /api/v1/recipient/auth/sessions. Dont4get maakt en controleert de code; Bird SMS in EU1 verzorgt de verzending. Deze login-endpoints staan op de bestaande loginserver.
Een geslaagde login geeft rechtstreeks { accessToken, expiresAt, profile }. Het token is een opaque bearer-token van 43 base64url-tekens, geen JWT. De huidige release gebruikt één uur geldigheid en bewaart het in de mobiele client uitsluitend in geheugen.
Stuur het bestaande accessToken als Authorization: Bearer … naar de gegevens-API van dezelfde omgeving. TestFlight gebruikt daarvoor https://beta-platform-dont4get.vercel.app/api/v1. De API controleert de SHA-256-sessiehash, vervaltijd en het actieve sms-profiel, gevolgd door een expliciete interne koppeling en de actieve platformactor/ontvanger. Een telefoonnummer of meegestuurd recipient-ID maakt die koppeling niet. Beta-sessies geven geen toegang tot productie.
Controleer eerst GET /api/v1/me: data.authentication is recipient_session en data.recipientId is de gekoppelde platformontvanger. Gebruik dat ID uit de API; het native profile.id kan anders zijn. Deze sessie heeft uitsluitend ontvangersrechten, zonder API-sleutelbeheer. De gegevens-API gebruikt { data, requestId }, ook al blijft de bestaande loginresponse onverpakt.
Bij 401 INVALID_RECIPIENT_SESSION moet de app opnieuw aanmelden. 403 RECIPIENT_SESSION_NOT_LINKED vereist controle van de beheerde profielkoppeling; opnieuw aanmelden maakt die niet. Een 503 RECIPIENT_SESSION_CONFIGURATION_INVALID betekent een verkeerde databasebinding. Gebruik geen productie-fallback, API-sleutel of Vercel-bypasssecret in de mobiele app. De native build en deze API-release hebben elk een eigen publicatiestap.
| Rol | Beschikbare mogelijkheden | Grens |
|---|---|---|
| Platformhouder | Eigen profiel en interfacetaal, bedrijfsgegevens zoeken, onboarding, betaalinrichting en status, koppelingencatalogus en agenda-autorisatie, afspraken lezen en aanleveren, eigen afspraaktypen, beoordeling van ontvangersverzoeken. | Geen andere organisaties, tenant-lifecyclebeheer, globale afspraaktypen wijzigen, tarievenbeheer, factuurbeheer, incasso-acties of beheer-mailbox. |
| Recipient | Eigen profiel en voorkeuren, eigen afspraken over platformhouders heen, bevestigings-, annulerings- en herplanningsverzoeken, suggesties beoordelen en een verwijderverzoek indienen en volgen. | Geen andere ontvangers, tenantbeheer, contactgegevens claimen, providerafspraken automatisch aanpassen of gegevens zelfstandig definitief verwijderen. |
| Beide rollen | Actuele identiteit/scopes lezen, eigen API-sleutels inzien en intrekken; een nieuwe sleutel vanuit een geauthenticeerde browsersessie maken. | Een beperkte sleutel heeft geen sleutelbeheer. Geen enkele bearer-sleutel kan nieuwe sleutels uitgeven. |
De publieke API maakt deze businessacties bereikbaar voor derden. De bestaande schermen en mobiele prototypefuncties zijn niet allemaal op deze endpoints aangesloten. Pushbezorging, routeberekeningen, inboximport, automatische AI-extractie en synchronisatie van ontvangersverzoeken met externe bronsystemen worden niet door dit contract geactiveerd. Bekijk per endpoint wat een opgeslagen voorkeur of aanvraag werkelijk doet.
Bedrijfszoeken heeft een eigen opgeslagen voortgang; de huidige provider ondersteunt Nederlandse bedrijven. Een gewijzigde interfacetaal wordt per actor opgeslagen, maar herschrijft een reeds geopende browsersessie niet. De agenda-API biedt een geautoriseerde start-URL. Google of Microsoft en Stripe kunnen interactie met een mens vereisen; hun toestemming of betaalinrichting wordt niet door een API-sleutel overgeslagen.
Gebruik HTTPS, Content-Type: application/json voor JSON-bodies en de canonieke basis-URL van je omgeving. Alle velden en scopes staan bij het endpoint. Onbekende invoervelden worden afgewezen, zodat velden zoals role, status of een andere tenant niet ongemerkt kunnen worden weggeschreven.
// Succes
{ "data": { "...": "endpoint-specifieke gegevens" }, "requestId": "..." }
// Fout
{ "error": { "code": "SCOPE_REQUIRED", "message": "..." }, "requestId": "..." }Gebruik de foutcode voor je afhandeling en requestId of de responseheader X-Request-Id voor ondersteuning. Bewaar geen tokens of volledige persoonlijke request- en responsebodies in je logs. De bestaande intake-response blijft backward-compatible en volgt het schema dat specifiek bij dat endpoint staat.
| Status | Betekenis | Actie |
|---|---|---|
| 400 | Ongeldige invoer of JSON | Corrigeer de request aan de hand van het schema. |
| 401 / 403 | Authenticatie of toestemming ontbreekt | Controleer sleutel, rol, scopes en actieve toewijzing. Blijf niet automatisch proberen. |
| 404 | Resource niet beschikbaar voor deze identiteit | Controleer de ID’s binnen de toegestane tenant of ontvanger. |
| 409 | Conflicterende versie, status of hergebruikte aanvraag-ID | Lees de actuele resource en verwerk het conflict. |
| 429 / 503 | Te veel verzoeken of dienst tijdelijk niet beschikbaar | Gebruik begrensde back-off, respecteer Retry-After indien aanwezig en voorkom dubbele mutaties. |
Paginering. Lijstendpoints met paginering accepteren pageSize (standaard 25, maximaal 100) en een ondoorzichtig pageToken. Gebruik de teruggegeven data.nextPageToken met dezelfde query. Een waarde null betekent het einde. Pas het token niet aan.
Gelijktijdig wijzigen. Afspraaktypen en de beoordeling van ontvangersverzoeken gebruiken expectedVersion zoals gespecificeerd bij het endpoint. Een oude versie geeft een conflict. Ontvangersverzoeken gebruiken een vaste clientRequestId voor veilige identieke herhalingen. Herhaal andere POST-aanroepen niet blind na een netwerkfout; lees eerst de status.
Browser en server. Serverintegraties gebruiken bearer-authenticatie. Een mutatie met een browsersessie vereist dezelfde origin en X-Dont4get-CSRF: 1. Deze verkenner stuurt standaard geen sessiecookies. Schakel alleen voor bewuste sessieaanroepen de browsersessie-optie in. Er is geen onbeperkte cross-origin cookie-API.
Een 202 met pending_review betekent dat een aanvraag duurzaam is vastgelegd voor menselijke beoordeling. Lees het bijbehorende statusendpoint en toon deze status in je eigen interface. Een annulerings- of herplanningsverzoek verandert de afspraak in het externe bronsysteem niet automatisch.
Bij betaalinrichting retourneert de API een Stripe-URL en een opgeslagen status. Open de URL voor de gebruiker en poll het billing-endpoint. De Stripe-webhook bepaalt de uitkomst. Bij agenda-autorisatie opent de gebruiker de autorisatie-URL; lees daarna de koppelingenstatus. Toon een duidelijke herstelactie als gebruikersactie uitblijft of de dienst een fout meldt.
Suggesties vereisen menselijke beoordeling. Stuur confirmedByHuman: true alleen nadat die beoordeling daadwerkelijk is uitgevoerd. Een goedgekeurde suggestie is een vastgelegde beoordeling; de API maakt daarmee geen providerafspraak. Een verwijderverzoek vereist eveneens expliciete bevestiging en blijft een verzoek totdat een bevoegde medewerker de afhandeling heeft voltooid.
De gewone bedrijfsroutes blijven zelfstandig bruikbaar. Maak een lokale afspraak met createHolderAppointment en lees of wijzig de componentindeling met listHolderAppointmentLayouts en updateHolderAppointmentLayout. De stemcatalogus ontsluit dezelfde 33 beoordeelde platformhouderacties, inclusief profielen, onboarding, planning, afspraaktypen en koppelingen.
GET /api/v1/platform-holders/{id}/voice/capabilities. Dit geeft een compacte lijst met scope en modus read of proposal. Voeg ?operationId=… toe voor de exacte invoer- en uitvoerschema’s van één gekozen handeling. De native aanmeldbrug moet in de echte app zijn geverifieerd; een API-sleutel of ontvangerssessie vervangt deze sessie niet.POST …/voice/sessions met een vooraf bewaarde clientRequestId. Poll parallel GET …/voice/sessions/{clientRequestId}. Gebruik de private signed URL alleen in de appverbinding, nooit in toolresultaten of logs. De server vereist een goedgekeurde EU-agentversie en geeft configuratie- of providerfouten expliciet terug.platform_capabilities en platform_action. Laat de app een strikt geparseerde arguments-JSON-string, het operationId en eigen sessie-/aanvraag-ID’s naar POST …/voice/actions sturen. De server valideert de onderliggende DTO en bepaalt de tenant.GET …/voice/proposals/{proposalId} en toon de exacte bewaarde waarden. Alleen de afzonderlijke menselijke bevestigingsknop roept POST …/confirm aan; deze route is nooit een agenttool. Betaaltoestemming blijft een aparte keuze. Bij uitvoering pollt de app de status automatisch.Voorstellen verlopen na tien minuten. Een dubbele bevestiging voert niet opnieuw uit. Bij failed, stalled of timed_out met mayHaveApplied=true moet eerst de werkelijke bedrijfsstatus worden gecontroleerd. Een afspraakaanmaak is geen bewijs van geslaagde sms-bezorging; render ook delivery.status. Externe agenda’s worden niet automatisch teruggeschreven.
De repository bevat de volledige configuratie- en actiemapping in docs/platform-holder-voice-control.md en één kopieerbare bouwopdracht voor de bestaande iOS-app in docs/native-platform-holder-voice-task.md. TestFlight gebruikt de vaste platform-beta en vereist een afzonderlijk geverifieerde appbuild.
Gebruik @dont4get/sdk in je Node.js-applicatie, dont4get in je terminal of dont4get-mcp als lokale stdio-server voor je AI-client. De pakketten gebruiken de stabiele operationId-waarden en schema’s van dit contract, met dezelfde server-side autorisatie. Ze zijn vanuit de repository te bouwen en als lokale tarballs te installeren; openbare npm-publicatie wordt niet verondersteld.
De CLI vraagt bevestiging voor mutaties. MCP begint met alleen lezen, filtert tools op live scopes en biedt ook bij schrijfopt-in geen betaalcheckout, menselijke beoordelingsacties, sleutelbeheer of DELETE-acties. God-userbeheer en impersonatie zijn in alle drie uitgesloten. De installatiegids beschrijft onboarding, browsertoestemming en statuscontrole stap voor stap.
Filter op rol of categorie, bekijk de operationIds en schema’s en probeer een expliciete aanroep. De kleuren voor GET, POST, PATCH en DELETE volgen de vertrouwde Swagger-conventies.
API-referentie wordt geladen…