API-Referenz

Diese Seite ergänzt den Integrationsleitfaden um konkrete Implementierungsbeispiele. Für die wichtigsten Operationen der externen FHIR-API – etwa Patienten suchen, anlegen und aktualisieren sowie Befunde, Diagnosen, Therapien und Dokumente schreiben – zeigt sie vollständige HTTP-Requests mit typischen Responses. Die Beispiele folgen dem im Leitfaden beschriebenen Ablauf (Kontext, Authentifizierung, Profile) und können als Vorlage für die eigene Implementierung dienen. Am Ende der Seite finden Sie typische Fehlerbeispiele.

Request-/Response-Beispiele

Hinweise

  • Platzhalter: Beispiele verwenden <HOST>, <API_KEY>, <KONTEXT_ID>, <OAUTH_TOKEN>.
  • JSON: Für JSON Content-Type und Accept auf application/fhir+json setzen.
  • XML: Die API akzeptiert alternativ application/fhir+xml; charset=UTF-8.
  • X-FHIR-Profile ist bei create-Operationen nicht erforderlich; maßgeblich ist meta.profile.
  • Deep Link: Der APS-Client öffnet das aufrufUrlTemplate nach Ersetzung von ${kontextId}, ${FHIRBasisUrl}, ${oAuthToken}.

Alle Beispiele beziehen sich auf die externe FHIR-HTTP-API unter /aps/fhir/api/r4.

Patient per Kontext-Identifier suchen

Request

GET https://<HOST>/aps/fhir/api/r4/Patient?identifier=https://fhir.t2med.de/identifier/kontext|<KONTEXT_ID>
Accept: application/fhir+json
Authorization: Bearer <OAUTH_TOKEN>
Prefer: return=OperationOutcome
X-API-Key: <API_KEY>
X-TreatWarningAsError: true
X-FHIR-Profile: https://fhir.t2med.de/StructureDefinition/FhirApiPatient|1.0.0

Response (200)

{
  "resourceType": "Patient",
  "id": "<PATIENT_OBJECT_ID>",
  "meta": {
    "profile": [
      "https://fhir.t2med.de/StructureDefinition/FhirApiPatient|1.0.0"
    ]
  },
  "identifier": [
    {
      "system": "https://fhir.t2med.de/identifier/kontext",
      "value": "<KONTEXT_ID>"
    }
  ]
}

Patient per Name und Geburtsdatum suchen

Request

GET https://<HOST>/aps/fhir/api/r4/Patient?family=must&given=max&birthdate=1980-04-12
Accept: application/fhir+json
Authorization: Bearer <OAUTH_TOKEN>
Prefer: return=OperationOutcome
X-API-Key: <API_KEY>
X-FHIR-Profile: https://fhir.t2med.de/StructureDefinition/FhirApiPatient|1.0.0

Response (200, Suchergebnis)

{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "meta": {
          "profile": [
            "https://fhir.t2med.de/StructureDefinition/FhirApiPatient|1.0.0"
          ]
        }
      }
    }
  ]
}

Patient per ID lesen

Request

GET https://<HOST>/aps/fhir/api/r4/Patient/<PATIENT_OBJECT_ID>
Accept: application/fhir+json
Authorization: Bearer <OAUTH_TOKEN>
Prefer: return=OperationOutcome
X-API-Key: <API_KEY>
X-FHIR-Profile: https://fhir.t2med.de/StructureDefinition/FhirApiPatient|1.0.0

Response (200)

{
  "resourceType": "Patient",
  "id": "<PATIENT_OBJECT_ID>",
  "meta": {
    "profile": [
      "https://fhir.t2med.de/StructureDefinition/FhirApiPatient|1.0.0"
    ]
  }
}

Patient anlegen

Request

POST https://<HOST>/aps/fhir/api/r4/Patient
Content-Type: application/fhir+json
Accept: application/fhir+json
Authorization: Bearer <OAUTH_TOKEN>
X-API-Key: <API_KEY>

{
  "resourceType": "Patient",
  "meta": {
    "profile": [
      "https://fhir.t2med.de/StructureDefinition/FhirApiPatient|1.0.0"
    ]
  },
  "identifier": [
    {
      "system": "https://fhir.t2med.de/identifier/kontext",
      "value": "<KONTEXT_ID>"
    }
  ],
  "name": [
    {
      "family": "Mustermann",
      "given": ["Max"]
    }
  ],
  "birthDate": "1980-04-12",
  "gender": "male"
}

Response: 201 + OperationOutcome (siehe Beispiel bei „Observation anlegen (Befund)“ unten).

Patient aktualisieren

Request — mit If-Match-Header für Optimistic Locking (empfohlen):

Tips

<VERSION> ist die kurze Versionsnummer aus meta.versionId des vorherigen Lesezugriffs, extrahiert via IdType(meta.versionId).versionIdPart (z. B. "4" aus "abc123/_history/4"). Ohne If-Match-Header wird kein Versionscheck durchgeführt.

PUT https://<HOST>/aps/fhir/api/r4/Patient/<PATIENT_OBJECT_ID>
Content-Type: application/fhir+json
Accept: application/fhir+json
Authorization: Bearer <OAUTH_TOKEN>
X-API-Key: <API_KEY>
If-Match: W/"<VERSION>"

{
  "resourceType": "Patient",
  "id": "<PATIENT_OBJECT_ID>",
  "meta": {
    "profile": [
      "https://fhir.t2med.de/StructureDefinition/FhirApiPatient|1.0.0"
    ]
  },
  "name": [
    {
      "family": "Mustermann",
      "given": ["Max"]
    }
  ],
  "birthDate": "1980-04-12",
  "gender": "other",
  "_gender": {
    "extension": [
      {
        "url": "http://fhir.de/StructureDefinition/gender-amtlich-de",
        "valueCoding": {
          "system": "http://fhir.de/CodeSystem/gender-amtlich-de",
          "code": "D"
        }
      }
    ]
  },
  "telecom": [
    {
      "system": "phone",
      "value": "089 123456",
      "use": "home"
    }
  ]
}

Response: 200. Beim Aktualisieren einer bestehenden Ressource antwortet die API mit 200 (nicht 201, das ist dem Anlegen vorbehalten).

Observation anlegen (Befund)

Request

POST https://<HOST>/aps/fhir/api/r4/Observation
Content-Type: application/fhir+json
Accept: application/fhir+json
Authorization: Bearer <OAUTH_TOKEN>
Prefer: return=OperationOutcome
X-API-Key: <API_KEY>
X-TreatWarningAsError: true

{
  "resourceType": "Observation",
  "meta": {
    "profile": [
      "https://fhir.t2med.de/StructureDefinition/FhirApiObservationBefund|1.0.0"
    ]
  },
  "identifier": [
    {
      "system": "https://fhir.t2med.de/identifier/kontext",
      "value": "<KONTEXT_ID>"
    }
  ],
  "status": "final",
  "effectiveDateTime": "2026-01-29T08:36:00+01:00",
  "valueString": "leichtes Fieber"
}

Response (201)

{
  "resourceType": "OperationOutcome",
  "meta": {
    "profile": [
      "https://fhir.t2med.de/StructureDefinition/FhirApiOperationOutcome|1.0.0"
    ]
  },
  "issue": [
    {
      "severity": "information",
      "code": "processing"
    }
  ]
}

Observation anlegen (Anamnese)

Wie „Observation anlegen (Befund)“, aber Profil:

https://fhir.t2med.de/StructureDefinition/FhirApiObservationAnamnese|1.0.0

Observation anlegen (Freitext)

Wie „Observation anlegen (Befund)“, aber Profil:

https://fhir.t2med.de/StructureDefinition/FhirApiObservationFreitext|1.0.0

Zusätzlich mögliche Extension:

{
  "extension": [
    {
      "url": "https://fhir.t2med.de/StructureDefinition/FhirApiFreitextKuerzel",
      "valueString": "Info"
    }
  ]
}

DocumentReference anlegen (Freitext)

Request

POST https://<HOST>/aps/fhir/api/r4/DocumentReference
Content-Type: application/fhir+json
Accept: application/fhir+json
Authorization: Bearer <OAUTH_TOKEN>
Prefer: return=OperationOutcome
X-API-Key: <API_KEY>

{
  "resourceType": "DocumentReference",
  "meta": {
    "profile": [
      "https://fhir.t2med.de/StructureDefinition/FhirApiDocumentReferenceFreitext|1.0.0"
    ]
  },
  "identifier": [
    {
      "system": "https://fhir.t2med.de/identifier/kontext",
      "value": "<KONTEXT_ID>"
    }
  ],
  "status": "current",
  "date": "2026-01-29T08:36:00+01:00",
  "content": [
    {
      "attachment": {
        "contentType": "text/plain;charset=UTF-8",
        "title": "ToDo",
        "data": "RmVobGVyYmVoYW5kbHVuZyB2ZXJiZXNzZXJuLgpGZWhsZXJzaW11bGF0aW9uIGVpbmJhdWVuLg=="
      }
    }
  ]
}

Response: 201 + OperationOutcome.

DocumentReference anlegen (Anhang)

Request

POST https://<HOST>/aps/fhir/api/r4/DocumentReference
Content-Type: application/fhir+json
Accept: application/fhir+json
Authorization: Bearer <OAUTH_TOKEN>
Prefer: return=OperationOutcome
X-API-Key: <API_KEY>

{
  "resourceType": "DocumentReference",
  "meta": {
    "profile": [
      "https://fhir.t2med.de/StructureDefinition/FhirApiDocumentReferenceAnhang|1.0.0"
    ]
  },
  "identifier": [
    {
      "system": "https://fhir.t2med.de/identifier/kontext",
      "value": "<KONTEXT_ID>"
    }
  ],
  "status": "current",
  "date": "2026-01-29T08:36:00+01:00",
  "description": "Befundbericht als PDF",
  "extension": [
    {
      "url": "https://fhir.t2med.de/StructureDefinition/FhirApiAnhangKuerzel",
      "valueString": "PDF"
    }
  ],
  "content": [
    {
      "attachment": {
        "contentType": "application/pdf",
        "title": "befundbericht.pdf",
        "creation": "2026-01-29T08:36:00+01:00",
        "data": "JVBERi0xLjQKJ..."
      }
    }
  ]
}

Response: 201 + OperationOutcome.

Procedure anlegen (Therapie)

Request

POST https://<HOST>/aps/fhir/api/r4/Procedure
Content-Type: application/fhir+json
Accept: application/fhir+json
Authorization: Bearer <OAUTH_TOKEN>
Prefer: return=OperationOutcome
X-API-Key: <API_KEY>
X-TreatWarningAsError: true

{
  "resourceType": "Procedure",
  "meta": {
    "profile": [
      "https://fhir.t2med.de/StructureDefinition/FhirApiProcedureTherapie|1.0.0"
    ]
  },
  "identifier": [
    {
      "system": "https://fhir.t2med.de/identifier/kontext",
      "value": "<KONTEXT_ID>"
    }
  ],
  "code": {
    "text": "Täglich drei Mal spazieren gehen"
  },
  "extension": [
    {
      "url": "https://fhir.t2med.de/StructureDefinition/FhirApiFeststellungszeitpunkt",
      "valueDateTime": "2026-01-29T08:36:00+01:00"
    }
  ]
}

Der Text des Eintrags steht in code.text (Pflicht). Statt identifier kann der Kontext auch über encounter.reference (Encounter/<KONTEXT_ID>) angegeben werden.

Response: 201 + OperationOutcome.

Zeitpunkt-Reihenfolge in der Implementierung:

  1. Extension https://fhir.t2med.de/StructureDefinition/FhirApiFeststellungszeitpunkt
  2. Extension https://fhir.t2med.de/StructureDefinition/FhirApiProcedureOccurrence
  3. performedDateTime

Procedure anlegen (Prozedere)

Wie „Procedure anlegen (Therapie)“, aber mit dem Profil:

https://fhir.t2med.de/StructureDefinition/FhirApiProcedureProcedere|1.0.0

Beispiel für code.text: "Morgens, mittags, abends". Aufbau, Pflichtfelder und Zeitpunkt-Reihenfolge entsprechen der Therapie.

Condition anlegen (Diagnose)

Request

POST https://<HOST>/aps/fhir/api/r4/Condition
Content-Type: application/fhir+json
Accept: application/fhir+json
Authorization: Bearer <OAUTH_TOKEN>
Prefer: return=OperationOutcome
X-API-Key: <API_KEY>

{
  "resourceType": "Condition",
  "meta": {
    "profile": [
      "https://fhir.t2med.de/StructureDefinition/FhirApiConditionDiagnose|1.0.0"
    ]
  },
  "identifier": [
    {
      "system": "https://fhir.t2med.de/identifier/kontext",
      "value": "<KONTEXT_ID>"
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://fhir.de/CodeSystem/bfarm/icd-10-gm",
        "version": "2026",
        "code": "J06.9"
      }
    ],
    "text": "Diagnoseklartext"
  },
  "onsetDateTime": "2026-01-29T09:14:00+01:00"
}

Response: 201 + OperationOutcome.

Kontext anlegen (Device Flow)

Beim Device Flow gibt es keinen Deep Link. Den Kontext legt die Drittanbieter-Anwendung selbst an (ab Version 26.10). Pflicht sind Patient, Arztrolle und Behandlungsort, der Behandlungsfall ist optional.

Request

POST https://<HOST>/aps/fhir/api/r4/Encounter
Content-Type: application/fhir+json
Accept: application/fhir+json
Authorization: Bearer <OAUTH_TOKEN>
Prefer: return=OperationOutcome
X-API-Key: <API_KEY>
X-TreatWarningAsError: true

{
  "resourceType": "Encounter",
  "meta": {
    "profile": [
      "https://fhir.t2med.de/StructureDefinition/FhirApiEncounter|1.0.0"
    ]
  },
  "subject": {
    "reference": "Patient/<PATIENT_OBJECT_ID>"
  },
  "episodeOfCare": [
    {
      "reference": "EpisodeOfCare/<BEHANDLUNGSFALL_ID>"
    }
  ],
  "participant": [
    {
      "individual": {
        "reference": "Practitioner/<ARZTROLLE_ID>"
      }
    }
  ],
  "serviceProvider": {
    "reference": "Organization/<BEHANDLUNGSORT_ID>"
  }
}

Response: 201 + OperationOutcome. Die Kontext-ID steht im Header Location, z. B. https://<HOST>/aps/fhir/api/r4/Encounter/<KONTEXT_ID>/_history/0. Mit dieser kontextId lassen sich die schreibenden Aufrufe wie im Deep-Link-Pfad ausführen. Fehlen subject, participant oder serviceProvider, antwortet der Server mit 400.

eAkte lesen

Ab Version 26.11 liefert die Operation $eakte die eAkte eines Patienten. Mit start und end lässt sich der Zeitraum eingrenzen, embedEncounter bettet den Encounter in jeden Eintrag ein.

Request (Parameter in der URL)

GET https://<HOST>/aps/fhir/api/r4/Patient/<PATIENT_OBJECT_ID>/$eakte?start=2026-01-01&end=2026-12-31&embedEncounter=false
Accept: application/fhir+json
Authorization: Bearer <OAUTH_TOKEN>
X-API-Key: <API_KEY>
X-TreatWarningAsError: true

Request (Parameter im Body)

POST https://<HOST>/aps/fhir/api/r4/Patient/<PATIENT_OBJECT_ID>/$eakte
Content-Type: application/fhir+json
Accept: application/fhir+json
Authorization: Bearer <OAUTH_TOKEN>
X-API-Key: <API_KEY>
X-TreatWarningAsError: true

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "start",
      "valueDate": "2026-01-01"
    },
    {
      "name": "end",
      "valueDate": "2026-12-31"
    },
    {
      "name": "embedEncounter",
      "valueString": "false"
    }
  ]
}

Response (200, gekürzt)

{
  "resourceType": "Bundle",
  "meta": {
    "profile": [
      "https://fhir.t2med.de/StructureDefinition/FhirApiBundleEAkte|1.0.0"
    ]
  },
  "type": "searchset",
  "entry": [
    {
      "resource": {
        "resourceType": "Composition",
        "meta": {
          "profile": [
            "https://fhir.t2med.de/StructureDefinition/FhirApiCompositionEAkte|1.0.0"
          ]
        },
        "status": "final",
        "type": {
          "coding": [
            {
              "system": "http://hl7.org/fhir/ValueSet/doc-typecodes",
              "code": "11503-0"
            }
          ]
        },
        "subject": {
          "reference": "Patient/<PATIENT_OBJECT_ID>"
        },
        "date": "2026-01-29T08:36:00+01:00",
        "author": [
          {
            "reference": "Practitioner/<ARZTROLLE_ID>"
          }
        ],
        "title": "<Titel des Eintrags>",
        "custodian": {
          "reference": "Organization/<BEHANDLUNGSORT_ID>"
        },
        "section": [
          {
            "title": "<Titel des Eintrags>",
            "text": {
              "status": "generated",
              "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Text des Eintrags</div>"
            }
          }
        ]
      }
    }
  ]
}

Dokumente und Bilder sind als DocumentReference referenziert. Eine einzelne Referenz lässt sich mit GET /DocumentReference/<ID> lesen.

Transaction Bundle

Request

POST https://<HOST>/aps/fhir/api/r4
Content-Type: application/fhir+json
Accept: application/fhir+json
Authorization: Bearer <OAUTH_TOKEN>
Prefer: return=OperationOutcome
X-API-Key: <API_KEY>

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "request": {
        "method": "POST",
        "url": "Observation"
      },
      "resource": {
        "resourceType": "Observation",
        "meta": {
          "profile": [
            "https://fhir.t2med.de/StructureDefinition/FhirApiObservationBefund|1.0.0"
          ]
        },
        "identifier": [
          {
            "system": "https://fhir.t2med.de/identifier/kontext",
            "value": "<KONTEXT_ID>"
          }
        ],
        "status": "final",
        "effectiveDateTime": "2026-01-30T08:36:00+01:00",
        "valueString": "leichtes Fieber"
      }
    }
  ]
}

Response (200)

{
  "resourceType": "Bundle",
  "type": "transaction-response",
  "entry": [
    {
      "response": {
        "status": "201",
        "outcome": {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "information",
              "code": "processing"
            }
          ]
        }
      }
    }
  ]
}

Typische Fehlerbeispiele

Fehlender API-Key (403)

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "forbidden",
      "diagnostics": "Der FHIR-API-Key fehlt oder ist ungültig."
    }
  ]
}

Profil fehlt bei Create (400)

{
  "resourceType": "OperationOutcome",
  "meta": {
    "profile": [
      "https://fhir.t2med.de/StructureDefinition/FhirApiOperationOutcome|1.0.0"
    ]
  },
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Das Profil ist nicht angegeben."
    }
  ]
}

Profil nicht unterstützt (501)

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-supported",
      "diagnostics": "Das Profil wird nicht unterstützt."
    }
  ]
}

Eine vollständige Übersicht der HTTP-Statuscodes und ihrer Bedeutung findet sich unter Leitfaden → Fehlerbehandlung und Robustheit.