swagger: "2.0"
info:
  title: Arztnummernverzeichnis API
  description: >-
    Die API für das KHANR-VZ für den Zugriff durch die Verwaltungssysteme der Krankenhäuser
  version: 1.0.0
  contact:
    name: innovas GmbH
    email: suport-health@innovas.de
basePath: /arztnummernverzeichnis/api-extern/v1.0.0

#libraryName und libraryNameClient werden nur intern bei der Innovas verwendet
x-libraryName: arztnummernverzeichnissst
x-libraryNameClient: "@innovas/arztnummernverzeichnissst-lib"

securityDefinitions:
  jwt:
    description: Zur Authentifizierung an dieser Schnittstelle muss zunächst unter dem Endpoint /benutzer/api-extern/v0.0.1/authenticate ein JWT-Token angefordert werden. Beim Aufruf muss im Header das Feld Sec-Maschineller-Request mit dem Startwert "Startwert_Sec-Maschineller-Request" gesetzt sein. Zur Authentifizierung werden dem authenticate-Aufruf Benutzername und Passwort übermittelt. Der Endpoint Authenticate liefert ein Cookie JWT_TOKEN zurück. Im Header findet sich im Feld Sec-Maschineller-Request ein weiterer Antworttoken. Der Cookie muss zur Authentifizierung beim Aufruf weiterer Endpoints als header mit dem Namen "Cookie" übergeben werden. Der Header Sec-Maschineller-Request muss auf den erhalten Antworttoken gesetzt werden.
    type: apiKey
    in: header
    name: Cookie
security:
  - jwt: []
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json

responses:
  invalidarguments:
    description: Ungültige Parameter übergeben
    schema:
      type: array
      minItems: 1
      items:
        $ref: "#/definitions/Meldung"
  unknownerror:
    description: Unbekannter Fehler aufgetreten
    schema:
      type: array
      minItems: 1
      items:
        $ref: "#/definitions/Meldung"
  objectNotFound:
    description: Ein Objekt wurde anhand seiner ID nicht gefunden

paths:
  /arzteintrag:
    post:
      summary: Erzeugt einen neuen Arzteintrag
      description: |
        Versucht einen neuen Arzteintrag im KHANR-VZ anzulegen. Beim ersten Aufruf für einen Arzt muss die Iteration immer mit ERSTE_ITERATION übergeben werden. Als Ergebnis des Aufrufs gibt es drei Möglichkeiten.
          * Der Arzteintrag konnte ohne Warnmeldungen angelegt werden. Das ArzteintragAnlegenErgebnis enthält einen Arzteintrag und die ANR darin ist gefüllt.
          * Der Arzteintrag könnte angelegt werden, wurde jedoch noch nicht angelegt, da der anzulegende Arzt im KHANR-VZ mit anderen Daten aufgeführt ist. Die Abweichungen sind in den Warnungen des ArzteintragAnlegenErgebnis aufgeführt. Wenn die Daten nur mit kleinen Abweichungen eingegeben wurden und es pro Attribut nur einen abweichenden Wert gibt, so wird ein Korrekturvorschlag berechnet und zurückgegeben. Die Hinweismeldungen und der optionale Korrekturvorschlag sollten dem Anwender angezeigt werden und dieser sollte die Daten erneut anhand der offiziellen Dokumente prüfen. Anschließend kann der (ggf. korrigierte) Arzteintrag erneut übermittelt werden, indem die Iteration mit ZWEITE_ITERATION übergeben wird. Dabei werden die Abweichungsprüfungen nicht ausgeführt.
          * Der Arzteintrag konnte angelegt werden, aber es konnte keine ANR automatisch vergeben werden. Der Arzteintrag wurde in ein Clearing bei der Geschäftsstelle ausgesteuert.
          Alle drei Möglichkeiten werden mit dem HTTP-Statuscode 200 zurückgegeben. Im Body kann der Fall dann anhand des dort enthaltenen Status unterschieden werden.
      operationId: erzeugeArzteintrag
      parameters:
        - name: arztAnlageAnfrage
          in: body
          required: true
          schema:
            $ref: "#/definitions/ArzteintragAnlegen"
      responses:
        200:
          description: successful operation
          schema:
            $ref: "#/definitions/ArzteintragAnlegenErgebnis"
        400:
          $ref: "#/responses/invalidarguments"
        500:
          $ref: "#/responses/unknownerror"
  /arzteintrag/{anr}:
    put:
      summary: ändert einen vorhandenen Arzteintrag
      description: Aktualisiert einen vorhandenen Arzteintrag. Die ANR kann nur geändert werden, wenn die Geschäftsstelle einen Clearinghinweis mit einem ANR-Änderungsvorschlag unterbreitet hat. Die Änderung erfolgt, indem im Parameter anr die alte Nummer übertragen wird und im body die neue Nummer. Wird eine vom Vorschlag der Geschäftsstelle abweichende Nummer übertragen, resultiert dies in einen Fehler.
      operationId: aendereArzteintrag
      parameters:
        - name: anr
          in: path
          required: true
          type: string
          minLength: 7
          maxLength: 7
          description: Die ANR des zu ändernden Arztes
        - name: arztAendernAnfrage
          in: body
          required: true
          schema:
            $ref: "#/definitions/ArzteintragAendern"
      responses:
        200:
          description: successful operation
          schema:
            $ref: "#/definitions/Arzteintrag"
        400:
          $ref: "#/responses/invalidarguments"
        404:
          $ref: "#/responses/objectNotFound"
        500:
          $ref: "#/responses/unknownerror"

  /clearing:
    get:
      summary: Ermittelt alle Ärzte im Clearing
      description: Gibt eine Liste aller Ärzte zurück, die sich derzeit im Clearing befinden. Dabei wird zwischen verschiedenen Clearing-Status unterschieden. Ärzte werden z.B. durch den monatlichen Abgleich mit der ANRV und durch den Abgleich mit anderen Arzteinträgen im KHANR-VZ in eine Clearing-Status gesetzt. Der Status sowie der Fehlercode bzw. Clearinghinweis sollen direkt im Verwaltungssystem des Krankenhauses angezeigt werden.
      operationId: liesClearingAerzte
      responses:
        200:
          description: successful operation
          schema:
            type: array
            items:
              $ref: "#/definitions/ClearingArzt"
        500:
          $ref: "#/responses/unknownerror"

definitions:
  ArzteintragAnlegenStatus:
    type: string
    enum:
      - ERFOLGREICH
      - WARNUNGEN
      - CLEARING
    description: Gibt an, ob ein Arzt erfolgreich angelegt werden konnte (ERFOLGREICH), ob die Attribute noch einmal von einem Sachbearbeiter kontrolliert werden müssen, bevor sie gespeichert werden (WARNUNGEN) oder ob sich der Arzt im Clearing gespeichert wurde und von der Geschäftsstelle geprüft werden muss (CLEARING).

  ArzteintragAnlegenErgebnis:
    description: |
      Das Vorgehen beim Anlegen und die verschiedenen Möglichkeiten sind in POST /arzteintrag beschrieben. In Abhängigkeit des Status sind die folgenden Attribute gefüllt.
        * ERFOLGREICH: arzteintrag
        * WARNUNGEN: warnungen und optional korrekturvorschlag
        * CLEARING: clearinghinweise
    type: object
    required:
      - status
    properties:
      status:
        $ref: "#/definitions/ArzteintragAnlegenStatus"
      arzteintrag:
        $ref: "#/definitions/Arzteintrag"
      korrekturvorschlag:
        $ref: "#/definitions/Korrekturvorschlag"
      warnungen:
        type: array
        minItems: 1
        items:
          $ref: "#/definitions/Meldung"
      clearinghinweise:
        type: array
        minItems: 1
        items:
          $ref: "#/definitions/ClearingHinweis"

  Qualifikation:
    type: object
    required:
      - code
      - abschlussdatum
    properties:
      code:
        description: Es dürfen nur von der KBV definierte Codes verwendet werden. Es kann entweder die Kennziffer für die Gebiet-, Facharzt- und Schwerpunktkompetenz (3-Steller) oder der Fachgruppencode (2-Steller) geschickt werden. Bei der Übertragung sind zwingend führende 0en mit zu übertragen, denn es ist z.B. ein Unterschied zwischen 044 - TG Plastische Chirurgie; obsolet und 44 - Kinderneuropsychiatrie
        type: string
        minLength: 2
        maxLength: 3
      abschlussdatum:
        type: string
        format: date
        description: >-
          Datum an dem der Arzt den Farcharzttitel oder die Schwerpunktkompetenz erlangt hat.
      ende:
        type: string
        format: date
        description: >-
          Datum an dem der Facharzttitel oder die Schwerpunktqualifikation endet. Wenn der Arzt seinen ersten Facharzttitel erlangt, endet z.B. die Qualifikation 999 (Arzt in Weiterbildung). Ansonsten enden Qualifikationen nur, wenn ein Facharzttitel aberkannt wird.
  Standortzugehoerigkeit:
    type: object
    required:
      - standortnummer
      - beginn
    properties:
      standortnummer:
        description: Nach der Aktivierung des Standortverzeichnisses für ein KH, dürfen nur noch für das Krankenhaus registrierte Standortnummern übergeben werden. Vorher dürfen Standortnummern frei vergeben werden, diese müssen jedoch dem untenstehenden Pattern entsprechen.
        type: string
        minLength: 9
        maxLength: 9
        pattern: 77[0-9]{4}0[0-9]{2}
      beginn:
        type: string
        format: date
      ende:
        type: string
        format: date

  Korrekturvorschlag:
    type: object
    properties:
      anr:
        type: string
        minLength: 7
        maxLength: 7
      vorname:
        type: string
        minLength: 1
        maxLength: 255
      nachname:
        type: string
        minLength: 1
        maxLength: 255
      geburtsdatum:
        type: string
        format: date
      geschlecht:
        $ref: "#/definitions/Geschlecht"
      datumExamen:
        type: string
        format: date
      datumApprobation:
        type: string
        format: date
      drTitel:
        type: boolean
      datumErstePromotion:
        type: string
        format: date

  Arzteintrag:
    type: object
    required:
      - vorname
      - nachname
      - geburtsdatum
      - geschlecht
      - datumExamen
      - datumApprobation
      - drTitel
      - qualifikationen
      - standortzugehoerigkeiten
    properties:
      anr:
        type: string
        minLength: 7
        maxLength: 7
      vorname:
        type: string
        minLength: 1
        maxLength: 255
      nachname:
        type: string
        minLength: 1
        maxLength: 255
      geburtsdatum:
        type: string
        format: date
      geschlecht:
        $ref: "#/definitions/Geschlecht"
      datumExamen:
        type: string
        format: date
      datumApprobation:
        type: string
        format: date
      drTitel:
        type: boolean
      datumErstePromotion:
        type: string
        format: date
      qualifikationen:
        description: Es muss mindestens eine Qualifikation angegeben werden.
        type: array
        minLength: 1
        items:
          $ref: "#/definitions/Qualifikation"
      standortzugehoerigkeiten:
        description: Es muss mindestens eine Standortzugehörigkeit angegeben werden.
        type: array
        minLength: 1
        items:
          $ref: "#/definitions/Standortzugehoerigkeit"

  Geschlecht:
    type: string
    enum:
      - WEIBLICH
      - MAENNLICH
      - DIVERS
      - UNBESTIMMT
    description: Geschlecht nach Personenstandsgesetz. UNBESTIMMT sollte verwendet werden, wenn im Personenstandsregister kein Geschlecht eingetragen ist bzw. wenn im Reisepass das Geschlecht X vermerkt ist.
  AnlegenIteration:
    type: string
    enum:
      - ERSTE_ITERATION
      - ZWEITE_ITERATION
    description: Kennzeichen, in welcher Iteration der Datensatz angelegt wird. Beim ersten Aufruf muss immer ERSTE_ITERATION übertragen werden. Werden Warnungen zurückgegeben, sind diese zu prüfen. Anschließend kann ein erneuter Aufruf mit den geprüften Daten mit ZWEITE_ITERATION erfolgen.
  ArzteintragAnlegen:
    allOf:
      - $ref: "#/definitions/Arzteintrag"
      - type: object
        required:
          - iteration
        properties:
          iteration:
            $ref: "#/definitions/AnlegenIteration"
  ArzteintragAendern:
    allOf:
      - $ref: "#/definitions/Arzteintrag"
      - type: object
        properties:
          aenderungskommentar:
            type: string
            minLength: 0
            maxLength: 1501

  ClearingStatus:
    type: string
    enum:
      - CLEARING_KH
      - CLEARING_GESCHAEFTSSTELLE
      - CLEARING_GESCHAEFTSSTELLE_EXT
  ClearingHinweis:
    type: object
    required:
      - code
      - text
    properties:
      code:
        type: integer
      text:
        type: string
        maxLength: 500
  ClearingArzt:
    type: object
    required:
      - clearingStatus
      - fehler
    properties:
      anr:
        type: string
        minLength: 7
        maxLength: 7
      clearingStatus:
        $ref: "#/definitions/ClearingStatus"
      vorschlagANR:
        description: Optionale Angabe einer ANR, wenn im Clearing festgestellt wurde, dass die Daten unter der falschen ANR erfasst sind.
        type: string
        minLength: 7
        maxLength: 7
      rueckfrage:
        description: Rückfrage, die das KH im Rahmen des Clearings an die Geschäftsstelle gestellt hat
        type: string
        maxLength: 4000
      hinweis:
        description: Hinweis, den die Geschäftsstelle dem Krankenhaus übermittelt hat, um den Clearingfall zu lösen.
        type: string
        maxLength: 4000
      fehler:
        type: array
        items:
          $ref: "#/definitions/ClearingHinweis"

  Meldungslevel:
    description: Ein Fehler gibt an, dass die Aktion nicht ausgeführt wurde. Eine Warnung gibt an, dass die Aktion nicht durchgeführt wurde, aber der Verwender die Aktion durch nochmalige explizite Bestätigung durchführen kann. Ein Hinweis gibt an, dass die Aktion (ggf. leicht abweichend) ausgeführt wurde.
    type: string
    enum:
      - Hinweis
      - Warnung
      - Fehler
  Meldung:
    type: object
    required:
      - level
      - text
    properties:
      level:
        $ref: "#/definitions/Meldungslevel"
      code:
        type: string
        description: "Fehlercode"
        maxLength: 8
      text:
        type: string
        description: "Fehlermeldung"
      feldliste:
        type: array
        description: "Optionale Liste der Felder, auf die sich die Fehlermeldung bezieht"
        items:
          type: string
          description: Ein Feld wird identifiziert über den voll qualifizierten Pfad des Eingabeobjektes der API-Methode, die den Fehler ausgelöst hat, wobei die Bestandteile jeweils durch "." getrennt sind. Bei Arrays wird das i-te Objekt durch "[i]" referenziert.
