Die REST-API ist der direkte Weg aus dem eigenen System. Ein Request fügt bis zu 100 Personen zu einer Vorlage hinzu und versendet auf Wunsch gleich die E-Mails. Die vollständige Dokumentation steht unter docs.virtualbadge.io.
Schritt 1: API-Token erzeugen
Öffnen Sie „Einstellungen“ und „Integrationen“. Unter „API Zugriff“ erzeugen Sie mit „Token generieren“ einen Token. Darunter stehen die URL für Anfragen und der geheime Zugriffs-Token.
Behandeln Sie den Token wie ein Passwort und legen Sie ihn nicht im Frontend-Code ab.
Schritt 2: Beispiel zur Vorlage öffnen
Öffnen Sie in der Vorlage „Teilnehmer“, klicken Sie auf „Teilnehmer hinzufügen“ und wählen Sie „Per API hinzufügen“. Der Dialog „API Integration“ zeigt in drei Schritten ein fertiges Beispiel für genau diese Vorlage, wahlweise als cURL, JavaScript oder Python.
Schritt 3: Teilnehmer per Request hinzufügen
Senden Sie einen POST-Request an /v2/public/recipient/. Der Token steht im Header „Authorization“ als Bearer-Token. Im Body nennen Sie die Vorlage im Feld certificate und die Personen im Feld recipients. Pflicht sind je Person email und full_name.
Mit send_emails legen Sie fest, ob die E-Mails sofort verschickt werden, mit add_duplicates, ob doppelte E-Mail-Adressen erlaubt sind. Ein Request nimmt bis zu 100 Personen auf.
curl -X POST "https://api.virtualbadge.io/v2/public/recipient/" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "certificate": "cert_8Kq2mXv4TzR1pLw9", "send_emails": true, "add_duplicates": true, "recipients": [ { "email": "lena.hoffmann@example.org", "full_name": "Lena Hoffmann" } ] }'
| Feld | Bedeutung |
|---|---|
| certificate | ID der Vorlage |
| recipients | Liste der Personen, bis zu 100 je Request |
| E-Mail-Adresse der Person, Pflichtfeld | |
| full_name | Name der Person, Pflichtfeld |
| send_emails | true versendet die E-Mails sofort |
| add_duplicates | true erlaubt doppelte E-Mail-Adressen |
Schritt 4: Antwort verarbeiten
Bei Erfolg antwortet die API mit dem Status 201 und den erstellten Teilnehmer-Objekten. Jede Person erhält eine eindeutige id und eine access_page_url, die Adresse ihrer Teilnehmeransicht. Speichern Sie beide Werte in Ihrem System.
Schritt 5: Ereignisse per Webhook empfangen
Webhooks melden Ihrem System, wenn etwas passiert ist, zum Beispiel wenn ein Nachweis erzeugt oder der Zugriff eines Teilnehmers widerrufen wurde. Die Tabelle nennt die Ereignisse. Einrichtung und Felder beschreibt die API-Dokumentation.
| Ereignis | Wann es ausgelöst wird |
|---|---|
| Certificate/Badge Generated | Ein Nachweis wurde erzeugt |
| Credential Email Sent | Die E-Mail mit dem Nachweis wurde gesendet |
| Recipient Access Revoked | Der Zugriff eines Teilnehmers wurde widerrufen |
| Training Completed | Ein Training wurde abgeschlossen, von Hand oder automatisch |
Schritt 6: In der Sandbox testen und umstellen
Testen Sie zuerst in einer Sandbox-Organisation. Nachweise von dort sind als Test gekennzeichnet. Ist alles richtig, übernehmen Sie die Vorlage in der Übersicht über „Zur Produktiv-Organisation migrieren“. Dabei entsteht dort eine Kopie mit Grundlegenden Details, Design und Teilnehmererlebnis. Prüfen Sie danach Token und Vorlagen-ID in Ihrem System, denn die Kopie ist eine eigene Vorlage.
Gehen Sie diese Anleitung mit Ihren eigenen Daten durch.
Ergebnis prüfen
- Ein Test-Request liefert den Status 201.
- Die Person erscheint in der Teilnehmerliste der Vorlage.
- Ihr System hat id und access_page_url gespeichert.
Mehr dazu: API-DokumentationIntegrationen
Häufige Fragen
Wie viele Personen passen in einen Request?
Bis zu 100 Personen.
Wo finde ich die ID der Vorlage?
Im Dialog „API Integration“ ist sie im Beispiel schon eingetragen. Sie steht auch unten in der Übersicht der Vorlage.
Wo steht die vollständige Dokumentation?
Unter docs.virtualbadge.io. Der Dialog führt über „Zur Doku“ direkt dorthin.
Geht das auch ohne eigene Entwicklung?
Ja, über Zapier. Dort brauchen Sie keinen API-Token. Für Moodle gibt es ein eigenes Plugin.