API-Integrationen: PDF, Dinaco, Microsoft Graph, Templates und Dateien

Native Integrationen und Plugins einrichten

Für die Einrichtung beginnen Sie bei der jeweiligen Kundenfunktion: Bexio wird über den Plugin Manager freigeschaltet und unter Integrationen → Buchhaltung verbunden. Automationen erhalten einen eigenen Regelbereich. Im Bereich Integrationen finden Sie ausserdem DINACO und die Zugangssysteme.

Nutzen Sie die folgenden technischen Zusammenhänge zur Einordnung. Konkrete Schritte stehen auf den verlinkten Unterseiten. Ein E-Mail-Konto zum Microsoft-Versand, eine SAML-Anmeldung und ein Microsoft-Ads-Trackingziel sind getrennte Verbindungen mit eigenen Einstellungen.

edoobox besitzt neben der öffentlichen API mehrere Integrationsbereiche. Diese verbinden sichtbare Funktionen wie PDF-Erzeugung, Dinaco-Einlass, Microsoft Graph, Vorlagen, Dateiablage, Exporte, SAML und externe Hilfsabfragen mit den Daten Ihres Kontos.

Diese Seite ist eine Orientierung für Admins und technische Ansprechpersonen. Sie ersetzt nicht die Detailanleitungen, sondern zeigt, welche Funktionen fachlich zusammenhängen und wo Sie bei Einrichtung oder Fehlersuche weiterlesen.

API-Zugangsverwaltung in edoobox mit vorhandenen Schlüsseln und Rechteauswahl.

AAPI-ZugangsverwaltungBSicherheitshinweisCSchlüsselstatus und Rechte

Überblick und Abgrenzung

Die öffentliche API eignet sich für externe Clients, individuelle Exporte und eigene Integrationen. Interne Integrationsschichten werden von edoobox genutzt, wenn Dokumente erstellt, Dateien gelesen, Vorlagen gerendert, Tickets synchronisiert oder externe Dienste angesprochen werden.

Dinaco: sendet Ticket-, Section-, Permission- und Merge-Daten an die Zutrittskontrolle.
PDF und Post: rendert PDFs, erzeugt RF-Referenzen, bettet Zahlungsdaten ein und versendet Briefe.
Microsoft Graph: versendet E-Mails über ein verbundenes Microsoft-Konto.
Templates: verarbeitet E-Mail- und PDF-Vorlagen mit Platzhaltern, Bedingungen und Schleifen.
Dateien und Exporte: verwaltet Speicher, signierte URLs und Tabellenexporte.
SAML und Hilfsabfragen: unterstützt SSO, IP-Hilfsdaten und Umsatzsteuerprüfungen.

Dinaco Ticketing und Einlassdaten

Die Dinaco-Integration verbindet edoobox mit externer Zutrittskontrolle. Event-Verbindungen, Sections, Permissions und Tickets sorgen dafür, dass Buchungsdaten in der Einlasslösung verarbeitet werden können.

Fachlich wichtig sind Client-ID, Secret, Event-ID, Section, Permission, Barcode, Kontaktinformationen und Ticketstatus. Permissions enthalten Kriterien, Start, Ende und Bereichsbezug; Sections beschreiben die Einlassbereiche. Tickets können je nach Prozess gültig, neu oder storniert beziehungsweise gesperrt sein; prüfen Sie daher immer Buchung, Ticketstatus und Dinaco-Synchronisation zusammen.

Zugangstokens werden nicht bei jedem Klick neu erstellt, sondern für eine kurze Zeit zwischengespeichert. Wenn Zugangsdaten geändert wurden, kann ein Fehler deshalb kurz weiter sichtbar sein. Testen Sie nach Änderungen mit einer einzelnen Buchung oder einem einzelnen Ticket.

Wenn Dinaco nicht wie erwartet synchronisiert, prüfen Sie zuerst Zugangsdaten, Event-Verbindung, Synchronisationszeitraum, Sections, manuelle Synchronisation und ob die betroffenen Tickets überhaupt gültig und öffentlich relevant sind. Die Bedienung in der Oberfläche steht unter Dinaco-Integration und Ticketing, Einlassscan, Dinaco und Präsenzkontrolle.

Anwendungsbeispiel: Dinaco-Event manuell synchronisieren

Nach dem Hinterlegen von Client-ID und Secret legt die Administration eine Event-Verbindung an. Wenn sich Sections oder Zutrittsdaten kurzfristig ändern, öffnet sie die Synchronisation für dieses Event und startet den Abgleich manuell, statt auf den nächsten Hintergrundlauf zu warten.

PDF, Rechnungen, QR-/RF-Referenzen und Briefversand

PDF-Ausgaben berühren Vorlagen, Fonts, Bilder, Anhänge, Rechnungsdaten, Barcodes, QR-/RF-Referenzen, ZUGFeRD-Daten, Signaturen und optional Briefversand. Dadurch kann ein scheinbares PDF-Problem verschiedene Ursachen haben: Vorlage, Platzhalter, Bildgrösse, Dateiablage, Sprache, Rechnung oder Signatur.

edoobox kann PDF-Vorlagen als Hintergrund verwenden, HTML an festen Positionen rendern, Bilder einbetten und je nach Prozess Rechnungen, Tickets, Booking-PDFs, Stornorechnungen, Mahnungen oder Bestätigungen erzeugen. RF-Referenzen werden für Zahlungsreferenzen normalisiert und geprüft; QR-Rechnungen benötigen zusätzlich korrekte Rechnungs- und Zahlungsdaten.

Für PDF-Vorlagen sind Bildqualität und Bildgrösse wichtig. Bilder werden für das PDF eingebettet; leere, nicht erreichbare oder zu grosse Bilder können im PDF fehlen. Verwenden Sie deshalb saubere Vorlagenbilder, prüfen Sie Logos und Hintergründe in der PDF-Vorschau und testen Sie mehrsprachige Sonderzeichen.

edoobox unterstützt unterschiedliche Schriftarten und internationale Zeichensätze, damit auch Sprachen mit Sonderzeichen, asiatischen Zeichen oder Symbolen besser in PDFs dargestellt werden können. Wenn ein PDF falsch aussieht, prüfen Sie neben dem Platzhalter auch Sprache, Font, Hintergrund-PDF und eingebettete Bilder.

Beim Briefversand wird ein fertiges PDF an einen Versanddienst übergeben, dort verarbeitet und später mit Statusinformationen zurückgemeldet. Lesen Sie dazu Eigene PDF-Anhänge und Templates, QR-Rechnungen und Briefversand der Rechnung.

Anwendungsbeispiel: Rechnung als PDF und Brief versenden

Eine Rechnung wird als PDF gerendert, Bilder werden eingebettet und eine RF-Referenz erzeugt. Wenn Briefversand aktiv ist, übergibt edoobox den PDF-Inhalt an den Versanddienst, speichert die externe Sendungs-ID und aktualisiert später den Versandstatus.

Microsoft Graph: E-Mail-Versand

Microsoft Graph wird für den E-Mail-Versand über ein verbundenes Microsoft-Konto verwendet. Prüfen Sie die Verbindung, den vorgesehenen Absender und die erteilten Versandberechtigungen. Für den einzelnen Versand sind ausserdem Empfänger, CC, Reply-To, HTML-Inhalt und Anhänge relevant.

Eine von Microsoft angenommene Nachricht bedeutet, dass Graph den Versandauftrag akzeptiert hat. Ob die Nachricht beim Empfänger zugestellt oder später abgewiesen wird, prüfen Sie weiterhin über Postausgang, Fehlermeldung, Providerhinweis und gegebenenfalls das Microsoft-Postfach.

Graph-Antworten werden fachlich unterschieden: akzeptierte Nachricht, temporärer Fehler, Provider- oder Authentifizierungsfehler und permanente Payload-Probleme. Diese Klassifizierung ist wichtig für den Postausgang und erneute Zustellversuche.

Richten Sie die Verbindung nach Microsoft-Konto für den E-Mail-Versand verbinden ein. Testen Sie danach eine einzelne Nachricht mit dem vorgesehenen Absender und kontrollieren Sie sowohl den Postausgang als auch den Empfang. Eine erfolgreiche Anmeldung allein bestätigt noch keinen erfolgreichen Versand.

Template-Rendering und Platzhalter

Vorlagen für E-Mails und PDFs werden in mehreren Schritten verarbeitet. Zuerst werden Schleifen über wiederholbare Daten verarbeitet, danach Bedingungen geprüft und zuletzt Platzhalter ersetzt. Dadurch sind komplexe Vorlagen möglich, zum Beispiel Listen gebuchter Leistungen, konditionale Hinweise, Ticket-Barcodes oder promotionsbezogene Texte.

PDF- und Mail-Vorlagen hängen zusätzlich vom Abonnement, von aktivierten Sprachen, eigenen PDF-Hintergründen, Dateinamen je Sprache und vorhandenen Daten ab. Nicht jede Vorlage kennt alle Platzhalter; ein Platzhalter kann in einer Rechnung funktionieren, in einer Erinnerungsmail aber leer bleiben.

Wichtig ist die Reihenfolge: Ein Platzhalter in einer Bedingung oder Schleife muss zu den Daten passen, die für diese Vorlage verfügbar sind. Prüfen Sie deshalb Alle Platzhalter für E-Mails und PDFs und E-Mail-Vorlagen mit IF und EACH.

Anwendungsbeispiel: Vorlage mit Bedingung und Schleife

Eine E-Mail-Vorlage enthält eine Liste gebuchter Leistungen und einen Rabatt-Hinweis nur für bestimmte Tags. edoobox rendert zuerst jede Leistung, prüft danach die Bedingung und ersetzt zuletzt Namen, Datum und weitere Platzhalter.

Dateien, Exporte, SAML und Hilfsabfragen

Dateien können je nach Umgebung in unterschiedlichen Speichern liegen. edoobox liest Objekte, erzeugt signierte URLs für Upload oder Download und löscht Dateien, wenn der Prozess dies vorsieht. Für Admins wird das über Dokumente, Templates, Uploads oder den Secure File Manager sichtbar.

Signierte URLs sind zeitlich begrenzt. Wenn ein Download-Link abläuft oder ein Upload nicht mehr funktioniert, laden Sie die Datei aus der Oberfläche neu, statt alte Links weiterzugeben. Das ist besonders wichtig bei geschützten Kursunterlagen, E-Mail-Anhängen und temporären Exporten.

Tabellenexporte können CSV, XLSX, ODS oder andere Formate erzeugen. Bei sehr grossen Datenmengen kann ein CSV sinnvoller sein als eine umfangreiche Excel-Datei; grosse Exporte können automatisch anders verarbeitet werden. Die fachlichen Grundlagen stehen unter Tabellen und Exportmöglichkeiten.

SAML unterstützt SSO-Flows mit Metadaten, NameID-Formaten, Login-Scopes und IdP-Antworten. Externe Hilfsabfragen können IP- oder Umsatzsteuerinformationen unterstützen und werden teilweise gecached. Die SAML-Einrichtung finden Sie unter Single Sign On via SAML in edoobox aktivieren.

Öffentliche API oder interne Integration?

Wenn ein externes System Daten lesen oder schreiben soll, ist die öffentliche API der richtige Weg. Dafür erstellen Sie API-Schlüssel mit klaren Rechten und dokumentieren, welche Integration diese Schlüssel verwendet.

Interne Integrationspfade sind nicht als stabile Schnittstelle für Kundensysteme gedacht. Sie erklären aber, warum eine sichtbare Funktion mehrere Voraussetzungen hat. Ein Beispiel: Eine per Microsoft versendete Rechnung kann gleichzeitig E-Mail-Vorlage, PDF-Rendering, Datei-Anhang, Microsoft-Token und Postausgang betreffen.

Für externe Projekte sollten technische Ansprechpersonen daher immer zuerst prüfen: Gibt es eine dokumentierte API-Funktion? Gibt es eine bestehende edoobox Integration? Oder handelt es sich um eine interne Funktion, die nicht direkt angesprochen werden darf?

Eigene Angebotsdaten und Ereignisempfänger verbinden

Eine API-Angebotswebsite liest offer-Daten, getrennte text-Ressourcen und die von edoobox bereitgestellten Share-Links. Ein eigener Cache gehört zur Website-Integration; er ist keine Platzreservierung. Der Ablauf Eigene Angebotswebsite und Kursplaner beschreibt vollständige Listen, Sprachfassungen und veraltete Daten.

Für Bilder verwenden Sie die tatsächlich zurückgegebenen image.url- und image.url300-Werte. Vorschaubilder, öffentliche Ausgangsdateien und Social-Media-Ausschnitte werden je nach Bildweg unterschiedlich verarbeitet. Ein selbst ergänztes Grössensuffix ist deshalb kein allgemeiner API-Vertrag. Bild-URLs und Originalproportionen erklärt den belegten Umfang.

Passende Ereignisse können einen gezielten Abruf auslösen. Die Webhook-Anleitung erklärt die Einrichtung über /v2/webhook mit benötigtem Recht, Zieladresse, Topics und HMAC-Prüfung. Zahlungsanbieter-, Scanner- und allgemeine Integrations-Webhooks sind getrennte Verbindungen. Aus der Einrichtung folgt keine zugesicherte Zustellung jedes fachlichen Statuswechsels.

Einrichtung und Tests sauber trennen

Testen Sie Integrationen nicht direkt mit produktiven Massenaktionen. Verwenden Sie ein Testangebot, eine Testbuchung, eine Testrechnung oder eine kleine Auswahl an Datensätzen. So erkennen Sie Fehler, ohne viele Teilnehmende, Rechnungen oder E-Mails zu beeinflussen.

Für Microsoft testen Sie zuerst Authentifizierung und eine einzelne E-Mail. Für PDF prüfen Sie eine Vorlage mit echten Demo-Daten. Für Dinaco testen Sie eine Event-Verbindung und ein Ticket. Für SAML testen Sie eine einzelne Admin-Person mit definierten Attributen.

Betriebsregeln, Fehlerbilder und Caches

Integrationen arbeiten mit verschiedenen Caches und Wiederholregeln. Dinaco-Token, PDF-Templates, Hilfsabfragen, Briefversand-Tokens oder externe OAuth-Tokens werden nicht bei jedem Klick neu geholt. Dadurch kann eine Änderung kurz verzögert sichtbar werden.

Fehler werden je nach Integration unterschiedlich sichtbar: Dinaco meldet Synchronisationsfehler, Microsoft Graph liefert HTTP- und JSON-Fehler, PDF-Rendering kann an Bildern oder Templates scheitern, Briefversand kann externe Statusmeldungen liefern, SAML kann an Attributen oder Metadaten hängen.

Bei der Fehlersuche immer den konkreten Pfad nennen: Mailversand, PDF-Rendering, Briefversand, Dateispeicher, SAML-Login, API-Zugriff, Hilfsabfrage oder Dinaco-Ticketing. Je genauer der Pfad, desto schneller kann Support oder Technik die richtigen Logs und Statusmeldungen prüfen.

Prüfliste vor der Einrichtung

Welche fachliche Funktion soll verbunden werden?
Welche Rechte, Schlüssel, Provider oder Konten werden benötigt?
Sind Vorlagen, Platzhalter und Sprachen vollständig gepflegt?
Wer ist für externe Systeme wie Microsoft, Dinaco, SAML-IdP oder Briefversand zuständig?
Wie wird getestet: Demo-Angebot, Testbuchung, Testmail, Testticket oder Testrechnung?
Welche Logs, Belege oder Statusmeldungen braucht der Support bei Fehlern?

Serverseitiges Tracking V2

Die neue Tracking-V2-Integration verwaltet Google Analytics, Microsoft Ads und ChatGPT / OpenAI Ads je Konto. Sie ergänzt Browserereignisse um den serverseitigen Versand von Käufen, Zahlungen und Rückabwicklung. Für eine Einbettung sind der aktuelle Website-Kontext und die Einwilligung erforderlich; siehe iFrame und Einwilligung.