Scheduling

Die Scheduling API ermöglicht patientenseitige Selbstbuchung für Videosprechstunden. Öffentliche Discovery-Endpunkte können mit einer shop_uid aufgerufen werden. Buchungs- und Umbuchungsvorgänge nutzen entweder einen Organisations-API-Key oder einen kurzlebigen Patient Booking Token.

Übermitteln Sie signierte Patient Booking Tokens niemals in URLs. Tauschen Sie das Token gegen einen booking_launch_code ein und verwenden Sie diesen Code für gehostete Buchungslinks oder eingebettete Widgets.

Authentifizierung

Die Scheduling API akzeptiert zwei Credentials. Die meisten Endpunkte akzeptieren beides; einige sind auf eines beschränkt.

Patient Booking Tokens (empfohlen für Patientenflüsse)

Ein kurzlebiges JWT, das Ihr Partner-Backend für einen bestimmten Patienten ausstellt. Übergeben Sie es im Header X-RxScale-Booking-Token. Das Token wird gegen ein in RxScale hinterlegtes Organisations-Booking-Token-Secret verifiziert. Algorithmus: HS256 JOSE-Header: muss kid enthalten — die key_id, die beim Provisionieren des Secrets zurückgegeben wurde. Erforderliche Claims:

Claim	Typ	Beschreibung
`aud`	string	Muss `rxscale-scheduling` sein.
`exp`	int	Ablauf (Unix-Sekunden). Kurz halten — unter 5 Minuten ist üblich.
`nbf`	int	Not-before (Unix-Sekunden).
`iat`	int	Issued-at (Unix-Sekunden).
`shop_identifier`	string	Der in RxScale konfigurierte Shop-Identifier.
`shop_customer_id`	string	Ihre stabile Kunden-ID. RxScale dedupliziert Patienten anhand dieser ID.
`patient_profile_fields`	array	Profilfelder, die übernommen werden sollen. Jeder Eintrag: `{ "field": "<field_key>", "value": <wert>, "source": "shop" }`.

import jwt, time
now = int(time.time())
payload = {
    "aud": "rxscale-scheduling",
    "exp": now + 300,
    "nbf": now - 10,
    "iat": now,
    "shop_identifier": "shop_abc",
    "shop_customer_id": "cust_123",
    "patient_profile_fields": [
        {"field": "first_name", "value": "Ada", "source": "shop"},
        {"field": "last_name",  "value": "Lovelace", "source": "shop"},
        {"field": "email",      "value": "ada@example.com", "source": "shop"},
    ],
}
token = jwt.encode(payload, SECRET, algorithm="HS256", headers={"kid": KEY_ID})

Booking-Token-Secrets werden in der RxScale-Datenbank verschlüsselt gespeichert. Nur Ihre key_id liegt im Klartext für das Routing vor; der Secret-Wert wird sowohl bei der Token-Verifikation als auch beim Abruf durch einen Admin (Admin-Portal oder Secrets-API) im Speicher entschlüsselt. Rotieren Sie, indem Sie ein neues Secret provisionieren und das alte widerrufen, sobald Ihr Minter umgestellt ist.

Organisations-API-Key

Senden Sie X-API-Key: <key> statt des Booking Tokens für Server-zu-Server-Flüsse. Der Key benötigt die Berechtigung scheduling:write. Nutzen Sie das für Back-Office-Tools, skriptgesteuertes Umbuchen oder Operations-Skripte.

Terminarten auflisten

GET /v1/scheduling/appointment-types?shop_uid={shop_uid}

string

erforderlich

Shop-UID, mit der die Terminarten auf die richtige Organisation eingeschränkt werden.

Kein API-Key erforderlich.

curl "https://api.rxscale.com/v1/scheduling/appointment-types?shop_uid=shop_123"

{
  "data": [
    {
      "uid": "apt_video_15",
      "name": "Videosprechstunde",
      "duration_minutes": 15
    }
  ]
}

Die Antwort enthält bewusst kein hold_ttl_seconds, max_bookings_per_slot und keine weiteren Terminierungs- oder Preisfelder der Terminart — dieser Endpunkt ist unauthentifiziert, und genau diese Felder wären die Stellschrauben für eine Angreifer-Kampagne, die Slots blockiert. Falls Ihre Integration diese Felder benötigt, verwenden Sie stattdessen GET /v1/management/scheduling/appointment-types mit einem Organisations-API-Key (siehe die Management-API-Dokumentation).

Slots suchen

POST /v1/scheduling/slots/search

Kein API-Key erforderlich. Die Slot-Suche liefert nur Slots zurück, die den wirksamen Buchungsvorlauf der Terminart erfüllen. Wenn ein Arzt für diese Terminart eine eigene Einstellung hat, geht dieser Wert vor, auch 0 Minuten. Terminarten mit selected_doctors_only liefern nur Ärzte mit aktiver arztspezifischer Einstellung zurück.

string

erforderlich

string

erforderlich

int

erforderlich

Fensterstart (Unix-Sekunden).

int

erforderlich

Fensterende (Unix-Sekunden). Max. 31 Tage ab from.

string

Auf einen Arzt einschränken.

string

IANA-Zeitzone (z. B. Europe/Berlin) zur Lokalisierung der Ausgabe. Standard ist Europe/Berlin. Jeder Slot enthält start_local/end_local in dieser Zone; start_date/end_date bleiben Unix-Sekunden.

curl -X POST "https://api.rxscale.com/v1/scheduling/slots/search" \
  -H "Content-Type: application/json" \
  -d '{
    "shop_uid": "shop_123",
    "appointment_type_uid": "apt_video_15",
    "from": 1778457600,
    "to": 1778544000
  }'

{
  "slots": [
    {
      "doctor_uid": "doc_123",
      "doctor_name": "Dr. Max Meyer",
      "start_date": 1778490000,
      "end_date": 1778490900,
      "timezone": "Europe/Berlin",
      "start_local": "2026-05-11T11:00:00+02:00",
      "end_local": "2026-05-11T11:15:00+02:00"
    }
  ]
}

Booking Session erstellen

Verwenden Sie diesen Endpunkt beim Start der gehosteten UI oder des Widget-Skripts. Die Anfrage kann das signierte Patient Booking Token entweder in X-RxScale-Booking-Token oder im JSON-Body als booking_token enthalten.

POST /v1/scheduling/booking-sessions

string

erforderlich

booking für einen neuen Termin, rebooking für eine bestehende Buchung.

string

Pflicht im booking-Modus.

int

Fensterstart (Unix-Sekunden). Pflicht im booking-Modus.

int

Fensterende (Unix-Sekunden). Pflicht im booking-Modus.

string

URL, zu der der Patient nach erfolgreicher Buchung weitergeleitet wird.

string

Patient Booking JWT, falls nicht im Header übergeben.

curl -X POST "https://api.rxscale.com/v1/scheduling/booking-sessions" \
  -H "Content-Type: application/json" \
  -H "X-RxScale-Booking-Token: eyJ..." \
  -d '{
    "mode": "booking",
    "appointment_type_uid": "apt_video_15",
    "from": 1778457600,
    "to": 1778544000,
    "return_url": "https://partner.example/booking-complete"
  }'

{
  "booking_launch_code": "blc_Nc8...",
  "expires_at": 1778458500,
  "launch_url": "https://meet.rxscale.com/booking?launch=blc_Nc8..."
}

Booking Session abrufen

Die gehostete UI ruft diesen Endpunkt nur mit dem Launch-Code auf, um den Buchungskontext zu laden. Kein Auth-Header nötig — der Launch-Code selbst ist das Credential.

GET /v1/scheduling/booking-sessions/{booking_launch_code}

curl "https://api.rxscale.com/v1/scheduling/booking-sessions/blc_Nc8..."

{
  "uid": "bsn_abc...",
  "shop_uid": "shop_123",
  "appointment_type_uid": "apt_video_15",
  "appointment_type": {
    "uid": "apt_video_15",
    "name": "Videosprechstunde",
    "duration_minutes": 15
  },
  "start_from": 1778457600,
  "start_to": 1778544000,
  "mode": "booking",
  "return_url": "https://partner.example/booking-complete",
  "expires_at": 1778458500,
  "billing": {
    "lines": [
      {
        "description": "Videosprechstunde",
        "quantity": 1,
        "unit_amount": 4900,
        "vat_rate_bp": null
      }
    ],
    "total": 4900,
    "currency": "EUR",
    "payment_required": true,
    "test_mode": false
  }
}

Die Antwort enthält bewusst kein patient_profile_uid und keine weiteren Patienten-Identifier, damit der Launch-Code gefahrlos durch die URL im Browser des Patienten geführt werden kann.

Abrechnung

billing ist immer vorhanden und beschreibt, was die Booking Session kostet.

lines — die berechneten Positionen in Anzeigereihenfolge. unit_amount ist in der kleinsten Einheit der Währung angegeben (Cent), vat_rate_bp ist ein Mehrwertsteuersatz in Basispunkten (1900 = 19 %). null bedeutet, dass keine Umsatzsteuer anfällt — das ist etwas anderes als ein echter Satz von 0 %.
total — die Summe aus quantity × unit_amount über alle Positionen, in derselben Einheit.
currency — der ISO-4217-Code, in dem alle Positionen berechnet sind. Der Wert ist nur dann null, wenn es überhaupt keine Währung zu melden gibt: bei einer Session ohne Positionen und ohne Terminart. Eine Session mit Positionen hat immer eine Währung — behandeln Sie null also als „nichts zu berechnen“ und nicht als Standardwert.
payment_required — false, wenn es keine Positionen gibt. Verzweigen Sie über dieses eine Flag: Eine Session mit payment_required: false wird genau wie bisher gebucht, ohne Zahlungsschritt. Sessions sind ohne Preis, sofern der Buchungslink nicht mit Preisen erzeugt wurde.
test_mode — true, wenn die Zahlung dieser Buchung im Testmodus des Zahlungsanbieters läuft: Die Bezahlseite verhält sich wie im Echtbetrieb, der Patientin oder dem Patienten wird jedoch nichts berechnet und es erreicht kein Betrag die Organisation. Weisen Sie darauf hin — die gehostete Buchungs-UI von RxScale zeigt im Zahlungsschritt einen entsprechenden Hinweis. Der Wert ist immer false, wenn payment_required false ist: Ein Link ohne Preis zieht überhaupt keine Zahlung ein und hat damit auch keinen Modus. Ältere Stände dieser API liefern das Feld gar nicht — behandeln Sie ein fehlendes test_mode als false. Der Wert wird bei jeder Anfrage neu aus der Terminart abgeleitet und beschreibt damit die Zahlung, die entstehen wird — sobald eine Zahlung existiert, lesen Sie stattdessen testmode an der Zahlung.

Die Preise werden bei der Erzeugung des Buchungslinks festgeschrieben und ändern sich danach nicht mehr — was Sie hier anzeigen, ist genau das, was der Patient zahlen soll. Den Testmodus schaltet die Organisation pro Terminart im RxScale-Adminportal ein. Ein Buchungslink ist deshalb entweder vollständig ein Testlauf oder vollständig echt — nie beides. Eine Session für eine Terminart im Testmodus meldet das so:

curl "https://api.rxscale.com/v1/scheduling/booking-sessions/blc_Tm4..."

{
  "uid": "bsn_def...",
  "shop_uid": "shop_123",
  "appointment_type_uid": "apt_video_15",
  "appointment_type": {
    "uid": "apt_video_15",
    "name": "Videosprechstunde",
    "duration_minutes": 15
  },
  "start_from": 1778457600,
  "start_to": 1778544000,
  "mode": "booking",
  "return_url": "https://partner.example/booking-complete",
  "expires_at": 1778458500,
  "billing": {
    "lines": [
      {
        "description": "Videosprechstunde",
        "quantity": 1,
        "unit_amount": 4900,
        "vat_rate_bp": null
      }
    ],
    "total": 4900,
    "currency": "EUR",
    "payment_required": true,
    "test_mode": true
  }
}

Sonst ändert sich an der Session nichts: Preis, Währung und der gesamte Buchungsablauf sind dieselben wie bei einer echten Zahlung. Nur das Geld ist nicht echt.

Holds erstellen und bestätigen

Authentifizierte Integrationen können Holds mit einem API-Key mit scheduling:write anlegen. Gehostete-UI-Integrationen nutzen die booking_launch_code-Routen.

POST /v1/scheduling/booking-sessions/{booking_launch_code}/holds

string

erforderlich

string

erforderlich

int

erforderlich

Unix-Sekunden.

string

Optionaler Grund für den Termin, bis zu 2000 Zeichen. Leere Werte werden als null gespeichert. Stammt die Sitzung aus einem öffentlichen Buchungslink — dem nicht authentifizierten, per Magic-Link verifizierten Buchungsablauf —, gilt stattdessen eine Grenze von 500 Zeichen; enthält der Wert eine URL — auch eine mit unsichtbaren oder Vollbreitenzeichen getarnte — oder Steuer-, Formatierungs- bzw. Schreibrichtungszeichen, wird die Anfrage mit 400 abgelehnt.

string

Optional. Derselbe Key mit identischem Body liefert den bestehenden Hold zurück, statt einen neuen anzulegen.

curl -X POST "https://api.rxscale.com/v1/scheduling/booking-sessions/blc_Nc8.../holds" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hold-attempt-1" \
  -d '{
    "doctor_uid": "doc_123",
    "appointment_type_uid": "apt_video_15",
    "start_date": 1778490000,
    "visit_reason": "Medikationsreview vor Dosisanpassung"
  }'

{
  "hold_uid": "pdm_123",
  "expires_at": 1778490900,
  "ttl_seconds": 900,
  "status": "held",
  "visit_reason": "Medikationsreview vor Dosisanpassung"
}

POST /v1/scheduling/booking-sessions/{booking_launch_code}/holds/{hold_uid}/confirm

string

Optionaler Grund für den Termin, bis zu 2000 Zeichen. Wird dieses Feld weggelassen, bleibt der beim Erstellen des Holds gesetzte Wert erhalten; ein leerer Wert löscht ihn. Dieselbe Grenze für öffentliche Buchungslinks gilt auch hier: 500 Zeichen; die Anfrage wird mit 400 abgelehnt, wenn der Wert eine URL — auch eine mit unsichtbaren oder Vollbreitenzeichen getarnte — oder Steuer-, Formatierungs- bzw. Schreibrichtungszeichen enthält.

curl -X POST "https://api.rxscale.com/v1/scheduling/booking-sessions/blc_Nc8.../holds/pdm_123/confirm" \
  -H "Content-Type: application/json" \
  -d '{
    "visit_reason": "Medikationsreview vor Dosisanpassung"
  }'

{
  "uid": "pdm_123",
  "status": "confirmed",
  "start_date": 1778490000,
  "end_date": 1778490900,
  "visit_reason": "Medikationsreview vor Dosisanpassung"
}

Wenn ein Hold abgelaufen ist, der Slot aber noch nicht durch einen anderen Termin belegt wurde, ist die Bestätigung weiterhin möglich und der Termin wechselt in den Status confirmed.

Wenn visit_reason gesetzt ist, ist der Grund für Ärzte/Admins sichtbar und kann in Termin-Erinnerungen per E-Mail/SMS sowie in synchronisierten Kalendereinladungen erscheinen. Er kann beim Erstellen des Holds gesetzt und beim Bestätigen bearbeitet oder gelöscht werden — ein Request-Body ohne visit_reason lässt den vorhandenen Wert unverändert.

Hold bezahlen

Kostenpflichtige Buchungslinks (billing.payment_required: true) erfordern eine Zahlung, bevor der Termin bestätigt wird. Die Patientin oder der Patient wird auf eine gehostete Mollie-Bezahlseite geleitet; RxScale bestätigt den Termin selbst, sobald das Geld tatsächlich eingegangen ist. Auf diesem Weg gibt es keinen Bestätigungsaufruf — rufen Sie den Confirm-Endpunkt für eine kostenpflichtige Session nicht auf. Zahlungen werden über das eigene verbundene Mollie-Konto der Organisation eingezogen. Die Organisation verbindet es einmalig im RxScale-Adminportal.

Testzahlungen. Ist billing.test_mode true, wird die Zahlung im Testmodus des Zahlungsanbieters erstellt: Die Bezahlseite sieht aus und verhält sich genau wie im Echtbetrieb, es wird jedoch nichts berechnet, nichts an die Organisation ausgezahlt und es gibt nichts abzustimmen. Alles Weitere auf dieser Seite — die Statuswerte, das Abfragen des Zahlungsstatus, der Callback, das Erstattungsverhalten — funktioniert identisch; genau das macht einen Testlauf aussagekräftig. Die RxScale-Plattformgebühr wird auf der Zahlung weiterhin ausgewiesen, tatsächlich einbehalten wird sie aber nicht, weil kein Geld geflossen ist. Siehe Bezahlte Buchungen vor dem Go-live durchspielen.

Zahlung starten

POST /v1/scheduling/booking-sessions/{booking_launch_code}/payment

string

erforderlich

UID des für diese Session erstellten Holds.

curl -X POST "https://api.rxscale.com/v1/scheduling/booking-sessions/blc_Nc8.../payment" \
  -H "Content-Type: application/json" \
  -d '{"hold_uid": "pdm_123"}'

{
  "payment_uid": "apy_123",
  "checkout_url": "https://www.mollie.com/checkout/select-method/...",
  "status": "open",
  "amount": 4900,
  "currency": "EUR",
  "testmode": false
}

Leiten Sie die Patientin oder den Patienten auf checkout_url. amount ist in der kleinsten Währungseinheit angegeben — 4900 sind 49,00 €. testmode ist der Modus, in dem diese Zahlung erstellt wurde. Er steht mit dem Anlegen fest und wird nie neu abgeleitet; lesen Sie deshalb auf jedem Bildschirm nach einer Zahlung diesen Wert und nicht billing.test_mode — dieser meldet die aktuelle Einstellung der Terminart und kann sich ändern, während die Patientin oder der Patient noch auf der Bezahlseite ist. API-Versionen vor diesem Feld senden den Schlüssel gar nicht; behandeln Sie ein fehlendes testmode als „keine Angabe“ und greifen Sie auf billing.test_mode zurück, niemals als false. Das Starten einer Zahlung verlängert den Hold, damit er nicht ablaufen kann, während die Bezahlseite geöffnet ist. Ein zweiter Aufruf für denselben Hold liefert dieselbe checkout_url mit 200 statt 201, sodass ein Doppelklick oder der Zurück-Button des Browsers keine zwei bezahlbaren Links für einen Termin erzeugen kann.

Status	Bedeutung
`201`	Zahlung erstellt.
`200`	Für diesen Hold war bereits eine Zahlung offen; dieselbe `checkout_url` wird zurückgegeben.
`400`	`hold_uid` fehlt.
`404`	Unbekannte Booking Session, oder der Hold gehört nicht zu dieser Session bzw. ist nicht mehr im Status `held`.
`409`	Dieser Buchungslink hat keinen Preis, es gibt nichts zu bezahlen — verwenden Sie den Confirm-Endpunkt. Oder dem Termin fehlt die Terminart, sodass er nicht abgeschlossen werden kann.
`422`	Die Organisation kann derzeit keine Zahlungen annehmen. Entweder ist kein Mollie-Konto verbunden, die Verbindung ist nicht im Status „verbunden“ oder sie ist fehlerhaft konfiguriert — und, ausschließlich bei einer Terminart mit echten Zahlungen, das Konto ist von Mollie noch nicht für Zahlungen freigeschaltet. Eine Terminart im Testmodus ist allein von diesem letzten Grund ausgenommen: Ein verbundenes, korrekt konfiguriertes Mollie-Konto braucht auch sie.
`502`	Der Zahlungsanbieter hat die Anfrage abgelehnt oder war nicht erreichbar. Ein erneuter Versuch ist unbedenklich.

Zahlungsstatus abfragen

GET /v1/scheduling/booking-sessions/{booking_launch_code}/payment?hold_uid=pdm_123

curl "https://api.rxscale.com/v1/scheduling/booking-sessions/blc_Nc8.../payment?hold_uid=pdm_123"

{
  "status": "paid",
  "amount": 4900,
  "currency": "EUR",
  "testmode": false,
  "appointment_status": "confirmed",
  "appointment_start": 1778490000,
  "doctor_display_name": "Dr. Test"
}

Fragen Sie diesen Endpunkt ab, nachdem die Patientin oder der Patient von der Bezahlseite zurückkehrt. Er liest die Zahlung bei Bedarf erneut beim Anbieter aus und ist damit nicht davon abhängig, dass Anbieter-Callbacks rechtzeitig eintreffen — die Antwort stimmt auch dann, wenn ein Callback verzögert wird oder verloren geht. Fragen Sie alle paar Sekunden ab; der Endpunkt ist günstig und ruft den Anbieter nur auf, wenn sich der Datensatz überhaupt noch ändern kann. Werten Sie appointment_status aus. Er wird confirmed, sobald das Geld eingegangen ist und der Slot noch verfügbar war. appointment_start (Epoch-Sekunden) und doctor_display_name beschreiben den gebuchten Termin, sodass Sie ohne zweite Anfrage anzeigen können, wofür gerade bezahlt wurde. Beide sind null, solange appointment_status nicht confirmed ist — auch während die Zahlung noch open ist, und im Fall refund_required, in dem kein Termin existiert, der beschrieben werden könnte. doctor_display_name kann außerdem bei einem bestätigten Termin null sein, wenn die Ärztin oder der Arzt die Praxis inzwischen verlassen hat; behandeln Sie den Wert als Best-Effort und verwenden Sie ersatzweise eine allgemeine Bezeichnung.

`status`	Bedeutung
`open`	Noch nicht bezahlt. Die Bezahlseite ist möglicherweise noch geöffnet.
`paid`	Bezahlt. Prüfen Sie `appointment_status` — er lautet dann `confirmed`.
`failed` / `canceled` / `expired`	Nicht bezahlt. Der Hold bleibt unverändert; ein erneuter Versuch ist möglich, solange er gilt.
`refund_required`	Bezahlt, aber der Termin konnte nicht bestätigt werden — der Slot wurde vergeben oder der Termin storniert, während die Zahlung unterwegs war. Es existiert kein Termin. Bitten Sie um eine erneute Buchung; RxScale erstattet die Zahlung.

refund_required ist selten, aber real. Behandeln Sie es als „Zahlung erfolgreich, Buchung nicht“ und niemals als erfolgreiche Buchung.

Callback des Zahlungsanbieters

POST /v1/scheduling/payments/mollie/webhook/{webhook_token}

Dieser Endpunkt existiert für den Zahlungsanbieter, nicht für Partner — es gibt nichts zu integrieren und nichts aufzurufen. Er ist nur dokumentiert, damit die Anfrage in Netzwerk-Logs wiedererkennbar ist. Er ist im üblichen Sinne unauthentifiziert: Der Anbieter signiert nichts. Geschützt wird er durch den webhook_token im Pfad — ein langer Zufallswert, der pro Zahlung erzeugt wird, von keiner API-Antwort zurückgegeben wird und nur RxScale und dem Zahlungsanbieter bekannt ist. Der Anfragetext dient ausschließlich dazu, die betroffene Zahlung zu identifizieren; das tatsächliche Ergebnis wird immer über einen authentifizierten Aufruf beim Anbieter zurückgelesen, sodass eine gefälschte Anfrage nichts als bezahlt markieren kann.

Termin stornieren

Storniert einen bestätigten oder gehaltenen Termin. Akzeptiert entweder ein Booking Token (patientenseitige Stornierung) oder einen Organisations-API-Key (Operations).

POST /v1/scheduling/appointments/{appointment_uid}/cancel

string

Optionaler Freitext-Grund. Wird am Termin für Audit-Zwecke gespeichert.

curl -X POST "https://api.rxscale.com/v1/scheduling/appointments/pdm_123/cancel" \
  -H "X-RxScale-Booking-Token: eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "patient_request"}'

{
  "appointment_uid": "pdm_123",
  "status": "cancelled"
}

Patientenseitige Stornierungen respektieren cancellation_min_notice_minutes der Terminart. Eine Stornierung innerhalb der Frist gibt 400 mit dem betroffenen Feld zurück; buchen Sie den Patienten um oder rufen Sie den Endpunkt mit einem API-Key auf, wenn ein operativer Override nötig ist.

Das Stornieren eines bezahlten Termins erstattet ihn vollständig. Trägt der Termin eine Zahlung mit dem Status paid, partially_refunded oder refund_required, wird beim Stornieren automatisch der gesamte noch erstattbare Betrag zurückgefordert. Beim Umbuchen passiert das nicht — die Patientin oder der Patient behält den bezahlten Termin, nur zu einer neuen Zeit.Die Erstattung ist beim Antworten dieses Endpunkts angefordert, aber noch nicht abgeschlossen: Sie wird kurz darauf an den Zahlungsanbieter übermittelt, und der Erstattungssatz des Termins wechselt von pending zu refunded.Eine vorher vorgenommene Teilerstattung lässt Sie die Differenz nicht einbehalten: Beim Stornieren geht der Restbetrag zurück. Nach einer Teilerstattung von 40,00 € auf eine Zahlung von 49,00 € werden beim Stornieren die restlichen 9,00 € zurückgezahlt, und die zahlende Person hat alle 49,00 € zurückerhalten. Einen Teil der Zahlung über eine Stornierung hinweg einzubehalten, wird nicht unterstützt.Die RxScale-Plattformgebühr wird bei einer Erstattung nicht zurückerstattet. Ihr Mollie-Konto zahlt den vollen Betrag zurück, RxScale behält die Gebühr — eine vollständige Erstattung kostet Sie also genau diese Gebühr.

Termin umbuchen

Verschiebt einen bestehenden Termin auf einen neuen Slot. Der Rebook-Flow legt atomar einen neuen Termin an (mit previous_meeting_uid auf den Originaltermin) und storniert den alten.

POST /v1/scheduling/appointments/{appointment_uid}/rebook

int

erforderlich

Unix-Sekunden für den neuen Slot.

string

Pflicht, wenn die Terminart rebooking_mode: any_doctor setzt. Bei same_doctor_only wird der ursprüngliche Arzt übernommen.

string

Optional. Standard ist die ursprüngliche Terminart.

string

Dringend empfohlen — schützt vor doppelten Umbuchungen bei Retries.

curl -X POST "https://api.rxscale.com/v1/scheduling/appointments/pdm_123/rebook" \
  -H "X-RxScale-Booking-Token: eyJ..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rebook-attempt-1" \
  -d '{"new_start_date": 1778510000}'

{
  "appointment_uid": "pdm_456",
  "status": "confirmed"
}

Umbuchungen werden blockiert, wenn die Terminart allow_patient_rebooking: false setzt, rebooking_min_notice_minutes nicht eingehalten ist oder der neue Slot bereits belegt ist.

Join-Token abrufen

Liefert ein kurzlebiges Jitsi-Waiting-Room-JWT und den Raumnamen. Wird von der Patient-UI verwendet, um den Videocall zu starten.

POST /v1/scheduling/appointments/{appointment_uid}/join

curl -X POST "https://api.rxscale.com/v1/scheduling/appointments/pdm_123/join" \
  -H "X-RxScale-Booking-Token: eyJ..."

{
  "room_name": "doctor-123-room",
  "token": "eyJhbGciOi...",
  "expires_at": 1778497200
}

Patienten-Meeting-Link zusammensetzen

Die Antwort enthält keinen fertigen Link. Ihre Integration muss ihn selbst zusammenbauen:

https://<meetings-app>/meeting/{room_name}?jwt={token}

Optional können Sie einen return_url-Query-Parameter anhängen, um den Patienten nach dem Gesprächsende zurück auf Ihre Plattform weiterzuleiten:

https://<meetings-app>/meeting/{room_name}?jwt={token}&return_url=https%3A%2F%2Fpartner.example%2Fnach-dem-call

string

erforderlich

Der token-Wert aus der Antwort dieses Endpunkts. Von RxScale signiert; nicht verändern.

string

URL, zu der der Patient nach dem Gesprächsende weitergeleitet wird. Die Weiterleitung erfolgt nur, wenn der Origin der URL (Schema + Host + Port) auf der admin-konfigurierten Allowlist der Organisation steht. Ist der Origin nicht auf der Liste oder wird kein return_url übergeben, kehrt der Patient einfach zur vorherigen Seite zurück. Konfigurieren Sie die Allowlist im Admin-Portal unter Einstellungen → Rückleitungs-URLs.

Dieses return_url dient ausschließlich der Navigation nach dem Call auf der Meeting-Seite. Es ist vom return_url im Booking-Session-Body zu unterscheiden, das den Patienten nach einer erfolgreichen Buchung weiterleitet. Verwechseln Sie beide nicht.

Join-Fenster

Der Endpunkt akzeptiert Join-Anfragen ab 10 Minuten vor start_date des Termins bis 60 Minuten nach end_date. Anfragen außerhalb dieses Fensters liefern:

{ "error": ["Appointment is outside the join window"] }

Stellen Sie das in Ihrer UI klar dar — der Patient sollte einen Countdown oder einen “Join öffnet in N Minuten”-Hinweis sehen statt eines blockierten Buttons.

Gehostete UI

Leiten Sie den Patienten auf die launch_url aus der Booking-Session-Antwort weiter oder binden Sie das Widget-Skript ein:

<script
  src="https://meet.rxscale.com/booking-widget.js"
  data-launch-code="blc_Nc8..."
  data-target="#rxscale-booking"
  data-base-url="https://meet.rxscale.com">
</script>

Das Widget rendert die gehostete Buchungsseite in einem iframe innerhalb eines Shadow-DOM-Wrappers, damit Styles nicht in die Host-Seite überschwappen.

Aktions-Links in Terminerinnerungen

Diese Endpunkte werden von der RxScale-gehosteten Meetings-UI aufgerufen, wenn ein Patient einen Beitreten-, Umbuchen- oder Stornieren-Link aus einer Termin-Erinnerung per E-Mail oder SMS öffnet. Partner rufen sie nicht direkt auf — sie sind hier der Vollständigkeit halber dokumentiert.

Jeder Erinnerungs-Link enthält einen von RxScale beim Versand der Erinnerung erzeugten, undurchsichtigen Einmal-Launch-code. Der Code selbst ist das Credential — weder ein API-Key noch ein Patient Booking Token wird auf diesen Routen benötigt oder akzeptiert.

Aktions-Link-Kontext abrufen

Lädt den Anzeigekontext, den die gehostete UI benötigt, um die Landing-Page der Erinnerung zu rendern.

GET /v1/scheduling/appointment-actions/{code}

Kein Auth-Header nötig — der Code selbst ist das Credential. Ein fehlender, abgelaufener oder nicht zugeordneter Code liefert 404.

curl "https://api.rxscale.com/v1/scheduling/appointment-actions/aac_Xy9..."

{
  "action": "rebook",
  "appointment_start": 1778490000,
  "appointment_end": 1778490900,
  "doctor_display_name": "Dr. Max Meyer",
  "appointment_type_name": "Videosprechstunde",
  "join_window": {
    "state": "too_early",
    "opens_at": 1778489400
  },
  "rebook_allowed": true,
  "cancel_allowed": true,
  "already_actioned": false,
  "doctor_uid": "doc_123",
  "rebooking_mode": "same_doctor_only"
}

Feld	Typ	Beschreibung
`action`	string	Welche Aktion dieser Link startet: `join`, `rebook` oder `cancel`
`appointment_start`	integer	Startzeit des Termins (Unix-Sekunden)
`appointment_end`	integer	Endzeit des Termins (Unix-Sekunden)
`doctor_display_name`	string	Anzeigename des Arztes, für die Kopfzeile der Landing-Page
`appointment_type_name`	string	Name der Terminart
`join_window`	object	`{ state, opens_at }`. `state` ist `too_early`, `open` oder `too_late`; `opens_at` ist der Unix-Zeitstempel, zu dem der Raum öffnet (10 Minuten vor `appointment_start`)
`rebook_allowed`	boolean	Ob ein Umbuchen für diesen Termin aktuell erlaubt ist
`cancel_allowed`	boolean	Ob ein Stornieren für diesen Termin aktuell erlaubt ist
`already_actioned`	boolean	Ob die Aktion dieses Links bereits abgeschlossen wurde (z. B. wurde der Termin darüber bereits storniert)
`doctor_uid`	string	Nur vorhanden, wenn `action` gleich `rebook` ist. Die UID des aktuellen Arztes
`rebooking_mode`	string	Nur vorhanden, wenn `action` gleich `rebook` ist. Entweder `same_doctor_only` oder `any_doctor_same_organisation`

Beitreten

Liefert dieselbe Waiting-Room-Token-Struktur wie Join-Token abrufen. Wiederverwendbar, solange das Join-Fenster offen bleibt.

POST /v1/scheduling/appointment-actions/{code}/join

curl -X POST "https://api.rxscale.com/v1/scheduling/appointment-actions/aac_Xy9.../join"

{
  "room_name": "doctor-123-room",
  "token": "eyJhbGciOi...",
  "expires_at": 1778497200
}

Liefert 400, wenn der Aufruf außerhalb des Join-Fensters erfolgt (10 Minuten vor appointment_start bis 60 Minuten nach appointment_end).

Stornieren

POST /v1/scheduling/appointment-actions/{code}/cancel

string

Optionaler Freitext-Grund.

curl -X POST "https://api.rxscale.com/v1/scheduling/appointment-actions/aac_Xy9.../cancel" \
  -H "Content-Type: application/json" \
  -d '{"reason": "patient_request"}'

{
  "appointment_uid": "pdm_123",
  "status": "cancelled"
}

Einmalig: Hat der Code den Termin bereits storniert, liefert ein erneuter Aufruf 409 — ebenso, wenn der Termin aus einem anderen Grund nicht mehr storniert werden kann (bereits abgeschlossen oder außerhalb der Stornierungsfrist). Dies ist der einzige der vier Endpunkte, der ein patient_doctor_meeting_updated-Event mit change: "cancelled" auslöst.

Umbuchungs-Session starten

Legt eine gehostete Booking-Session im rebook-Modus an, damit der Patient über denselben gehosteten Buchungsflow einen neuen Slot wählen kann, der unter Booking Session erstellen beschrieben ist.

POST /v1/scheduling/appointment-actions/{code}/rebook-session

curl -X POST "https://api.rxscale.com/v1/scheduling/appointment-actions/aac_Xy9.../rebook-session"

{
  "booking_launch_code": "blc_Rk2...",
  "expires_at": 1778458500,
  "launch_url": "https://meet.rxscale.com/booking?launch=blc_Rk2..."
}

Idempotent — ein erneuter Aufruf vor Ablauf der Session liefert denselben booking_launch_code zurück, statt einen neuen zu erzeugen, und verbraucht dabei nicht den Aktions-Link-Code der Erinnerung. Der ursprüngliche Termin bleibt aktiv, bis der Patient tatsächlich einen neuen Slot bestätigt: erst dann wird er storniert und ersetzt, wobei ein rebooked-Event ausgelöst wird.

Arztportal-Endpunkte

Diese Endpunkte sind auf den authentifizierten Arzt (Auth0-Token) eingeschränkt und werden vom RxScale-Arztportal genutzt. Partner müssen sie in der Regel nicht direkt aufrufen.

Geplante Termine auflisten

GET /v1/doctor/appointments

Query-Parameter wie beim Admin-Listing: status, from, to, patient_uid, page, limit. Die Antwort enthält ausschließlich Termine des authentifizierten Arztes.

Verfügbarkeits-CRUD

GET    /v1/doctor/availability-rules
POST   /v1/doctor/availability-rules
PATCH  /v1/doctor/availability-rules/{rule_uid}
DELETE /v1/doctor/availability-rules/{rule_uid}

Jede Regel hat weekday (0 = Montag … 6 = Sonntag), start_time und end_time in Minuten seit Mitternacht, optional buffer_minutes zwischen Slots sowie optionale Gültigkeitsgrenzen valid_from / valid_until (Unix-Sekunden). PATCH-Bodies sind partiell; mit clear_valid_from: true oder clear_valid_until: true lassen sich gesetzte Grenzen entfernen. DELETE ist ein Soft-Delete.

Admin-Endpunkte

Auf die authentifizierte Admin-Organisation (Auth0-Token) eingeschränkt.

Termine auflisten

GET /v1/admin/scheduling/appointments

Query: doctor_uid, patient_uid, status, from, to, page, limit. Standard: aktive (gehalten + bestätigt) Termine ab jetzt; mit status=all und from=0 lässt sich die Historie einsehen.

Termin stornieren

POST /v1/admin/scheduling/appointments/{appointment_uid}/cancel

Body {"reason": "..."} erforderlich.

Terminart-Erinnerungen

GET    /v1/admin/scheduling/appointment-types/{appointment_type_uid}/reminders
POST   /v1/admin/scheduling/appointment-types/{appointment_type_uid}/reminders
PATCH  /v1/admin/scheduling/appointment-types/{appointment_type_uid}/reminders/{reminder_uid}
DELETE /v1/admin/scheduling/appointment-types/{appointment_type_uid}/reminders/{reminder_uid}

Jede Erinnerung hat recipient_role (patient / doctor / admin), minutes_before (positive ganze Zahl bis 60 Tage), send_email, send_sms und active. Mehrere Erinnerungen pro (appointment_type, recipient_role) sind erlaubt, solange sich der minutes_before-Offset unterscheidet. Ein Maintenance-Job läuft jede Minute, findet bestätigte Termine, deren Auslösefenster “jetzt” umfasst, und publiziert pro auflösbarem Empfänger ein scheduling.appointment_reminder_due-Event. Das Event feuert immer (Partner-Webhook-Subscriber erhalten es); der RxScale-eigene Notification-Handler verschickt E-Mail/SMS nur, wenn die jeweiligen Flags send_email / send_sms auf der Erinnerungszeile gesetzt sind. Wenn der Termin einen visit_reason hat, enthalten das Reminder-Event und die RxScale-E-Mail/SMS-Inhalte diesen Grund. Partner abonnieren das Event über den bestehenden Endpunkt für Organisations- Benachrichtigungs-Abonnements mit notification_type=APPOINTMENT_REMINDER_DUE.

Verfügbarkeiten eines Arztes ansehen

GET /v1/admin/scheduling/doctors/{doctor_uid}/availability-rules

Lesende Auflistung der wöchentlichen Buchungsfenster eines Arztes. Gibt 404 zurück, wenn der Arzt nicht in der Organisation des Admins ist.

Booking-Token-Secrets

GET    /v1/admin/scheduling/booking-token-secrets
GET    /v1/admin/scheduling/booking-token-secrets/{key_id}
POST   /v1/admin/scheduling/booking-token-secrets
DELETE /v1/admin/scheduling/booking-token-secrets/{key_id}

POST legt ein neues Secret an und gibt {key_id, secret} zurück. GET liefert den Wert entschlüsselt zurück — Secrets liegen verschlüsselt in der Datenbank, sind aber von Admins jederzeit über die API und das Admin-Portal (Einstellungen → Buchungs-Secrets) wieder lesbar, damit ein neuer Minter ohne Neu-Provisionierung konfiguriert werden kann. DELETE widerruft das Secret. Die legacy organisations-gebundenen Pfade (/v1/admin/scheduling/organisations/{organisation_uid}/booking-token-secrets[/<key_id>]) werden weiterhin akzeptiert und gegen die authentifizierte Organisation validiert.

Fehler

Die Scheduling API nutzt Standard-HTTP-Statuscodes:

Status	Bedeutung
`400`	Schema-Validierung fehlgeschlagen oder eine Geschäftsregel hat die Aktion blockiert (Details im `error`-Body).
`401`	Booking Token oder API-Key fehlt oder ist ungültig.
`404`	Ressource nicht gefunden oder der Aufrufer ist nicht berechtigt, sie zu sehen. Bei unberechtigtem Zugriff liefert die API `404`, um Resource-Enumeration zu verhindern.
`409`	Slot wurde zwischen Hold und Confirm anderweitig belegt. Neu suchen und erneut versuchen.
`429`	Rate Limit (10 Anfragen pro Sekunde pro Service). Backoff und retry.

​Scheduling

​Authentifizierung

​Patient Booking Tokens (empfohlen für Patientenflüsse)

​Organisations-API-Key

​Terminarten auflisten

​Slots suchen

​Booking Session erstellen

​Booking Session abrufen

​Abrechnung

​Holds erstellen und bestätigen

​Hold bezahlen

​Zahlung starten

​Zahlungsstatus abfragen

​Callback des Zahlungsanbieters

​Termin stornieren

​Termin umbuchen

​Join-Token abrufen

​Patienten-Meeting-Link zusammensetzen

​Join-Fenster

​Gehostete UI

​Aktions-Links in Terminerinnerungen

​Aktions-Link-Kontext abrufen

​Beitreten

​Stornieren

​Umbuchungs-Session starten

​Arztportal-Endpunkte

​Geplante Termine auflisten

​Verfügbarkeits-CRUD

​Admin-Endpunkte

​Termine auflisten

​Termin stornieren

​Termin­art-Erinnerungen

​Verfügbarkeiten eines Arztes ansehen

​Booking-Token-Secrets

​Fehler

Scheduling

Authentifizierung

Patient Booking Tokens (empfohlen für Patientenflüsse)

Organisations-API-Key

Terminarten auflisten

Slots suchen

Booking Session erstellen

Booking Session abrufen

Abrechnung

Holds erstellen und bestätigen

Hold bezahlen

Zahlung starten

Zahlungsstatus abfragen

Callback des Zahlungsanbieters

Termin stornieren

Termin umbuchen

Join-Token abrufen

Patienten-Meeting-Link zusammensetzen

Join-Fenster

Gehostete UI

Aktions-Links in Terminerinnerungen

Aktions-Link-Kontext abrufen

Beitreten

Stornieren

Umbuchungs-Session starten

Arztportal-Endpunkte

Geplante Termine auflisten

Verfügbarkeits-CRUD

Admin-Endpunkte

Termine auflisten

Termin stornieren

Terminart-Erinnerungen

Verfügbarkeiten eines Arztes ansehen

Booking-Token-Secrets

Fehler