Application Programming Interface (API)

Mit dieser API können Sie Vorgänge rund um PsyDix.org und psychologische Testverfahren automatisieren. Sie bildet das Grundgerüst für die nahtlose Interaktion zwischen verschiedenen Softwareanwendungen und maßgeschneiderten Lösungen.

Authentifizierung

Die Authentifizierung der API erfolgt über Basic Auth.

Übergeben Sie bitte die folgenden Daten zusammen mit Ihrer HTTP-Anfrage:

Sie können Ihren geheimen API-Schlüssel unter „Mein Therapeutenbereich“ generieren und anzeigen lassen:

Mein Therapeutenbereich > Meine Daten > Meine Application Programming Interface (API) - Schnittstelle

Den Implementierungsaufwand könnten Sie wie folgt abschätzen:

  1. Einbindung eines Eingabefelds für den geheimen Schlüssel (z. B. in den Einstellungen)
  2. GET-Anfrage zur Anzeige der verfügbaren Test-Batterien
  3. POST-Anfrage zum Anlegen der Test-Batterie
  4. Optional: Benachrichtigung über beantwortete Fragebögen mittels Webhook

Durch diese Schritte könnten Sie problemlos über 100 psychologische Testverfahren in Ihre Software integrieren.

GET https://psydix.org/api/v1/erhalte-test-batterien/

Sie erhalten Sie ein JSON-Array von Objekten der Test-Batterien: 

[
  {
    "title": "Meine erste Test-Batterie",
    "codeBattery": "bWioebwzIr8yZG1Y1oY1"
  },
  {
    "title": "Test-Batterie für Depression",
    "codeBattery": "QYYLtdESjBmNEmX4fmI8"
  },
  {
    "title": "Test-Batterie für KJP",
    "codeBattery": "b9BpEdCaKbKT9PTttuT5"
  }
]

titel ist der Titel der Test-Batterie und codeBattery der Identifikationscode.

POST https://psydix.org/api/v1/erstelle-test-batterie/

POST-Parameter:

Um einen neuen Patienten anzulegen, können Sie die (leider nicht ganz intuitive) Abkürzung verwenden und eine Test-Batterie erstellen.

Bei Erstellung einer neuen Test-Batterie wird gleichzeitig ein neuer Patient angelegt, sofern kein optionaler Patienten-Code übertragen wurde.

Falls Sie den optionalen Patienten-Code übermitteln, werden die psychologischen Testverfahren der Test-Batterie für den bereits vorhandenen Patienten-Code erstellt.

Folglich können Sie mit nur einen API-Aufruf einen neuen Patienten mit mehreren Tests anlegen.

Übergeben Sie den codeBattery der Test-Batterie als Parameter, und im Erfolgsfall erhalten Sie als Rückgabewert ein Objekt der folgenden Form: 

{
  "codePatient": "PXXXXXXXXX",
  "codesTestsNew": ["XXXXXXXXXXX", "XXXXXXXXXXY", "XXXXXXXXXXZ"]
}

Ausnahme: Beim Erstellen eines HAQ, der aus zwei Fragebögen Selbst- und Fremdbeurteilung besteht, wird nur der Code des ersten Fragebogens zurückgegeben.

Wenn Sie in Ihrer Anwendung auf die Fragebögen verlinken möchten, können Sie den Link wie folgt erstellen:

Sollten codeBattery oder codePatient fehlerhaft sind, wird eine Fehlermeldung zurückgegeben. Ebenso wird eine entsprechende Meldung ausgegeben, wenn nicht mehr ausreichend Tests in im gebuchten Paket verfügbar sind.

GET https://psydix.org/api/v1/erhalte-tests/[(PATIENTEN-)CODE/]

Gibt eine Liste aller angelegten Tests zurück. Jeder Test wird durch ein JSON-Objekt dargestellt, das die folgenden Informationen enthält: 

[
  {
    "codeTest":    "TEST-CODE",
    "codePatient": "PATIENTEN-CODE",
    "title":       "Titel des psychologischen Testverfahrens",
    "acronym":     "TDPT",
    "language":    "de",
    "scores":      [0,2,4,4,0,10],
    "dateCreated": "DATUM-ERSTELLT",
    "dateDone":    "DATUM-BEANTWORTET"
  }
]

Sofern codePatient, scores oder dateDone nicht gesetzt sind, ist der entsprechende Wert null. Die Tests werden in der Reihenfolge ihrer Erstellung zurückgegeben, mit dem zuletzt angelegten psychologischen Testverfahren zuerst.

Beispielantwort:

[
  {
    "codeTest":    "XXXXXXXXXX",
    "codePatient": null,
    "title":       "ICD-10-Symptom-Rating",
    "acronym":     "ISR",
    "language":    "de",
    "scores":      null,
    "dateCreated": "2025-09-11 22:00:00",
    "dateDone":    null
  },
  {
    "codeTest":    "XXXXXXXXXY",
    "codePatient": "PXXXXXXXXX",
    "title":       "Rasch-basiertes Depressionsscreening I",
    "acronym":     "DESC-I",
    "language":    "de",
    "scores":      [14],
    "dateCreated": "2025-09-12 22:00:00",
    "dateDone":    "2025-09-14 22:00:00"
  }
]

Die Daten werden in der Zeitzone UTC zurückgegeben. 2025-09-12 22:00:00 UTC aus dem Beispiel entspricht 2025-09-13 in der Zeitzone Europe/Berlin.
Bitte beachten Sie, dass sich dies in Zukunft ändern kann. Wir planen eine Migration zu einer anderen Datenbanktechnologie, PostgreSQL, bei der das Datum mit Zeitzone zurückgegeben wird. Der erwartete neue Wert wäre dann: 2025-09-12 22:00:00+0

Optional kann ein (Patienten-)Code übergeben werden. Wenn ein Test-Code übergeben wird, erhalten Sie ein Array mit den Informationen dieses spezifischen Tests. Wenn hingegen ein Patienten-Code übergeben wird, werden Ihnen die Informationen zu allen Tests dieses Patienten zurückgegeben.

GET https://psydix.org/api/v1/erhalte-auswertung-pdf/CODE/

Liefert die PDF-Auswertung für einen angegebenen Test- oder Patienten-Code.

Die folgenden Parameter können optional an die URL angehängt werden:

Es ist auch möglich, beide Parameter zu kombinieren: ?kurz=1&sw=1

Webhook

Über einen Webhook können Sie Benachrichtigungen über beantwortete psychologische Testverfahren erhalten.

Sie können Ihre Webhook-URL in Ihrem Therapeutenbereich festlegen:

Mein Therapeutenbereich > Meine Daten > Mein Webhook

Beim Abspeichern der Webhook-URL wird automatisch ein zufälliger Bearer-Zugangs-Token generiert und einmalig angezeigt. Sie können in verwenden, um sicherzustellen, dass nur authorisierte Zugriffe auf Ihre Webhook-URL erfolgen.

Sie werden ein JSON-Objekt mit den folgenden Schlüsseln erhalten:

Hier ist ein Beispiel für das JSON-Objekt: 

{
  "codeTest":    "XXXXXXXXXX",
  "codePatient": "PXXXXXXXXX",
  "title":       "Titel des psychologischen Testverfahrens",
  "acronym":     "TDPT",
  "language":    "de",
  "scores":      [0,2,4,4,0,10],
  "dateDone":    "2025-09-14 22:00:00"
}

Wenn Sie in Ihrer Anwendung auf die Auswertung verlinken möchten, können Sie den Link wie folgt erstellen:

Wenn Sie PHP verwenden, können Sie den folgenden Code verwenden, um die JSON-Daten zu empfangen: 

$json = file_get_contents('php://input');
$data = json_decode($json, true);

Auf den Bearer-Zugangs-Token können Sie beispielsweise mit folgendem PHP-Code zugreifen: 

$authorizationHeader = $_SERVER['HTTP_AUTHORIZATION'] ?? $_SERVER['REDIRECT_HTTP_AUTHORIZATION'] ?? '';

if (preg_match('/^Bearer (.+)$/', $authorizationHeader, $matches)) {
  $token = $matches[1];
  if (password_verify($token, $storedHashOfToken)) {
    // token is valid
  }
}
Mein Therapeutenbereich
×