Anamnese (v4)

Fragebogenmodelle abrufen und Anamnese-Antworten übermitteln

​

Anamnese (v4)

Mit der v4-Anamnese-API rufen Sie ein Fragebogenmodell ab, stellen es auf Ihrer eigenen Oberfläche dar und übermitteln die Antworten des Patienten zurück an RxScale. Jede Übermittlung wird vor dem Speichern gegen das Fragebogenmodell validiert, sodass ein ungültiger Inhalt niemals einen Datensatz erzeugt.

Dies ist die v4-Anamnese-API. Die bisherigen /api/v3-1/anamnesis-Endpoints sind weiterhin verfügbar — siehe Anamnese für deren Referenz.

​

Basispfad

/v4/anamnesis

​

Authentifizierung

Die Lese-Endpoints (Fragebogenmodell, öffentliche Dateien) sowie der Standard-Endpoint POST /submissions sind öffentlich und erfordern keinen API-Schlüssel. Sie sind dafür gedacht, direkt von Onlineshops und anderen Client-Oberflächen aufgerufen zu werden, die RxScale-Fragebögen darstellen.

Der externe Übermittlungs-Endpoint (POST /external/submissions) ist authentifiziert und erfordert einen API-Schlüssel im Header X-API-Key mit der Berechtigung anamnesis:external_submit. Sie dürfen nur im Namen eines externen Anamnese-Anbieters übermitteln, der zu Ihrer Organisation gehört — der übergebene provider_identifier wird zu einem Anbieter aufgelöst, der zur Organisation des API-Schlüssels gehört.

Bei den öffentlichen Endpoints sind, da keine Zugangsdaten gesendet werden, nur nicht sensible Lesevorgänge (Fragebogenmodell, öffentliche Dateien) sowie Schreibvorgänge zugänglich, die gegen das Fragebogenmodell validiert werden. Übermittelte Antworten werden über HTTPS übertragen, und eine verschlüsselte Kopie jeder Übermittlung wird im Ruhezustand aufbewahrt.

​

Endpoint-Übersicht

Methode	Endpoint	Auth	Beschreibung
GET	/questionnaires/{questionnaire_id}	Öffentlich	Fragebogenmodell und Darstellungs-Metadaten abrufen
GET	/questionnaires/{questionnaire_id}/files/{filename}	Öffentlich	Eine vom Fragebogen referenzierte Datei herunterladen
POST	/questionnaires/{questionnaire_id}/submissions	Öffentlich	Eine Anamnese für einen Fragebogen übermitteln
POST	/questionnaires/{questionnaire_id}/external/submissions	X-API-Key	Eine Anamnese im Namen eines externen Anbieters übermitteln

​

Fragebogen abrufen

Rufen Sie das Fragebogenmodell und die zur Darstellung benötigten Metadaten ab. Dieser Endpoint ist öffentlich und erfordert keinen API-Schlüssel.

GET /v4/anamnesis/questionnaires/{questionnaire_id}

questionnaire_id · string · erforderlich

Die UID des Fragebogens

​

Beispielanfrage

curl -X GET "https://api.rxscale.com/v4/anamnesis/questionnaires/abc123-def456"

​

Antwort

{
  "model": {
    "title": "Patient Intake",
    "pages": [
      {
        "name": "page1",
        "elements": [
          { "type": "text", "name": "lastName", "title": "Last name", "isRequired": true },
          { "type": "text", "name": "dob", "title": "Date of birth", "inputType": "date" }
        ]
      }
    ]
  },
  "theme": {
    "themeName": "default",
    "colorPalette": "light"
  },
  "type": "direct_to_cart",
  "identifier": "patient-intake",
  "version": 3
}

Feld	Typ	Beschreibung
model	object	Das SurveyJS-Fragebogenmodell. Übergeben Sie es an den SurveyJS-Renderer
theme	object	Das für die Darstellung verwendete SurveyJS-Theme
type	string	Der Fragebogentyp (z. B. direct_to_cart oder product_recommender)
identifier	string	Ein stabiler, menschenlesbarer Bezeichner für den Fragebogen
version	integer	Die veröffentlichte Version des Fragebogens

404 · error

Wird zurückgegeben, wenn für die angegebene questionnaire_id kein Fragebogen existiert.

​

Fragebogendatei herunterladen

Laden Sie eine vom Fragebogen referenzierte Datei herunter (z. B. ein Bild oder ein Informations-PDF). Die Datei wird als Anhang mit ihrem ursprünglichen Dateinamen zurückgegeben. Dieser Endpoint ist öffentlich und erfordert keinen API-Schlüssel.

GET /v4/anamnesis/questionnaires/{questionnaire_id}/files/{filename}

questionnaire_id · string · erforderlich

Die UID des Fragebogens

filename · string · erforderlich

Der Name der herunterzuladenden Datei

​

Beispielanfrage

curl -X GET "https://api.rxscale.com/v4/anamnesis/questionnaires/abc123-def456/files/info.pdf" \
  -o info.pdf

Die Antwort enthält die rohen Dateibytes, ausgeliefert als Anhang (Content-Disposition: attachment; filename="info.pdf").

404 · error

Wird zurückgegeben, wenn der Fragebogen oder die angeforderte Datei nicht existiert.

​

Anamnese übermitteln

Übermitteln Sie die Antworten des Patienten für einen Fragebogen. Dieser Endpoint ist öffentlich und erfordert keinen API-Schlüssel. Der data-Inhalt wird vor dem Speichern gegen das Fragebogenmodell validiert. Bei Erfolg wird die Übermittlung gespeichert (eine verschlüsselte Kopie der Antworten wird im Ruhezustand aufbewahrt) und ihre UID zurückgegeben.

POST /v4/anamnesis/questionnaires/{questionnaire_id}/submissions

questionnaire_id · string · erforderlich

Die UID des beantworteten Fragebogens

​

Anfragekörper

{
  "data": {
    "lastName": "Müller",
    "dob": "1990-05-15"
  }
}

Feld	Typ	Erforderlich	Beschreibung
data	object	Ja	Der SurveyJS-Antwortinhalt. Seine Struktur muss mit dem über Fragebogen abrufen zurückgegebenen Fragebogenmodell übereinstimmen

​

Beispielanfrage

curl -X POST "https://api.rxscale.com/v4/anamnesis/questionnaires/abc123-def456/submissions" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {"lastName": "Müller", "dob": "1990-05-15"}
  }'

​

Antwort

{
  "uid": "anam-9f8e7d6c"
}

Feld	Typ	Beschreibung
uid	string	Die UID der erstellten Anamnese. Verwenden Sie sie, um die Übermittlung mit einer Shopify-Bestellung zu verknüpfen — siehe die Anleitung zur Fragebogen-Integration

Der Endpoint antwortet bei Erfolg mit 201 Created.

​

Externe Anamnese übermitteln

Übermitteln Sie eine Fragebogenantwort im Namen eines externen Anamnese-Anbieters. Der data-Inhalt wird auf genau dieselbe Weise wie bei einer regulären Übermittlung gegen das Fragebogenmodell validiert.

Dieser Endpoint ist authentifiziert: Senden Sie Ihren API-Schlüssel im Header X-API-Key. Der Schlüssel muss die Berechtigung anamnesis:external_submit besitzen. Anstelle einer Anbieter-UID übergeben Sie einen provider_identifier, der zu einem externen Anamnese-Anbieter aufgelöst wird, der zur Organisation des API-Schlüssels gehört — Sie dürfen nur für einen Anbieter übermitteln, der zu Ihrer Organisation gehört.

POST /v4/anamnesis/questionnaires/{questionnaire_id}/external/submissions

questionnaire_id · string · erforderlich

Die UID des beantworteten Fragebogens

​

Anfragekörper

{
  "provider_identifier": "my-clinic-provider",
  "external_identifier": "ext-submission-001",
  "data": {
    "lastName": "Müller",
    "dob": "1990-05-15"
  }
}

Feld	Typ	Erforderlich	Beschreibung
provider_identifier	string	Ja	Der Bezeichner Ihres externen Anamnese-Anbieters (von RxScale bereitgestellt). Es handelt sich um einen Bezeichner, nicht um eine UID, und der Anbieter muss zu der Organisation gehören, der der API-Schlüssel zugeordnet ist
external_identifier	string	Ja	Ihr eigener Bezeichner für diese Übermittlung, zur Nachverfolgung und zur Verknüpfung mit Bestellungen
data	object	Ja	Der SurveyJS-Antwortinhalt. Seine Struktur muss mit dem Fragebogenmodell übereinstimmen

​

Beispielanfrage

curl -X POST "https://api.rxscale.com/v4/anamnesis/questionnaires/abc123-def456/external/submissions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "provider_identifier": "my-clinic-provider",
    "external_identifier": "ext-submission-001",
    "data": {"lastName": "Müller", "dob": "1990-05-15"}
  }'

​

Antwort

{
  "uid": "ext-anam-1a2b3c4d"
}

Feld	Typ	Beschreibung
uid	string	Die UID der erstellten externen Anamnese-Übermittlung

Der Endpoint antwortet bei Erfolg mit 201 Created.

​

Validierung der Übermittlung

Beide Übermittlungs-Endpoints validieren den data-Inhalt vor dem Schreiben in die Datenbank gegen das Fragebogenmodell. Schlägt die Validierung fehl, wird die Anfrage mit 400 Bad Request abgelehnt und kein Datensatz erstellt.

Der Fehlerkörper enthält die Liste der gegen das Fragebogenmodell gemeldeten Validierungsprobleme:

{
  "error": [
    "lastName is required",
    "dob must be a valid date"
  ]
}

Ist der Anfragekörper selbst fehlerhaft — etwa ein fehlendes Pflichtfeld wie data oder provider_identifier —, weist die 400-Antwort stattdessen das betreffende Feld aus:

{
  "error": {
    "data": ["Missing data for required field."]
  }
}

Ist der Übermittlungs-Validierer vorübergehend nicht erreichbar, schlägt die Anfrage mit 502 Bad Gateway fehl und es wird kein Datensatz erstellt. Dabei handelt es sich um eine vorübergehende Störung eines vorgelagerten Dienstes und nicht um ein Problem mit Ihrem Inhalt — wiederholen Sie die Anfrage:

{
  "error": "submission validator unavailable"
}

Rufen Sie immer das aktuelle Fragebogenmodell über Fragebogen abrufen ab und rendern Sie Ihr Formular daraus. Werden Antworten übermittelt, die nicht zum aktuellen Modell passen, schlägt die Validierung fehl und die Übermittlung wird nicht gespeichert.

​

Fehlerantworten

Status	Bedeutung
400	Die Übermittlung hat die Validierung gegen das Fragebogenmodell nicht bestanden oder der Anfragekörper war fehlerhaft. Es wird kein Datensatz erstellt
401	Fehlender oder ungültiger API-Schlüssel (nur externer Übermittlungs-Endpoint)
403	Dem API-Schlüssel fehlt die Berechtigung anamnesis:external_submit (nur externer Übermittlungs-Endpoint)
404	Für die angegebene questionnaire_id existiert kein Fragebogen, oder der provider_identifier verweist auf keinen zu Ihrer Organisation gehörenden Anbieter
409	Für diesen Anbieter existiert bereits eine externe Übermittlung mit diesem external_identifier (nur externer Übermittlungs-Endpoint)
502	Der Übermittlungs-Validierer war vorübergehend nicht erreichbar. Es wird kein Datensatz erstellt — wiederholen Sie die Anfrage

​

Typischer Integrationsablauf

1. Fragebogenmodell abrufen

   Rufen Sie GET /questionnaires/{questionnaire_id} auf, um model und theme zu erhalten.

2. Fragebogen darstellen

   Rendern Sie das Modell mit dem SurveyJS-Renderer (oder verwenden Sie das RxScale-Snippet, das dies für Sie übernimmt).

3. Antworten übermitteln

   Senden Sie die erfassten data an /submissions (öffentlich) oder mit Ihrem X-API-Key an /external/submissions für externe Anbieter. RxScale validiert die Antworten gegen das Modell.

4. Zurückgegebene UID speichern

   Speichern Sie die zurückgegebene uid und verwenden Sie sie, um die Übermittlung mit einer Shopify-Bestellung zu verknüpfen. Siehe die Anleitung zur Fragebogen-Integration.