at.chipkarte.client.auth.soap

## Interface IAuthService

-     public interface IAuthService

  Dieses Service stellt Funktionen für die Authentifizierung von Vertragspartnern sowie für die Dialogverwaltung (Auf-/Abbau) zur Verfügung.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `DialogData` | `authenticateDialog(String cardToken, ProduktInfo produktInfo, String extUID, Boolean pushMessageEnabled)` Durch diese Funktion wird ein Dialog erzeugt und authentifiziert.
    `DialogData` | `authenticateDialogEnt(ProduktInfo produktInfo, String extUID, String vpNummer, Boolean pushMessageEnabled)` Durch diese Funktion wird ein (Enterprise-)Dialog erzeugt und authentifiziert.
    `void` | `closeDialog(String dialogId)` Diese Funktion beendet einen aufgebauten Dialog.
    `void` | `setDialogAddress(String dialogId, String ordinationId, String taetigkeitsBereichId, String elgaRolle, GdaMa gdaMa, String prozess)` Diese Funktion ordnet dem Dialog eine Ordinationsadresse zu.

- - ### Method Detail

    - #### authenticateDialog

          DialogData authenticateDialog(String cardToken,
                                        ProduktInfo produktInfo,
                                        String extUID,
                                        Boolean pushMessageEnabled)
                                 throws DialogException,
                                        ServiceException

      Durch diese Funktion wird ein Dialog erzeugt und authentifiziert.
      Diese Authentifizierung erfolgt durch Prüfen des Admin-Card-Tokens sowie bei verfügbarer Serververbindung durch die Verifikation der enthaltenen VP-Signatur sowie einer Gültigkeitsprüfung der zur Erstellung verwendeten Karte.
      Dabei wird auch geprüft, ob die maximale Anzahl der Dialoge pro Ordinationsclient überschritten wurde und dadurch kein weiterer Dialogaufbau möglich ist.

      Voraussetzung:

      - Es wurde ein gültiger Admin-Card-Token unter Angabe der VP-Nummer und der PIN der o-card erstellt.

      Laufzeitgruppe: Mittel

      Replayability: Nein

      Parameters:
        `cardToken` - Mit Ordinationskarte und PIN erzeugtes VP-Signaturtoken (im Gegensatz zu einem SV-Signaturtoken, welches keine PIN benötigt).
        Angabe: Muss
        `produktInfo` - Informationen der Software, die diese Schnittstelle implementiert
        Angabe: Muss
        `extUID` - UserID vom externen System (z.B. KIS) (pseudonym/Klartext), optional
        `pushMessageEnabled` - Kennzeichen, ob die Abfrage neuer Nachrichten über den Push- bzw. Poll-Mechanismus erfolgt. Wenn true übergeben wird oder das Kennzeichen nicht gesetzt ist, dann können die Nachrichten nur mit der Funktion getMessages() abgefragt werden. Bei false können nur mit pollMessages() die Nachrichten abgefragt werden.
      Returns:
        Daten zum neu erstellten, authentifizierten Dialog (inklusive dessen ID, die als Referenz dieses Dialogs in anderen Funktionen dient).
      Throws:
        `ServiceException` - `INTERNAL_ERROR`, `CONNECTION_ERROR`, `INCOMPATIBILITY_EXCEPTION`
        `DialogException` - `SIGNATURE_INVALID`, `CARD_INVALID`, `TOO_MANY_OPEN_DIALOGS_FOR_OR_CLI`, `OCARD_GINA_MISMATCH`, `EXT_UID_INVALID`, `PRODUKTINFO_INVALID`, `CARDTOKEN_REQUIRED`, `CARDTOKEN_INVALID`, `CARDTOKEN_EXPIRED`, `CARDTOKEN_TYPE_NOT_ALLOWED`, `CARDTOKEN_SIG_TYPE_NOT_ALLOWED`, `HERSTELLERID_INVALID`, `HERSTELLERID_REQUIRED`, `HERSTELLERID_UNKNOWN`, `HERSTELLERID_DISABLED`, `SIGNATURE_ALREADY_USED`

    - #### authenticateDialogEnt

          DialogData authenticateDialogEnt(ProduktInfo produktInfo,
                                           String extUID,
                                           String vpNummer,
                                           Boolean pushMessageEnabled)
                                    throws DialogException,
                                           ServiceException

      Durch diese Funktion wird ein (Enterprise-)Dialog erzeugt und authentifiziert.
      Die Signatur mit SW-Zertifikat wird für die Authentifizierung im Request-Header übergeben.
      Es wird ebenfalls geprüft, ob die maximale Anzahl der Dialoge pro Ordinationsclient überschritten wurde und dadurch kein weiterer Dialogaufbau möglich ist.

      Voraussetzung:

      - Die Signatur mit SW-Zertifikat ist im Message Header des authenticateDialogEnt Requests gesetzt.

      Laufzeitgruppe: Mittel

      Replayability: Nein

      Parameters:
        `produktInfo` - Informationen der Software, die diese Schnittstelle implementiert
        Angabe: Muss
        `extUID` - UserID vom externen System (z.B. KIS) (pseudonym/Klartext), optional
        `vpNummer` - Vertragspartnernummer
        Angabe: Muss
        `pushMessageEnabled` - Kennzeichen, ob die Abfrage neuer Nachrichten über den Push- bzw. Poll-Mechanismus erfolgt. Wenn true übergeben wird oder das Kennzeichen nicht gesetzt ist, dann können die Nachrichten nur mit der Funktion getMessages() abgefragt werden. Bei false können nur mit pollMessages() die Nachrichten abgefragt werden.
      Returns:
        Daten zum neu erstellten, authentifizierten Dialog (inklusive dessen ID, die als Referenz dieses Dialogs in anderen Funktionen dient).
      Throws:
        `ServiceException` - `INTERNAL_ERROR`, `CONNECTION_ERROR`, `INCOMPATIBILITY_EXCEPTION`
        `DialogException` - `TOO_MANY_OPEN_DIALOGS_FOR_OR_CLI`, `INVALID_CERTIFICATE`, `NO_SIGNATURE`, `NO_VPNR_NUMBER`, `CERTIFICATE_PROBLEM_OCARD_DIALOG_REQUIRED`, `PARAMETER_MISMATCH_EXCEPTION`, `CERTIFICATE_TIMESTAMPS_INVALID`, `CERTIFICATE_TIMESTAMP_INTERVAL_INVALID`, `CERTIFICATE_REQUEST_OUT_OF_DATE`, `CERTIFICATE_SIGNATURE_ALGORITHM_INVALID` `EXT_UID_INVALID`, `PRODUKTINFO_INVALID`, `INVALID_VPNR_FORMAT`, `HERSTELLERID_INVALID`, `HERSTELLERID_REQUIRED`, `HERSTELLERID_UNKNOWN`, `HERSTELLERID_DISABLED`, `SIGNATURE_ALREADY_USED`, `DIALOG_CURRENTLY_USED`

    - #### setDialogAddress

          void setDialogAddress(String dialogId,
                                String ordinationId,
                                String taetigkeitsBereichId,
                                String elgaRolle,
                                GdaMa gdaMa,
                                String prozess)
                         throws DialogException,
                                ServiceException

      Diese Funktion ordnet dem Dialog eine Ordinationsadresse zu.

      Voraussetzung:

      - Funktion `authenticateDialog`/`authenticateDialogEnt` wurde erfolgreich ausgeführt

      Laufzeitgruppe: Mittel

      Replayability: Nein

      Parameters:
        `dialogId` - Dialog-Id, siehe `DialogData.getDialogId()`
        `ordinationId` - Identifiziert eine Ordination, die dem Dialog zugeordnet werden soll (siehe `Ordination.getOrdinationId()` in `DialogData.getDialogId()`)
        `taetigkeitsBereichId` - Identifiziert einen Tätigkeitsbereich, der dem Dialog zugeordnet werden soll (siehe `TaetigkeitsBereich.getId()` in `DialogData.getDialogId()`)
        `elgaRolle` - ELGA-Rolle des Vertragspartners
        Angabe: Kann
        Format: Code aus dem ELGA-Valueset "ELGA_Rollen_VS" (maximal 8-stellig)
        `gdaMa` - Informationen zum GDA-Mitarbeiter
        Angabe: Bei Angabe von `elgaRolle` muss entweder `gdaMa` oder `prozess` angegeben werden. Ansonsten ist keine Angabe erlaubt.
        `prozess` - Informationen zum durchführenden, automatisierten Prozess (z.B. Batch)
        Angabe: Bei Angabe von `elgaRolle` muss entweder `gdaMa` oder `prozess` angegeben werden. Ansonsten ist keine Angabe erlaubt.
        Format: maximal 250-stellig
      Throws:
        `ServiceException` - `INTERNAL_ERROR`, `CONNECTION_ERROR`, `INCOMPATIBILITY_EXCEPTION`
        `DialogException` - `DIALOG_CANCELED`, `DIALOG_INVALID`, `DIALOG_TIMEOUT`, `ADDRESS_ALREADY_SET`, `ORDINATION_ID_INVALID`, `TOO_MANY_OPEN_DIALOGS_FOR_OR_CLI`, `DIALOG_UNKNOWN`, `ORDINATION_ID_UNKNOWN`, `CORRUPT_DIALOGID`, `ELGAROLLE_WRONG_FORMAT`, `GDAMA_OR_PROZESS_WITHOUT_ELGAROLLE_NOT_ALLOWED`, `GDAMA_OR_PROZESS_REQUIRED`, `GDAMA_TITEL_VORNE_WRONG_FORMAT`, `GDAMA_VORNAME_WRONG_FORMAT`, `GDAMA_NACHNAME_WRONG_FORMAT`, `GDAMA_TITEL_HINTEN_WRONG_FORMAT`, `GDAMA_VORNAME_NACHNAME_REQUIRED`, `GDAMA_ZUSATZINFO_WRONG_FORMAT`, `PROZESS_WRONG_FORMAT`, `ELGAROLLE_INVALID`, `MULTIPLE_DIALOGID`, `DIALOG_CURRENTLY_USED`

    - #### closeDialog

          void closeDialog(String dialogId)
                    throws DialogException,
                           ServiceException

      Diese Funktion beendet einen aufgebauten Dialog.

      Voraussetzung:

      - Funktion `authenticateDialog`/`authenticateDialogEnt` wurde erfolgreich ausgeführt.

      Laufzeitgruppe: Mittel

      Replayability: Nein

      Parameters:
        `dialogId` - Dialog-Id des Dialogs, der geschlossen werden soll, siehe `DialogData.getDialogId()`.
      Throws:
        `ServiceException` - `INTERNAL_ERROR`, `INCOMPATIBILITY_EXCEPTION`
        `DialogException` - `DIALOG_INVALID`, `DIALOG_TIMEOUT`, `TOO_MANY_OPEN_DIALOGS_FOR_OR_CLI`, `DIALOG_UNKNOWN`, `ORDINATION_ID_UNKNOWN`, `CORRUPT_DIALOGID`, `INVALID_TRANSACTION_ID`, `MULTIPLE_DIALOGID`, `DIALOG_CURRENTLY_USED`