Aufruf per API – Patienten aus jeder Software aufrufen

Die API von Wartezimmer-Aufruf besteht im Kern aus einem einzigen Aufruf. Alles, was eine Software können muss, ist eine HTTPS-Anfrage senden – das können tomedo (per Aktionskette), Windows-Skripte, Praxisverwaltungssysteme mit „externem Programm“ und jede Programmiersprache.

Die API ist in den Tarifen mit API-Zugriff enthalten (siehe Preise). Ohne freigeschaltete API antwortet der Server mit 403 und "reason":"feature_api_disabled".

Überblick


Endpunkt	`POST https://wartezimmer-aufruf.de/api/waitingrooms/{wartezimmer-id}/invocations`
Authentifizierung	HTTP-Header `Authorization: Bearer IHR-API-TOKEN`
Body (JSON)	`name` (Pflicht) – Name oder Wartenummer, max. 255 Zeichen `room` (Pflicht) – Zimmer, max. 255 Zeichen
Header	`Accept: application/json` und `Content-Type: application/json`
Antwort bei Erfolg	`201 Created` – `{"ok":true}`
Wartezimmer auflisten	`GET https://wartezimmer-aufruf.de/api/waitingrooms` – liefert alle Standorte und Wartezimmer mit ihren IDs

Die Wartezimmer-ID finden Sie im Wartezimmer-Editor im Kasten Aufruf aus der Praxissoftware (API). Sie ist eine lange Zeichenkette wie 9d2f7c1e-3b4a-4f6e-8a9b-1c2d3e4f5a6b. Alternativ liefert GET /api/waitingrooms alle IDs.

Eine interaktive Referenz (OpenAPI/Swagger) finden Sie unter https://wartezimmer-aufruf.de/api-docs.

Schritt 1: API-Token erstellen

Oben rechts auf Ihren Namen klicken → API Tokens.
Namen vergeben, z. B. „tomedo Anmeldung“ oder „PC Zimmer 3“ → Create.
Den angezeigten Token sofort kopieren – er wird nur einmal angezeigt.

Empfehlung: Erstellen Sie pro Arbeitsplatz oder Zweck einen eigenen Token. Geht ein Gerät verloren, löschen Sie nur diesen Token, alle anderen funktionieren weiter.

Der Token gehört zu Ihrem Benutzerkonto und darf alle Wartezimmer der Teams aufrufen, in denen Sie Mitglied sind.

Schritt 2: Testen mit curl

Auf macOS und Linux ist curl vorinstalliert, unter Windows 10/11 ebenfalls (Eingabeaufforderung):

curl -X POST "https://wartezimmer-aufruf.de/api/waitingrooms/WARTEZIMMER-ID/invocations" \
  -H "Authorization: Bearer IHR-API-TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"Wartenummer 42","room":"3"}'

Antwort:

{"ok":true}

Innerhalb von ein bis zwei Sekunden erscheint der Aufruf auf dem Fernseher und die Ansage läuft.

Was wird angesagt?

Aus name und room wird automatisch ein Ansagetext erzeugt:

Eingabe `name`	Eingabe `room`	Ansage
`42`	`3`	„Wartenummer 42, gehen Sie in das Zimmer 3 bitte.“
`1234`	`3`	„Wartenummer 1-2-3-4, gehen Sie in das Zimmer 3 bitte.“ (einzeln gesprochen)
`Frau Müller`	`12`	„Frau Müller, gehen Sie in das Zimmer 12 bitte.“
`Herr Schmidt`	`MRT`	„Herr Schmidt, bitte kommen Sie zum MRT.“
`Herr Schmidt`	`Labor`	„Herr Schmidt, bitte kommen Sie zur Labor.“

Faustregel: Reine Zahlen in name werden als Wartenummer angesagt. Kurze Zimmerangaben (bis 3 Zeichen, z. B. „3“, „12“, „A1“) klingen am natürlichsten. Auf dem Bildschirm erscheint immer genau der Text, den Sie gesendet haben. Stimme, Anbieter und Sprechgeschwindigkeit stellen Sie pro Wartezimmer im Editor ein.

Fehler und Bedeutung

HTTP-Status	Bedeutung	Lösung
`401 Unauthenticated`	Token fehlt oder ist falsch	Header prüfen, ggf. neuen Token erstellen
`403`	Sie sind nicht Mitglied des Teams, zu dem das Wartezimmer gehört – oder die API ist in Ihrem Tarif nicht enthalten (`feature_api_disabled`)	Richtige Wartezimmer-ID verwenden bzw. Tarif mit API wählen
`404`	Wartezimmer-ID unbekannt	ID aus dem Editor oder `GET /api/waitingrooms` kopieren
`409`	Der Standort des Wartezimmers ist deaktiviert (`location_disabled`)	Standort unter Standorte aktivieren
`422`	`name` oder `room` fehlt oder ist zu lang	Beide Felder als JSON mitsenden
`429`	Zu viele Anfragen in kurzer Zeit	Kurz warten

Senden Sie immer den Header Accept: application/json, damit Fehler als JSON statt als HTML-Seite zurückkommen.

Beispiele

Windows PowerShell

$token = "IHR-API-TOKEN"
$room  = "WARTEZIMMER-ID"
Invoke-RestMethod -Method Post -Uri "https://wartezimmer-aufruf.de/api/waitingrooms/$room/invocations" `
  -Headers @{ Authorization = "Bearer $token"; Accept = "application/json" } `
  -ContentType "application/json" `
  -Body (@{ name = "Wartenummer 42"; room = "3" } | ConvertTo-Json)

Als Skript aufruf.ps1 mit Parametern, das die Praxissoftware aufrufen kann:

param([string]$Name, [string]$Zimmer)
$token = "IHR-API-TOKEN"
$room  = "WARTEZIMMER-ID"
Invoke-RestMethod -Method Post -Uri "https://wartezimmer-aufruf.de/api/waitingrooms/$room/invocations" `
  -Headers @{ Authorization = "Bearer $token"; Accept = "application/json" } `
  -ContentType "application/json" `
  -Body (@{ name = $Name; room = $Zimmer } | ConvertTo-Json) | Out-Null

Aufruf: powershell -ExecutionPolicy Bypass -File C:\Praxis\aufruf.ps1 -Name "Frau Müller" -Zimmer 3

Windows Batch (curl)

@echo off
curl -s -X POST "https://wartezimmer-aufruf.de/api/waitingrooms/WARTEZIMMER-ID/invocations" ^
  -H "Authorization: Bearer IHR-API-TOKEN" -H "Accept: application/json" ^
  -H "Content-Type: application/json" ^
  -d "{\"name\":\"%~1\",\"room\":\"%~2\"}"

Aufruf: aufruf.bat "Wartenummer 42" 3

macOS / AppleScript (z. B. für tomedo)

do shell script "curl -s -X POST 'https://wartezimmer-aufruf.de/api/waitingrooms/WARTEZIMMER-ID/invocations' -H 'Authorization: Bearer IHR-API-TOKEN' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{\"name\":\"Wartenummer 42\",\"room\":\"3\"}'"

Die vollständige tomedo-Anleitung mit Platzhaltern finden Sie unter tomedo-Integration.

Python

import requests

requests.post(
    "https://wartezimmer-aufruf.de/api/waitingrooms/WARTEZIMMER-ID/invocations",
    headers={"Authorization": "Bearer IHR-API-TOKEN", "Accept": "application/json"},
    json={"name": "Wartenummer 42", "room": "3"},
    timeout=5,
).raise_for_status()

PHP

$ch = curl_init('https://wartezimmer-aufruf.de/api/waitingrooms/WARTEZIMMER-ID/invocations');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer IHR-API-TOKEN',
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['name' => 'Wartenummer 42', 'room' => '3']),
]);
echo curl_exec($ch);

Wartezimmer-IDs abfragen

curl "https://wartezimmer-aufruf.de/api/waitingrooms" \
  -H "Authorization: Bearer IHR-API-TOKEN" -H "Accept: application/json"

Die Antwort listet alle Standorte mit ihren Wartezimmern (uuid, name, is_active).

Sicherheit

Der Token ist wie ein Passwort. Legen Sie ihn nicht in E-Mails, Chats oder Screenshots ab.
Speichern Sie ihn auf Arbeitsplatz-PCs in einer Datei, die nur der Praxisbenutzer lesen kann.
Löschen Sie nicht mehr benötigte Tokens unter API Tokens.
Alle Anfragen laufen verschlüsselt über HTTPS.

Überblick#

Schritt 1: API-Token erstellen#

Schritt 2: Testen mit curl#

Was wird angesagt?#

Fehler und Bedeutung#

Beispiele#

Windows PowerShell#

Windows Batch (curl)#

macOS / AppleScript (z. B. für tomedo)#

Python#

PHP#

Wartezimmer-IDs abfragen#

Sicherheit#