Referenzen abrufen

Ein Termin kann mit Formularen und Dateien der Medizinischen Dokumentation verknüpft sein. Diese Verknüpfungen sind nicht Teil des Termin-Objekts. Über diesen Endpoint rufst du sie getrennt ab.

Gibt die Referenzen eines Termins zurück.

Erforderliche Scopes: appointments. Die Ziele eines Typs erscheinen nur, wenn dein API-Zugang zusätzlich den passenden Scope hat: forms für die Typen Form und FormCustomer, medicals für den Typ MedicalFile. Fehlt der Scope, fehlen die Referenzen dieses Typs in der Liste.

Hinweis: Referenzen, deren Ziel der Client nicht sehen darf, werden stillschweigend herausgefiltert. meta.total zählt daher nur die für den Client sichtbaren Referenzen, nicht alle gespeicherten. Nicht sichtbar sind Ziele, die gelöscht sind, deren Scope fehlt, für die der Besitzer-Benutzer des API-Zugangs keine Berechtigung hat oder deren Kunde in einem Mandanten liegt, der für den Besitzer-Benutzer des API-Zugangs nicht freigegeben ist (nur mit dem Add-on Mandanten).

Hinweis: Ein fremder privater Termin ohne Freigabe zeigt im Kalender keine Inhalte. Der Endpoint antwortet dafür mit 200 OK, data: [] und meta.total: 0 – nicht mit einem Fehler.

Request

GET /api/oauth/v2/resource/appointments/{uuid}/references

Header

Header	Wert
Authorization	Bearer {access_token}

URL-Parameter

Parameter	Typ	Pflicht	Beschreibung
uuid	string	Ja	Eindeutige Termin-ID

Query-Parameter

Parameter	Typ	Pflicht	Beschreibung
offset	integer	Nein	Startposition (Standard: 0)
limit	integer	Nein	Anzahl Ergebnisse (Standard: 50, Max: 200)

Die Referenzen sind in der Reihenfolge sortiert, in der sie angelegt wurden.

Response

Erfolg (200 OK)

{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "type": "Form",
      "target": "c3d4e5f6-a7b8-9012-cdef-234567890123",
      "createdAt": "2026-10-12T09:30:00+02:00"
    },
    {
      "id": "d4e5f6a7-b8c9-0123-def0-345678901234",
      "type": "MedicalFile",
      "target": "e5f6a7b8-c9d0-1234-ef01-456789012345",
      "createdAt": "2026-10-12T09:42:00+02:00"
    }
  ],
  "meta": {
    "total": 2,
    "offset": 0,
    "limit": 50
  }
}

Hat der Termin keine Referenzen, ist data eine leere Liste.

Response-Felder

Feld	Typ	Beschreibung
data[].id	string (UUID)	Eindeutige Referenz-ID
data[].type	string	Typ des verknüpften Ziels: Form, FormCustomer oder MedicalFile
data[].target	string (UUID) | null	UUID des verknüpften Datensatzes, ohne eingebettete Kurzbezeichnung. Du löst sie je nach Typ mit GET /forms/{uuid} (Form), GET /forms/customers/{uuid} (FormCustomer) oder GET /files/{uuid} (MedicalFile) auf
data[].createdAt	string (ISO 8601) | null	Zeitpunkt, zu dem die Referenz angelegt wurde
meta.total	integer	Anzahl der für den Client sichtbaren Referenzen
meta.offset	integer	Aktuelle Startposition
meta.limit	integer	Anzahl der zurückgegebenen Einträge

Beispiele

bash

curl -X GET "https://my.offisy.at/api/oauth/v2/resource/appointments/b2c3d4e5-f6a7-8901-bcde-f01234567890/references?offset=0&limit=50" \
  -H "Authorization: Bearer {access_token}"

Server

Client-ID

Client-Secret

Parameter

uuid *string

offset integer

limit integer

Zuerst Token anfordern

Mögliche Fehler

Status	Code	Beschreibung
401	invalid_client	Ungültiger oder fehlender Access Token
403	insufficient_scope	Scope appointments nicht vorhanden
403	access_denied	Der Besitzer-Benutzer des API-Zugangs hat nicht die benötigte Berechtigung für den Termin, oder der Termin gehört zu einer fremden Firma
404	not_found	Termin nicht gefunden