Schnittstelle: Veranstaltungen lesen, Anmeldungen anlegen

So finden Sie esOrganisation → Schnittstelle

Die Schnittstelle (REST, JSON) liest Ihre Veranstaltungen, Teilnehmenden und den Meldestatus und legt auf Wunsch Anmeldungen an. So füllen Sie Ihre Website mit aktuellen Terminen oder übernehmen Anmeldungen aus Ihrem eigenen Formular. Die vollständige Beschreibung im Format OpenAPI 3 finden Sie unter `/api/v1/openapi.json`.

Bild in voller Größe öffnen

Schlüssel erstellen#

1. 1

   Schnittstelle einschalten

   Die Schnittstelle gehört zu Ihrem Veranstalter und ist zunächst ausgeschaltet. Schalten Sie sie unter Organisation → Schnittstelle ein.

2. 2

   Schlüssel anlegen

   Vergeben Sie eine Bezeichnung, wählen Sie die Rechte, die Gültigkeit und das Limit pro Minute. Der Schlüssel erscheint genau einmal, kopieren Sie ihn sofort. MeduCert speichert nur einen Fingerabdruck und den Anfang zur Wiedererkennung.

3. 3

   Widerrufen, wenn nötig

   Mit Widerrufen gilt ein Schlüssel sofort nicht mehr. Die Tabelle zeigt, wann er zuletzt genutzt wurde. Das Protokoll hält fest, wer einen Schlüssel erstellt oder widerrufen hat.

Rechte#

Das Geburtsdatum gibt die Schnittstelle nie aus. Geben Sie jedem Schlüssel nur die Rechte, die er braucht.

Endpunkte#

Basisadresse: `https://meducert.de/api/v1`. Jeder Aufruf trägt den Schlüssel im Header `Authorization: Bearer <Schlüssel>`.

Beispiel mit curl#

export MEDUCERT_KEY="mck_…"   # Ihr Schlüssel

# Offene Veranstaltungen
curl -H "Authorization: Bearer $MEDUCERT_KEY" \
  "https://meducert.de/api/v1/termine/?status=offen"

# Eine Anmeldung anlegen (mit Idempotency-Key gegen Doppelungen)
curl -X POST "https://meducert.de/api/v1/termine/12/anmeldungen/" \
  -H "Authorization: Bearer $MEDUCERT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: anmeldung-2026-0815" \
  -d '{"anrede":"frau","titel":"Dr. med.","vorname":"Maria","name":"Muster","email":"[email protected]",
       "efn":"802760699999990","art":"online","geburtsdatum":"1985-03-04"}'

Beispiel mit Python#

import requests

BASIS = "https://meducert.de/api/v1"
KOPF = {"Authorization": "Bearer mck_…"}

# Alle offenen Veranstaltungen, Seite für Seite
seite = 1
while seite:
    r = requests.get(f"{BASIS}/termine/", headers=KOPF,
                     params={"status": "offen", "seite": seite}, timeout=10)
    r.raise_for_status()
    antwort = r.json()
    for t in antwort["daten"]:
        print(t["beginn"], t["titel"], t["plaetze"])
    seite = antwort["naechste_seite"]

# Anmeldung anlegen
r = requests.post(
    f"{BASIS}/termine/12/anmeldungen/",
    headers={**KOPF, "Idempotency-Key": "anmeldung-2026-0815"},
    json={"anrede": "frau", "titel": "Dr. med.", "vorname": "Maria", "name": "Muster", "email": "[email protected]",
          "efn": "802760699999990", "art": "online", "geburtsdatum": "1985-03-04"},
    timeout=10,
)
print(r.status_code, r.json())

Anmeldungen anlegen#

Die Schnittstelle prüft wie das Anmeldeformular: EFN, Pflichtangaben, Plätze und Warteliste. Die Person erhält ihre Bestätigung per E-Mail. Die Antwort nennt `status` (`angemeldet` oder `warteliste`) und, bei der Warteliste, die Position. Ist die Person bereits angemeldet, antwortet die Schnittstelle mit 200 und `bereits_vorhanden: true`, ohne eine zweite E-Mail.

`anrede` (`frau`, `herr` oder `keine`) und `titel` (zum Beispiel `Dr. med.`, bis 60 Zeichen) sind optional. Ohne Angabe bleiben gespeicherte Werte der Person erhalten. Die Liste der Teilnehmenden liefert beide Felder mit.

Senden Sie bei jedem Anlegen einen `Idempotency-Key` (bis 64 Zeichen). Wiederholen Sie einen Aufruf mit demselben Schlüssel, zum Beispiel nach einem Verbindungsabbruch, erhalten Sie dieselbe Antwort und es entsteht keine zweite Anmeldung.

Antworten, Fehler und Limits#

• Listen sind seitenweise: `seite` und `pro_seite` (bis 100). Die Antwort enthält `gesamt` und `naechste_seite`.
• Fehler haben immer die Form `{"fehler": {"code": "…", "meldung": "…"}}` mit dem passenden HTTP-Status, zum Beispiel 401 (Schlüssel), 403 (Recht), 404, 422 (Angaben) und 429 (Limit).
• Das Limit pro Minute stellen Sie je Schlüssel ein. Die Header `X-RateLimit-Remaining` und `Retry-After` zeigen den Stand.
• Ein Schlüssel sieht nur die Daten seines Veranstalters.

Weiterlesen#

• Webhooks: Ereignisse automatisch erhalten

  MeduCert ruft Ihre Adresse auf, sobald sich etwas ändert: signiert, mit Wiederholungen und Zustellprotokoll.

  →

• Anmeldung auf Ihrer Website einbetten

  Zeigen Sie das Anmeldeformular direkt auf Ihrer Website: mit Code zum Kopieren, Vorschau und automatischer Höhe.

  →

• Rückmeldungen des EIV im Klartext

  Die Spalte „Rückmeldung des EIV“ übersetzt die Antwort des EIV in verständliche Worte und sagt Ihnen, ob Sie etwas tun müssen.

  →