API für Entwickler

API für Entwickler

Verbinde deine Software über ausdrückliche Aktionen für Quellen, Verarbeitung, Ergebnisse und Verwaltung. Diese Anleitung beschreibt die verfügbare API innerhalb der dokumentierten Freigabegrenzen. Benutzer, Rechte, Speicher und Credits bleiben an das Rapportly-Konto gebunden.

Bereite deine Anbindung in drei Schritten vor

1. 1
   Benutzer, Umgebung und Rechte wählen

   Öffne Konto → Anbindungen. Nutze getrennte Test- und Produktionsschlüssel. Der Testschlüssel gehört zum fiktiven Simulator; echte Aktionen mit fiktiven Daten verwenden einen Produktionsschlüssel mit passenden Rechten und Budget.

2. 2
   Empfang und Fehler üben

   Beginne mit dem Simulator und prüfe danach die API-Verträge und synthetischen Beispiele. Geheimnisse bleiben auf deinem Server; Änderungen sind in der Sammlung standardmäßig deaktiviert.

3. 3
   Einen vollständigen Auftrag verfolgen

   Speichere Eingabe und Auftragskennung, prüfe Start und Endstatus, lies das Ergebnis, lade eine verfügbare Datei herunter und kontrolliere den Verbrauch. Führe dies erst in einer freigegebenen Umgebung aus.

API-Schlüssel erstellen

Basisadresse

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

Der Schlüssel gehört zu einem Benutzer

Ein Schlüssel delegiert die Rechte eines Benutzers. Der Administrator bestimmt Umgebung, Rechteobergrenze, Monatsbudget und Ablaufdatum. Das Teammitglied aktiviert einen vorbereiteten Schlüssel selbst und sieht das Geheimnis einmal. Aktuelle Benutzer-, Paket- und Objektrechte gelten bei jedem Aufruf. Schlüsselverwaltung nutzt eine Benutzersitzung, Produktionsaktionen einen API-Schlüssel. Geheimnisse gehören auf deinen Server; verlorene Schlüssel unter Konto → Anbindungen widerrufen. Zapier-Ereignisse haben einen eigenen Vertrag.

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

Konkrete Verträge und Beispiele verwenden

Die Produktions-OpenAPI beschreibt Quellcode-Verträge und kennzeichnet unvollständige Ein- oder Ausgaben. Das Inventar zeigt offene Schemata. Die Postman-Sammlung beginnt mit ungültiger Adresse, leeren Schlüsseln und deaktivierten Änderungen. Importiere zur Prüfung und sende nur bewusst mit fiktiven Daten in einer freigegebenen Umgebung. Der Import wurde noch nicht getestet.

• Produktions-OpenAPI herunterladen
• Synthetische Postman-Sammlung herunterladen
• Anleitung von der Quelle bis zum Download herunterladen
• Schema-Inventar mit offenen Punkten herunterladen

Zuerst mit fiktiven Aufträgen üben

Erstelle einen Testschlüssel und übe laufende Aufträge, Ergebnisse, Fehler und fehlendes Budget. Der Simulator verwendet feste Beispieldaten und kostet keine Credits.

1. Erstelle oder aktiviere unter Konto → Anbindungen einen Schlüssel für Test mit den benötigten Aktionsrechten.
2. Rufe GET /test/scenarios auf und wähle eine Aktion aus der Antwort. Die Liste berücksichtigt deine aktuellen Rechte.
3. Sende POST /test/opdrachten nur mit actie und scenario: succes, verwerking_mislukt, creditbudget_bereikt oder toegang_geweigerd. Jeder neue Übungsauftrag erhält einen eigenen Idempotency-Key.
4. Speichere opdracht_id. Bei bezig nach ungefähr fünf Sekunden GET /test/opdrachten/{id} lesen. Status immer prüfen: HTTP200 kann einen Verarbeitungsfehler enthalten.

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"
}

Dieses Beispiel erfordert rapport.start in deiner Aktionsliste. Bei Verbindungsfehler dieselbe Eingabe mit demselben Schlüssel wiederholen.

• Simulatoranleitung herunterladen
• Postman-Übungssammlung herunterladen
• OpenAPI des Simulators herunterladen

Rufe nur benötigte Daten ab

Suche zugängliche Kundenordner, Gespräche und Berichte. /acties zeigt Aktionen und Rechte, /gebruik Budget und Reservierungen, /verzoeken technische Anfragen. Laufende Verarbeitung hat noch kein Ergebnis. Berichtslinks gelten 15 Minuten; lies den Bericht erneut für einen neuen Link.

Kundenverwaltung aktualisieren

Deine Software kann Bürovorlagen anpassen, persönliche Suchanfragen speichern, einen Besuch erfassen und einen Vorgang anlegen. Verwende die passenden Verwaltungsrechte und bestätige jede Änderung. Lies zuerst die aktuelle Version und behalte bei einem Antwortverlust dieselbe Anfragenkennung bei. Das Wiederholen einer alten Anfrage darf eine neuere Änderung nicht zurücksetzen. Der Produktionstest prüft Suchanfragen, Besuche und Vorgänge einschließlich Bereinigung und Schlüsselwiderruf. Bürovorlagen wurden dabei nur gelesen; Schreibzugriffe wurden lokal und in CI getestet. Die herunterladbare Anleitung beschreibt die vier Routen und die Grenzen ihrer Nachweise.

Zwei gespeicherte Versionen vergleichen

Vergleiche zwei vorhandene Versionsnummern desselben gespeicherten Berichtstextfelds oder Gesprächsfelds ohne neue KI-Verarbeitung. Dieser Vertrag wurde lokal und in CI getestet; der CRM-Produktionstest belegt das Produktionsverhalten des Vergleichs nicht. Fehlende Historie wird nicht durch den aktuellen Text ergänzt. Lange Unterschiede werden mit sichtbarem Hinweis auf höchstens 8000 Zeichen pro Seite gekürzt. PowerPoint, Angebotsberechnungen, Begleitschreiben und Formatierungen werden dabei nicht verglichen. Aktuelle Leserechte und Datenschutzbedingungen gelten weiterhin.

Kosten vorab schätzen

POST /generatieplan zeigt erwartete Schritte und Credits für Bericht, Angebot oder Gesprächspaket. Verwende gebruik:lezen. Berechnung und Teameinstellungen entsprechen der Website.

Eine Schätzung startet keine Verarbeitung und bucht keine Credits ab. Sie ist kein garantierter Höchstpreis. Zeige Unsicherheiten wie noch unbekannte Dateilesekosten. Beim Start werden Rechte und Credits erneut geprüft.

Schätzungsanleitung mit Ein- und Ausgaben herunterladen

Starte Verarbeitung aus deiner Software

Die API verbindet Akten- und Dokumentstarts, Uploads, Audio, Transkription, Kundenordner, Stile, Ausgaben, Workflows, Excel und gezielte Nachrichten. Jede Route hat eigene Eingaben, Rechte, Bestätigungen und Versionsprüfungen. Bestehende Verarbeitung und Creditabrechnung gelten weiter. Die Startantwort bestätigt den Empfang; lies danach den Status. Offene Verträge stehen im Inventar.

Zuerst eine Akte erstellen

Erzeuge und speichere eine UUID. Sende PUT /dossiers/{id} mit naam, höchstens 200 Zeichen. 201 bedeutet erstellt, 200 identisch wiederholt. Die Akte gehört zum Benutzer und zur Organisation des Schlüssels und kostet keine Credits. Abweichende Eingaben ergeben 409, unzugängliche oder gelöschte Akten 404. GET /dossiers/{id} liest naam und klant_id mit Leserecht.

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" }

Bericht, Angebot oder Präsentation

Beginne mit dossierId und notities. tier ist optional: basis, standaard oder max. Ohne Stilprofil wird neutrales Layout verwendet. Zugängliche stijlprofielId, klantId, bronOpnameIds und taal sind optional. Der Stil muss zum Dokumenttyp passen. Angebote verwenden bestehende Firmeneinstellungen und sichere Nummerierung; die API sendet sie nicht an Kunden.

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"
}

Speichere versie_id und verfolge GET /rapporten/{versie_id}, auch für Angebote und Präsentationen. Bei klaar enthält resultaat verfügbare Dateien: export_url für PDF, export_url_docx für Word und export_url_pptx für PowerPoint. Links gelten 15 Minuten. Bei mislukt zuerst Verarbeitung und Verbrauch prüfen; nicht automatisch mit einem neuen Schlüssel starten.

Anleitung von der Quelle bis zum Download herunterladen

Eigene Stilbeispiele hochladen

Übermittle ein bis drei Beispieldateien als vollständigen Satz. Rapportly verwendet dieselbe Datei- und Stilprüfung wie die Website. Speicher und Credits gehören zum verknüpften Benutzer.

1. Sende Dateien, Namen, Dokumenttyp, persönlichen oder Teamumfang, ausdrückliche Bestätigung und feste Auftragskennung. Teamstile erfordern Administrator oder Teamleitung.
2. Speichere die Empfangs-ID und lies den Status. Empfang bedeutet sichere Speicherung des vollständigen Satzes; Vorschauprüfung und Freigabe folgen gegebenenfalls später.
3. Wiederhole nach einer Unterbrechung genau dieselbe Anfrage, ohne einen zweiten Stil anzulegen. Unvollständige Uploads sind dreißig Tage wiederholbar und werden danach kontrolliert bereinigt.

Stilbeispiel-Anleitung mit Multipart und Fehlerbehandlung herunterladen

Kalender oder Postfach verbinden

Der Benutzer erteilt Google oder Microsoft selbst seine Zustimmung. Deine Software verfolgt die Anfrage und kann die Verbindung bewusst beenden. Anbieterpasswörter und Tokens erscheinen nicht in der Antwort.

Nutze verbindingen:beheren für Verbindungen und agenda:lezen für Termine. Versand erfordert zusätzlich Versandrecht und einen bewussten Auftrag.

Speichere Anfragenummer, Auftragskennung und aktuelle Basis. Wiederhole verlorene Anfragen exakt; eine alte Trennung darf eine spätere Verbindung nicht entfernen.

Die API kann das Standardpostfach wählen. Verwaltungs- und Versandrecht sind erforderlich. Lies zuerst aktuelle Wahl und Verbindung. Eine alte Wiederholung verändert keine neuere Wahl; bestehende Versandaufträge behalten ihren Absender.

Anleitung für Zustimmung, Termine, Trennung und Wiederherstellung herunterladen

Gesprächspaket aus Text

Sende ein Transkript mit mindestens hundert Zeichen. Verfolge das Ergebnis über gesprek_id. Optional: titel, tier, klantId und 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"
}

Bestehende Sprachvarianten lesen

Lies vorhandene Sprachergebnisse. Die beschriebenen Workflow-Routen zum Starten, Pausieren, Fortsetzen und Wiederherstellen wurden lokal und in CI getestet; der CRM-Produktionstest belegt diese Sprachverarbeitung nicht. Nutze sie ausschließlich in einer dafür freigegebenen Umgebung. Der ursprüngliche Benutzer, Schlüssel, die Quelle und die Kosten bleiben an die Anfrage gebunden. Der aktuelle Quellenstatus, Rechte, Budget und geprüfte Abrechnung bleiben erforderlich; eine abgelaufene oder gelöschte Quelle berechtigt nicht zu einem neuen Start. Stapelverarbeitung mit aktivierter zweiter Sprache bleibt gesperrt, auch bei übernommenen Einstellungen. Das kostenpflichtige Ergänzen eines einzelnen fehlenden Übersetzungsergebnisses bleibt ausgeschlossen.

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

Benachrichtigung bei abgeschlossener Verarbeitung

Rapportly kann deinen Server mit technischen Verweisen benachrichtigen. Inhalte rufst du anschließend mit passenden Leserechten ab, ohne ständig den Fortschritt abzufragen.

1. Erstelle einen HTTPS-Empfänger. Registriere ihn über POST /webhooks mit webhooks:beheren. Verwende denselben Produktionsschlüssel für die betreffenden Verarbeitungen.
2. Prüfe die Signatur anhand der ursprünglichen Nachrichtenbytes und speichere jede Ereignis-ID eindeutig. Bestätige erst nach sicherer Speicherung zusammen mit der Folgeaufgabe. Wiederholungen dürfen keinen zweiten Auftrag auslösen.
3. Lies GET /webhook-afleveringen und die Zustelldetails. Temporäre Fehler werden höchstens achtmal wiederholt; danach kann eine weitere Runde angefordert werden. Angenommen bedeutet nur Empfang durch deinen Server. Prüfe dort die weitere Verarbeitung.

• Webhookanleitung mit Grenzen und Wiederherstellung herunterladen
• Node.js-Beispiel zur Signaturprüfung herunterladen

Der Simulator versendet keine echten Meldungen. Prüfe deinen Empfänger mit fiktiven Daten und separater Produktionsanbindung. Das Beispiel prüft Signaturen; Speicherung und Folgeaktionen liegen bei deinem Server.

Was bedeutet ein Fehlercode?

Schlüssel und Kundendaten schützen

• Schlüssel nur auf deinem Server verwenden, nie in öffentlichem Browsercode.
• Pro Anbindung einen eigenen Schlüssel verwenden und alte Schlüssel widerrufen.
• Schlüssel, Ergebnisse und temporäre Links nicht in öffentliche Protokolle oder Chats schreiben.
• Abgerufene Kundendaten nach den Zugriffsregeln deines Systems speichern.