# Agenda en mailbox koppelen vanuit je eigen software Deze handleiding beschrijft de beschikbare API binnen de vermelde releasegrenzen. Actuele sleutel-, gebruikers-, pakket- en objectrechten blijven vereist. Niet alle websitefuncties zijn via de API beschikbaar. De fictieve oefenomgeving maakt geen echte providerverbinding. ## Voorbereiding Gebruik een productie-API-sleutel van de juiste gebruiker en diens pakket met de betreffende koppeling. De beheerder kan het rechtenplafond bepalen. Je hebt `verbindingen:beheren` nodig om verbindingen te bekijken, te starten en te stoppen; `agenda:lezen` voor afspraken. Een aanvraag voor mailboxverzending vraagt bovendien `berichten:verzenden`. Rechten worden niet automatisch toegevoegd aan bestaande sleutels. Bewaar de sleutel op je server. Basisadres: `https://api.rapportly.io/api/rapportly/v1`. Gebruik op alle API-verzoeken `Authorization: Bearer `. De providerlogin zelf gebeurt door de gebruiker in de browser. Het API-antwoord bevat geen providerwachtwoord of toegangstoken. | Soort | Provider | scope_versie | |---|---|---| | agenda | google of m365 | 1 | | mailbox | gmail of m365 | 1 voor concepten, 2 voor gericht verzenden | Gmail gebruikt technisch dezelfde compose-toestemming voor beide versies. In Rapportly blijft verzenden een afzonderlijk recht en een afzonderlijke bewuste actie. Een koppeling geeft nooit vanzelf een verzendopdracht. ## 1. Lees de huidige verbinding `GET /verbindingen/agenda/google` Bewaar de teruggegeven `basis` exact. Dit is een wijzigingskenmerk, geen token. `gekoppeld` is de actuele Rapportly-status, `beschikbaar` zegt of de serverprovider geconfigureerd is. `verversing_status` kan `verwerken` of `onzeker` zijn; `opnieuw_toestemming_nodig: true` betekent dat je een nieuwe toestemmingsaanvraag moet starten. Een databasefout geeft een fout, niet een lege verbinding. ## 2. Vraag toestemming `POST /autorisaties`, met `Content-Type: application/json` en een unieke `Idempotency-Key`, bijvoorbeeld `crm-agenda-toestemming-0001`. ```json {"soort":"agenda","provider":"google","scope_versie":1,"basis":"geen","bevestigd":true} ``` Gebruik `geen` alleen als stap 1 die waarde teruggaf; anders de exacte ontvangen basis. Bewaar aanvraagnummer en opdrachtcode. Open de ontvangen `url` voor deze gebruiker. Die bevestigt zelf bij Google of Microsoft. De aanvraag verloopt na 15 minuten; maximaal 5 aanvragen tegelijk per sleutel. De callback blijft bij Rapportly, geen eigen redirect-URL nodig. ## 3. Vraag de uitkomst op `GET /autorisaties/`, met dezelfde API-sleutel. Mogelijke statussen: `wacht_op_toestemming`, `verwerken`, `gekoppeld`, `mislukt`, `verlopen`, `onzeker`. Herhaal statusvragen met oplopende wachttijd en respecteer eventuele limietmeldingen. Een verloren startantwoord herstel je met exact dezelfde opdrachtcode en body. Een afgeronde of verlopen aanvraag geeft geen nieuwe providerlink. Bij `onzeker` vraag je eerst nogmaals de status en huidige verbinding op; voor een nieuwe bewuste poging gebruik je een nieuwe opdrachtcode en actuele basis. De providercode wordt nooit blind opnieuw ingewisseld. Sleutelintrekking of gewijzigde rechten tijdens toestemming verhindert nieuwe opslag. `gekoppeld` bij de aanvraag is een historisch ontvangstbewijs. Lees stap 1 opnieuw om te weten of de verbinding nu nog actief is. ## 4. Lees afspraken `GET /agenda/afspraken?uren=24`, met recht `agenda:lezen`. Alleen gehele uren van 1 tot 72; weglaten betekent 24. Je ontvangt aanstaande afspraken met de bestaande Rapportly-klantmatch, uitsluitend voor leesbare klanten. Ruwe deelnemeradressen worden niet teruggegeven. Het beheren of wijzigen van afspraken wordt door deze bestaande agenda-integratie niet aangeboden. ## 5. Ontkoppel bewust Lees stap 1 opnieuw. Stuur `DELETE /verbindingen/agenda/google`, `Content-Type: application/json`, een nieuwe `Idempotency-Key` en: ```json {"basis":"","bevestigd":true} ``` Dit verwijdert Rapportly’s opgeslagen toegang en annuleert nog open toestemmingen voor deze provider/gebruiker. Bij antwoordverlies herhaal je exact hetzelfde verzoek. Een oude herhaling verwijdert geen later opnieuw gemaakte verbinding. `status: ontkoppeld` is een ontvangstbewijs; huidige status lees je apart. `provider_toestemming_ingetrokken: false` maakt duidelijk dat hiermee niet de algemene toestemming in je Google-/Microsoft-account wordt ingetrokken. Een al aan de provider aangeboden verzending kan niet lokaal worden teruggedraaid. ## Fouten en kosten Een basisconflict vraagt opnieuw lezen en een bewuste nieuwe opdracht. Een bezette verversing vraagt wachten; een onzekere verversing kan nieuwe toestemming vereisen. Verwijder geen nieuwe verbinding automatisch om een oude fout op te lossen. Pakket-, sleutel-, scope- en gebruikersrechten blijven gelden. Deze vijf verbindings-/agenda-acties starten geen AI-verwerking en boeken zelf geen credits. Een latere verwerking via de API gebruikt de normale persoonlijke credits en het sleutelbudget. Controleer de huidige providerverbinding en rechten. Een beschreven route bewijst niet dat jouw agenda of mailbox al verbonden is. ## Zelf herstellen en technische ontvangstbewijzen Onder Account toont Rapportly bij een onzekere toegang de knop **Opnieuw verbinden**. Geef bij Google of Microsoft opnieuw toestemming. Bij alleen een tijdelijke statusfout kies je **Status opvragen**; Rapportly ontkoppelt daardoor niets. Een mailboxherstel houdt de eerdere keuze voor concepten of expliciet verzenden aan, zonder automatisch een bericht te sturen. Een toestemmingsaanvraag vervalt na 15 minuten. Onderhoud verwijdert daarna de tijdelijke claimgegevens. Een technische resultaatverwijzing verdwijnt na 30 dagen. Het minimale ontvangstbewijs blijft bij de sleutel, zodat herhalen met dezelfde Idempotency-Key geen nieuwe toestemming start en een oude ontkoppeling geen nieuwe verbinding verwijdert. De ontvangsten verdwijnen mee bij daadwerkelijke verwijdering van de sleutel, organisatie of het gebruikersaccount. Alleen een teamlid loskoppelen is geen accountverwijdering. Deze regels verwijderen geen bestaande rapporten en trekken niet de algemene toestemming bij Google/Microsoft in. ## 6. Kies je standaardmailbox Lees `GET /mailboxvoorkeur` met recht `verbindingen:beheren`. Je krijgt de huidige voorkeur, de feitelijke standaardmailbox, een `basis` voor die keuze en de huidige mailboxen. Kies alleen een mailbox met `verzendbaar: true`. Gebruik de ongewijzigde `verbinding_basis` van die mailbox. De basiswaarden zijn technische versies, geen providertokens. Wijzigen vereist beide sleutelrechten `verbindingen:beheren` en `berichten:verzenden`, ook binnen het beheerdersplafond. De gebruiker moet deze mailbox eerder zelf hebben verbonden met verzendtoestemming. Stuur `PUT /mailboxvoorkeur`, een nieuwe `Idempotency-Key`, `Content-Type: application/json` en: ```json { "provider": "gmail", "basis": "", "verbinding_basis": "", "bevestigd": true } ``` Voor Outlook gebruik je `m365`. Je kunt geen andere gebruiker, organisatie, mailboxadres of provider-URL opgeven. Een teambeheerder beheert de sleutelrechten; de koppeling en keuze horen bij het teamlid aan wie de sleutel is gekoppeld. Het antwoord bevat `ontvangst` (wat deze opdracht heeft opgeslagen) en `huidig` (de opnieuw opgehaalde huidige keuze). Na een verloren antwoord herhaal je exact dezelfde body en opdrachtcode. Een oude ontvangst kan Gmail noemen terwijl `huidig` inmiddels Outlook aanwijst. De herhaling overschrijft die nieuwere keuze niet. Toon daarom de huidige keuze uit `huidig`. Bij `mailvoorkeur_basis_conflict` of `mailvoorkeur_verbinding_conflict` lees je opnieuw en laat je de gebruiker bewust kiezen voordat je een nieuwe opdrachtcode maakt. Ook een tokenverversing kan de verbindingbasis wijzigen. Bij `mailvoorkeur_niet_gekoppeld` herstel je eerst de verbinding of verzendtoestemming. Bij een tijdelijke 503 kun je exact herhalen, of eerst de actuele keuze ophalen. Verbreed nooit automatisch de sleutelrechten. Deze keuze verstuurt geen bericht en kost geen AI-credits. Bestaande outboxopdrachten behouden hun vastgelegde provider. Nieuwe berichtopdrachten volgen afzonderlijk de normale preview, goedkeuring, verbindingcontrole en verzendrechten. Een ontbrekende eerder gekozen mailbox leidt niet tot automatisch verzenden vanuit de andere mailbox. De website gebruikt in de volledige API-modus hetzelfde versiecontract. Een conflict biedt **Huidige keuze ophalen**. Minimale technische voorkeursontvangsten blijven voor veilige herhaling bij de sleutel of het account; ze bevatten geen berichtinhoud of providertokens en verdwijnen mee bij daadwerkelijke verwijdering van de gekoppelde sleutel, organisatie of gebruiker. Native websiteontvangsten zonder API-sleutel volgen organisatie/gebruiker. De bestaande outbox heeft zijn eigen bewaarbeleid.