CC Simple Portal API

Version: 1.0
Kunde: KomMITT
Datum: 30.01.2015

1. Einführung

Mit dier API können im Backendsystem Nutzer für den Zugriff auf das Portal (Kundenexklusivbereich) sowie erweiterte Leistungen (z.B. Mail, Cloud) angelegt werden.

2. Server und Syntax der Aufrufe

Die URL für den Zugriff auf die API lautet:

URL: https://api04.ccgmbh.de/kommitt/ccsimplemailapi/

Die Aufrufe werden generell in der Form:

http(s)://server/apiDescription/package/additional_parameter/..

vorgenommen. Beispiele für die einzelnen Funktionsaufrufe befinden sich im weiteren Verlauf der Beschreibung.

Die API liefert bei Anfragen die Antworten in JSON zurück. Alternativ kann XML als Ausgabeformat gewählt werden. Hierzu muss der HTTP Header Force-XML: true gesetzt werden.

Beispiele:
JSON Aufruf

root@server: /> curl -k --header https://api04.ccgmbh.de/kommitt/ccsimplemailapi/mail/10953/list

{
"ParCustId":"10953",
"accounts":
        [
                {
                "account":
                    {
                     "mail":"10953@rapeedo.net",
                     "type":"TYPE_PRIMARY",
                     "forward":null
                    }
                }
        ]
}
XML Aufruf

root@server: /> curl -k --header "Force-XML: true" https://api04.ccgmbh.de/kommitt/ccsimplemailapi/mail/10953/list

<?xml version="1.0"?>
<response>
    <ParCustId>10953</ParCustId>
    <accounts>
        <account>
            <mail>10953@rapeedo.net</mail>
            <type>TYPE_PRIMARY</type>
            <forward/>
        </account>
    </accounts>
</response>

Allgemeine Informationen

Wird ein HTTP Responsecode OK/200 zurückgegeben gilt der Requests als erfolgreich. Message Body ist dabei optional. Wenn dieser jedoch angegeben ist handelt es sich im Content-Type text/xml mit dem root Node response sofern XML-Force: true gesetzt wurde. Ansonsten wird ein Content-Type text/json zurückgegeben.

Wird ein anderer Responsecode als OK/200 zurückgegeben handelt es sich um einen Fehler. Eine optionale Fehlerbeschreibung wird im Message Body als text/plain geliefert.

3. Funktionen

Folgende Packages stehen zur Vefügung:

Aufrufe:

https://server/apiDescription/mail/..
https://server/apiDescription/access/..
https://server/apiDescription/packs/..

4. Workflows

Aktivierung
    Kunde initialsieren      - https://server/apiDescription/access/12345/enable/098f6bcd4621d373cade4e832627b4f6

    Hinzufügen eines Packets - https://server/apiDescription/pack/12345/enable/mail/5
Deaktivierung
    Deaktivieren des Packets   - https://server/apiDescription/pack/12345/disable/mail/5

    Deaktivieren des Accounts  - https://server/apiDescription/access/12345/disable
Portal Passwort Reset
    Zurücksetzen des Passworts - https://server/apiDescription/access/12345/enable/098f6bcd4621d373cade4e832627b4f6

5. Access (ProvPortalAccess)

Die Sequenznummern in der authentication.ProvPortalAccess Tabelle werden über diese API verwaltet. Ein Tracking von Sequenznummern auf der Client Seite ist nicht notwendig.

Wenn die jeweilge ParCustId noch in PENDING stehende Requests besitzten sollte, so wird beim Auflisten der eingerichteten Packete das dirty Flag auf true gesetzt sein.

In diesem Fall werden auch sämtliche Änderungen an dieser ParCustId verweigert.

Auflistung des aktuellen Status

Aufruf: http://HOST/ccSimpleMailApi/access/PARCUSTID/status
Beispiel: http://192.168.10.170/ccSimpleMailApi/access/Cust01/status

<response>
  <ParCustId>Cust01</ParCustId>
  <found>true</found>
  <enabled>true</enabled>
    <!-- Nutzer hat Passwort geändert -->
  <pwdchanged>1</pwdchanged>
  <dirty>false</dirty>
</response>
Einrichten/Update der Portaldaten

Aufruf: http://HOST/ccSimpleMailApi/access/PARCUSTID/enable/HASH

Parameter:

** Passwörter werden immer als MD5 Hash übergeben

Deaktivieren eingerichteter Portaldaten

Aufruf: http://HOST/ccSimpleMailApi/access/PARCUSTID/disable

6. Funktionen im Package Mail

Auflistung aller eingerichteten Mailadressen

Aufruf: http://HOST/ccSimpleMailApi/mail/PARCUSTID/list
Beispiel: http://192.168.10.170/ccSimpleMailApi/mail/10038892/list

<response>
  <ParCustId>10038892</ParCustId>
  <accounts>
    <account>
      <mail>10038892@example.com</mail>
      <type>TYPE_PRIMARY_FORWARD</type>
      <forward>wreiti@example.com</forward>
    </account>
    <account>
      <mail>wolfgang.reitmeier@example.com</mail>
      <type>TYPE_ADDITIONAL</type>
      <forward/>
    </account>
    <account>
      <mail>wreiti@example.com</mail>
      <type>TYPE_ADDITIONAL</type>
      <forward/>
    </account>
  </accounts>
</response>

Dabei sind für type folgende Werte möglich:

7. Funktionen im Package Packs (ProvPortalPacks)

Die Sequenznummern in der authentication.ProvPortalPacks Tabelle werden über diese API verwaltet. Ein Tracking von Sequenznummern auf der Client Seite ist nicht notwendig.

Wenn die jeweilge ParCustId noch in PENDING stehende Requests besitzten sollte, so wird beim Auflisten der eingerichteten Packete das dirty Flag auf true gesetzt sein.

In diesem Fall werden auch sämtliche Änderungen an dieser ParCustId verweigert.

Auflistung aller eingerichteten Packete

Aufruf: http://HOST/ccSimpleMailApi/pack/PARCUSTID/list
Beispiel: http://192.168.10.170/ccSimpleMailApi/pack/14056/list

<response>
  <ParCustId>14056</ParCustId>
  <dirty>false</dirty>
  <packs>
    <pack>
      <name>Mail</name>
      <value>3</value>
    </pack>
    <pack>
      <name>Web</name>
      <value>100M</value>
    </pack>
  </packs>
</response>
Aktivieren eines Packetes

Aufruf: http://HOST/ccSimpleMailApi/pack/PARCUSTID/enable/PACK/VALUE

Deaktivieren eines Packetes

Aufruf: http://HOST/ccSimpleMailApi/pack/PARCUSTID/disable/PACK/VALUE

Die Kombination /PACK/VALUE ist im Fall von eMail Einrichtungen:

PACK = mail (Aktiviert Mailadressen für den Kunden)

VALUE = 5 (Legt die Anzahl der aktivierbaren Postfächer fest)

Kontaktadresse bei Rückfragen oder Problemen

tickets@ccgmbh.de

Communication Concept GmbH
Theklaer Str. 42
04347 Leipzig

Tel: +49 341 23405100
Fax: +49 341 23405190