API voor ontwikkelaars

API voor ontwikkelaars

Koppel je eigen software aan Rapportly met expliciete acties voor bronnen, verwerkingen, resultaten en beheer. Deze handleiding beschrijft de beschikbare API binnen de vermelde releasegrenzen. De gebruiker, rechten, opslag en credits blijven aan het Rapportly-account gekoppeld.

Bereid je koppeling in drie stappen voor

1. 1
   Kies gebruiker, omgeving en rechten

   Open Account → Koppelingen. Gebruik een aparte testsleutel voor de fictieve simulator en een afzonderlijke productiesleutel voor echte acties met fictieve gegevens. Laat de beheerder alleen de benodigde rechten en het passende budget instellen.

2. 2
   Oefen ontvangst en fouten

   Gebruik eerst de simulator. Importeer daarna de API-contracten en beoordeel de synthetische voorbeelden. Geheimen blijven in je eigen serverinstellingen; mutaties staan in de collectie standaard uit.

3. 3
   Volg een complete opdracht

   Bewaar invoer en opdrachtcode, controleer start en eindstatus, lees het resultaat, download een beschikbaar bestand en controleer het verbruik. Voer die proef pas uit in een vrijgegeven omgeving.

Maak je API-sleutel aan

Basisadres

https://api.rapportly.io/api/rapportly/v1

De sleutel hoort bij een gebruiker

Een sleutel delegeert rechten van één gebruiker. De beheerder stelt omgeving, rechtenplafond, maandbudget en vervaldatum in. Een teamlid activeert een klaargezette sleutel zelf en ziet het geheim één keer. Ieder verzoek controleert ook actuele gebruikers-, pakket- en objectrechten. Sleutelbeheer gebruikt een gebruikerssessie; productieacties een API-sleutel. Bewaar geheimen op je server en trek een verloren sleutel in via Account → Koppelingen. Bestaande Zapier-events volgen hun eigen contract.

GET https://api.rapportly.io/api/rapportly/v1/ping
Authorization: Bearer rply_<jouw_sleutel>

Gebruik concrete contracten en voorbeelden

De productie-OpenAPI beschrijft concrete broncontracten en markeert gedeeltelijke invoer of antwoorden. De inventaris toont de schema’s die nog openstaan. De Postman-collectie begint met een ongeldig adres, lege sleutels en uitgeschakelde mutaties. Importeer voor beoordeling en verstuur bewust in een vrijgegeven omgeving met fictieve gegevens. De import is nog niet getest.

• Download de productie-OpenAPI
• Download de synthetische Postman-collectie
• Download het stappenplan van bron tot resultaat en download
• Download de schema-inventaris met open onderdelen

Oefen eerst met fictieve opdrachten

Maak een aparte testsleutel en oefen hoe jouw software omgaat met een lopende opdracht, een resultaat, een fout en onvoldoende budget. De oefenomgeving gebruikt vaste voorbeeldinhoud en kost geen credits.

1. Maak of activeer in Account → Koppelingen een sleutel met omgeving Test en de actierechten die je wilt oefenen.
2. Vraag GET /test/scenarios op. Kies een actie-id uit het antwoord; dit overzicht volgt jouw actuele sleutelrechten.
3. Stuur POST /test/opdrachten met alleen actie en scenario. Kies succes, verwerking_mislukt, creditbudget_bereikt of toegang_geweigerd. Gebruik voor elke nieuwe oefenopdracht een eigen Idempotency-Key.
4. Bewaar opdracht_id. Bij status bezig lees je na ongeveer vijf seconden GET /test/opdrachten/{id}. Controleer altijd status: HTTP200 kan ook een mislukte verwerking bevatten.

POST https://api.rapportly.io/api/rapportly/v1/test/opdrachten
Authorization: Bearer rply_test_<jouw_testsleutel>
Idempotency-Key: test-rapport-0001
Content-Type: application/json

{
  "actie": "rapport.start",
  "scenario": "succes"
}

Dit voorbeeld vereist dat rapport.start in jouw actielijst staat. Herhaal bij een verbindingsprobleem dezelfde body met dezelfde Idempotency-Key.

• Download het stappenplan voor de oefenomgeving
• Download de importeerbare Postman-oefencollectie
• Download de OpenAPI-specificatie van de oefenomgeving

Haal alleen op wat je nodig hebt

Zoek toegankelijke klantmappen, gesprekken en rapporten. Lees /acties voor aangesloten acties en rechten, /gebruik voor budget en reserveringen en /verzoeken voor technische verzoekhistorie. Een lopende verwerking heeft nog geen resultaat. Downloadlinks voor rapportbestanden zijn 15 minuten geldig; lees het rapport opnieuw voor een nieuwe link.

Klantbeheer bijwerken

Je software kan kantoorsjablonen aanpassen, persoonlijke zoekopdrachten bewaren, een bezoek registreren en een traject aanmaken. Gebruik de passende beheerrechten en bevestig iedere wijziging. Lees eerst de actuele versie en bewaar dezelfde opdrachtcode bij antwoordverlies. Een oude herhaling mag een nieuwere wijziging niet terugzetten. De productieproef controleert zoekopdrachten, bezoek en trajecten, inclusief opruiming en sleutelintrekking. Kantoorsjablonen zijn daarin alleen gelezen; schrijven is lokaal en in CI getest. De downloadgids beschrijft de vier routes en hun bewijsgrenzen.

Twee opgeslagen versies vergelijken

Vergelijk twee bestaande versienummers van hetzelfde opgeslagen rapporttekstveld of gespreksveld zonder nieuwe AI-verwerking. Dit contract is lokaal en in CI getest; de CRM-productieproef bewijst het productiegedrag van vergelijken niet. Ontbrekende historie wordt niet aangevuld met de huidige tekst. Lange verschillen worden zichtbaar ingekort tot maximaal 8.000 tekens per kant. Dit vergelijkt geen PowerPoint, offerteberekening, begeleidende brief of opmaak. Actuele leesrechten en privacyvoorwaarden blijven gelden.

Vooraf een kostenraming opvragen

Laat je software via POST /generatieplan de verwachte stappen en credits opvragen voor een rapport, offerte of gespreksbundel. Gebruik het recht gebruik:lezen. Rapportly gebruikt dezelfde berekening en teaminstellingen als de website.

Een raming start geen verwerking en boekt geen credits af. De uitkomst is geen gegarandeerde maximumprijs; toon ook de onzekerheden, bijvoorbeeld nog onbekende kosten voor het uitlezen van bestanden. De uiteindelijke start controleert opnieuw rechten en beschikbare credits.

Download de kostenraminghandleiding met invoervoorbeeld en antwoorduitleg

Start een verwerking vanuit je eigen software

De API verbindt dossier- en documentstarts, uploads, audio en transcriptie, klantmappen, stijlen, uitvoer, workflows, Excel en gerichte berichtacties. Iedere route heeft eigen invoer, rechten, bevestiging en versiecontrole. De bestaande verwerking en creditafrekening blijven gelden. Een startantwoord bewijst ontvangst; lees daarna de concrete status. De inventaris benoemt contracten die nog openstaan.

Maak eerst een dossier aan

Maak in je eigen software een unieke UUID en bewaar die. Stuur PUT /dossiers/{id} met alleen naam (maximaal 200 tekens). Je krijgt 201 bij aanmaak en 200 bij een identieke herhaling. Het dossier hoort bij de gebruiker en organisatie van de sleutel. Dossieraanmaak kost geen credits. Deze route overschrijft niets: andere invoer geeft 409; een ontoegankelijk of verwijderd dossier geeft 404. GET /dossiers/{id} leest de actuele naam en klant_id met leesrecht.

PUT https://api.rapportly.io/api/rapportly/v1/dossiers/00000000-0000-4000-8000-000000000002
Authorization: Bearer rply_<jouw_sleutel>
Content-Type: application/json

{ "naam": "Voorbeeldproject" }

Rapport, offerte of presentatie

Gebruik dossierId en notities als begin. tier is optioneel: basis, standaard of max. Zonder stijlprofiel start je met neutrale opmaak. Je kunt ook een bestaand, toegankelijk stijlprofielId, klantId, bronOpnameIds of taal meesturen. De server controleert of de gekozen stijl bij het documenttype past. Een offerte gebruikt de vastgelegde bedrijfsinstellingen en veilige offertenummering; de API verstuurt de offerte niet naar de klant.

POST https://api.rapportly.io/api/rapportly/v1/rapporten
Authorization: Bearer rply_<jouw_sleutel>
Idempotency-Key: crm-rapport-2026-0001
Content-Type: application/json

{
  "dossierId": "00000000-0000-4000-8000-000000000002",
  "notities": "Team Atlas besprak de training. Noor plant de volgende bijeenkomst op donderdag.",
  "tier": "standaard"
}

Bewaar versie_id uit het antwoord en volg GET /rapporten/{versie_id}, ook voor offertes en presentaties. Pas bij status klaar zijn bestanden beschikbaar in het object resultaat: resultaat.export_url is de PDF, resultaat.export_url_docx het Word-bestand en resultaat.export_url_pptx de PowerPoint als die beschikbaar is. Downloadlinks verlopen na 15 minuten. Vraag het resultaat opnieuw op voor nieuwe links. Bij mislukt start je niet automatisch opnieuw met een nieuwe sleutel; controleer eerst de verwerking en het verbruik in Rapportly.

Download het stappenplan van bron tot resultaat en download

Je eigen stijlvoorbeelden uploaden

Laat je software één tot drie voorbeeldbestanden als complete set aanbieden. Rapportly gebruikt dezelfde bestandcontrole en stijlverwerking als de website. De opdracht hoort bij de gekoppelde gebruiker en gebruikt diens opslag en beschikbare credits.

1. Verstuur de bestanden met naam, documenttype, persoonlijk of team, expliciete bevestiging en een vaste opdrachtcode. Voor een teamstijl moet de gebruiker beheerder of teamleider zijn.
2. Bewaar de ontvangst-ID en vraag de status op. Ontvangen betekent dat de complete set veilig is vastgelegd; eventuele voorbeeldcontrole en goedkeuring volgen daarna.
3. Herhaal na een onderbreking precies dezelfde aanvraag. Er ontstaat geen tweede stijl. Onvolledige uploads kunnen dertig dagen worden herhaald en worden daarna gecontroleerd opgeruimd.

Download de handleiding voor stijlvoorbeelden, met multipartvoorbeeld en foutafhandeling

Je agenda of mailbox verbinden

Laat de gebruiker zelf toestemming geven bij Google of Microsoft. Je software kan de aanvraag volgen en de verbinding bewust stoppen. Providerwachtwoorden en tokens blijven buiten de API-respons.

Gebruik verbindingen:beheren voor koppelingen en agenda:lezen voor afspraken. Verzenden vraagt bovendien een afzonderlijk verzendrecht en bewuste opdracht.

Bewaar aanvraagnummer, opdrachtcode en huidige basis. Herhaal een verloren verzoek exact; een oude ontkoppeling mag geen later gemaakte verbinding verwijderen.

Je standaardmailbox kun je ook via de API kiezen. Daarvoor zijn beheer- en verzendrecht nodig. Lees eerst de huidige keuze en verbinding; een oude herhaling verandert geen nieuwere keuze en bestaande verzendopdrachten houden hun afzender.

Download de stappen voor toestemming, afspraken, ontkoppelen en herstel

Gespreksbundel uit tekst

Stuur een transcript van minimaal honderd tekens. Het antwoord geeft een gesprek_id terug waarmee je het resultaat kunt volgen. Optioneel: titel, tier, klantId en taal.

POST https://api.rapportly.io/api/rapportly/v1/gesprekken
Authorization: Bearer rply_<jouw_sleutel>
Idempotency-Key: crm-gesprek-2026-0001
Content-Type: application/json

{
  "transcript": "Team Atlas bespreekt uitsluitend een fictieve oefening. Het team plant een training en verzamelt algemene voorbeeldvragen zonder klantgegevens.",
  "titel": "Kennismaking"
}

Bestaande taalvarianten lezen

Lees bestaande taalresultaten. De beschreven workflowroutes voor starten, pauzeren, hervatten en herstel zijn lokaal en in CI getest; de CRM-productieproef bewijst deze taalverwerking niet. Gebruik ze uitsluitend in een daarvoor vrijgegeven omgeving. De oorspronkelijke gebruiker, sleutel, bron en kosten blijven aan de opdracht gekoppeld. Actuele bronstatus, rechten, budget en gecontroleerde afrekening blijven vereist; een verlopen of verwijderde bron geeft geen nieuwe startbevoegdheid. Bulk met een ingeschakelde tweede taal blijft gesloten, ook bij overgenomen instellingen. Betaald aanvullen van één ontbrekend vertaalonderdeel blijft uitgesloten.

GET https://api.rapportly.io/api/rapportly/v1/gesprekken/00000000-0000-4000-8000-000000000001/taalvarianten
Authorization: Bearer rply_<jouw_sleutel>

Ontvang automatisch bericht als een verwerking klaar is

Laat Rapportly een melding naar jouw server sturen. De melding bevat technische verwijzingen; de inhoud haal je daarna op met de juiste leesrechten. Zo hoeft je software niet voortdurend naar de voortgang te vragen.

1. Maak een HTTPS-ontvanger op je eigen server. Registreer deze met POST /webhooks en een productiesleutel met webhooks:beheren. Gebruik diezelfde sleutel voor de verwerkingen waarover je meldingen wilt ontvangen.
2. Controleer de handtekening op de oorspronkelijke berichtbytes en bewaar ieder event-id uniek. Bevestig de melding pas nadat je haar samen met jouw vervolgtaak veilig hebt opgeslagen. Een herhaalde melding mag geen tweede opdracht veroorzaken.
3. Bekijk GET /webhook-afleveringen en de details per aflevering. Rapportly probeert tijdelijke fouten maximaal acht keer opnieuw. Na een probleem kun je één extra ronde aanvragen. Geaccepteerd betekent dat jouw server de melding aannam; controleer de verdere verwerking in je eigen systeem.

• Download de webhookhandleiding met routes, grenzen en herstelstappen
• Download het Node.js-voorbeeld voor handtekeningcontrole

De fictieve oefenomgeving verstuurt geen echte meldingen. Test je ontvanger met fictieve gegevens en een afzonderlijke productieaansluiting. Het codevoorbeeld controleert de melding; jouw eigen server regelt opslag en vervolgacties.

Wat betekent een foutcode?

Bescherm de sleutel en de klantgegevens

• Gebruik de sleutel alleen op je server, nooit in openbare browsercode.
• Maak per koppeling een eigen sleutel en trek oude sleutels in.
• Zet sleutels, resultaten en tijdelijke downloadlinks niet in openbare logs of chatberichten.
• Bewaar opgehaalde klantgegevens volgens de toegangsregels van je eigen systeem.