.. include:: globals.txt

Allgemeines
=========================


Verschlüsselung
--------------------------

Die Kommunikation mir dem |connectcentername| erfolgt verschlüsselt über das
**https** Protokoll (Server-Side-Certificat).


.. _auth:

Authentifizierung
-------------------

Die Authentifizierung im |connectcentername| erfolgt per Anmeldung mit UserID und Passwort beim API-Aufruf :ref:`gettoken`. Sie liefert einen Token, der für alle weitere Kommunikation mit dem |connectcentername| erforderlich ist.

Sollte die Authentifizierung mit dem |connectcentername| fehlschlagen, wird grundsätzlich der Errorcode **401** zurückgegeben. Zusätzlich werden im Requestbody noch weitere Informationen zur fehlgeschlagenen Authentifizierung ausgegeben.

============================== ======================================================
Infotext                       Erläuterung
============================== ======================================================
**missing param token**        In der Anfrage wurde kein Token mitgeschickt.
**token is unknown**           Die Token-ID ist dem |connectcentername| nicht bekannt.
**token timeout**              Die Session des Tokens ist abgelaufen. Es muss ein Neues Token angefordert werden.
============================== ======================================================

.. _token:

Token
---------

.. _gettoken:

getToken
`````````

Erzeugt einen Token für die Kommunikation mit dem |connectcentername|. Der Token ist eine 64 Zeichen lange hexadezimale Zeichenkette (SH256 Hashkey).

============================= ================================
Aufruf         					|connecturl|/getToken/
============================= ================================
Methoden       					**GET**
Rückgabe        				64 Zeichen langer String
============================= ================================

\ 
\ 

============= =========
**Parameter**
============= =========
**id**         Name des Users im |connectcentername|
**password**   Passwort des Users    
============= =========

\ 
\ 

Mögliche Fehlerrückgaben
'''''''''''''''''''''''''

\ 
\ 

========= ============================== ======================================================
**Code**  Infotext                       Erläuterung
========= ============================== ======================================================
**400**   **missing params**             Parameter *id* und/oder *password* wurden nicht übergeben
**409**   **unknown user**               User mit entsprechenden *id* nicht bekannt.
**403**   **password wrong**             User konnte nicht authentifiziert werden.
========= ============================== ======================================================

Der Token ist bis zu einer Stunde nach der letzten Kommunikation mit dem Center über dieses Token gültig. Bei jedem Aufruf einer Funktion des Connect Centers muss dieser Token mitgeführt werden (Parameter “token”). 



Beispiel
'''''''''''''


Anfrage
...............

.. literalinclude:: tests/outputs_single/getToken.in


Rückgabe
...............

.. literalinclude:: tests/outputs_single/getToken.out


Nutzerkennung
--------------------------

.. _getusers:

getConnectUsers
````````````````

Für die Kommunikation mit einem Connect User, wird dessen ID im |connectcentername| benötigt. Eine Liste der vorhandenen User kann man über den Befehl **getConnectUsers** bekommen. Die id des Users steht im *id* Tag. Sie verändert sich für einen User nicht.
 
============================= ================================
Aufruf         					|connecturl|/getConnectUsers/
============================= ================================
Methoden       					**GET**
Rückgabe        				XML-Liste der User (encoding: utf-8)
============================= ================================


\ 
\ 

Mögliche Fehlerrückgaben
'''''''''''''''''''''''''

\ 
\ 

========= ============================== ======================================================
**Code**  Infotext                       Erläuterung
========= ============================== ======================================================
**401**   *...*                          |autherrors|
========= ============================== ======================================================



Beispiel
'''''''''''''

Anfrage
...............

.. literalinclude:: tests/outputs_single/getConnectUsers.in


Rückgabe
...............


.. literalinclude:: tests/outputs_single/getConnectUsers.out
   :language: xml
   :lines: 1-17
   :append: ...   
   :encoding: utf-8

Aktivität
--------------------------

getProtocols
````````````````

Ruft ab, welche Aktionen im Konto des Users in einem gegebenen Zeitraum ausgeführt wurden
 
============================= ================================
Aufruf         					|connecturl|/getProtocols/
============================= ================================
Methoden       					**GET**
Rückgabe        				XML-Liste der Aktionen (encoding: utf-8)
============================= ================================

\ 
\ 

============= =========
**Parameter**
============= =========
**fromDate**   Datum, ab dem das Protokoll beginnen soll, optional,  Format: "DD.MM.JJJJ" bzw. "DD.MM.JJJ HH:MM" (z.B. 01.01.2013 13:00). Uhrzeit ist im 24h Format und optional.
**toDate**     Datum, bei dem das Protokoll enden soll, optional, Format wie fromDate
============= =========

\ 
\ 

Mögliche Fehlerrückgaben
'''''''''''''''''''''''''

\ 
\ 

========= ============================== ======================================================
**Code**  Infotext                       Erläuterung
========= ============================== ======================================================
**401**   *...*                          |autherrors|
========= ============================== ======================================================



Beispiel
'''''''''''''

Anfrage
...............

.. literalinclude:: tests/outputs_single/getProtocols.in


Rückgabe
...............

.. literalinclude:: tests/outputs_single/getProtocols.out
   :language: xml
   :lines: 1-50
   :append: ...
   :encoding: utf-8