Beschreibung der Schnittstelle

Inhaltsverzeichnis

  1. Generelle Funktionsweise und Aufruf
  2. Validieren von Usernamen
  3. API Kontostandsabfrage
  4. Primeraauszahlung
  5. Kontostand eines Users abfragen
  6. Primeraeinzahlung

Generelle Funktionsweise und Aufruf

Zur Verwendung der Schnittstelle muss ein verifizierter API Account vorliegen. Die Schnittstelle arbeitet mit einfachen HTTP POST- oder GET-Anfragen über eine URL der folgenden Struktur: 

https://www.primeraportal.de/api/handler/HANDLER.(json|xml)

Die Handler werden in den nachfolgenden Abschnitten genauer definiert. Je nachdem, welche Dateieendung der Handler bekommt, liefert die Rückgabe entweder ein JSON- oder ein XML Dokument zurück. Die Rückgabewerte, und die Rückgabestruktur unterscheiden sich jedoch nicht.

Bei jeder Anfrage muss der Usernamen und das Primera-Passwort (nicht das LOGIN-Passwort)des API Accounts mittels der Parameter username und password übermittelt werden. Das Primera-Passwort ist hierbei nicht im Klartext, sondern als MD5-Hash zu übertragen. Ein Aufruf, der den Kontostand als XML Dokument zurückliefert lautet dementsprechend: 

https://www.primeraportal.de/api/handler/get-primera.xml?username=APIUser&password=098f6bcd4621d373cade4e832627b4f6

Die Rückgabe hat generell immer die folgende Struktur (im PHP Syntax):

array(
    "success" => 1,     // 0 if error occured
    "handlername" => array(
        "some" => 321,
        "data" => 123,
    )
)

Im Fehlerfall wird neben einem Fehlercode auch stets eine knappe Fehlerbeschreibung übertragen, so dass Probleme schnell lokalisiert werden können.

Validieren von Usernamen

Um beispielsweise bei einer Auszahlung den Usernamen bei PrimeraPortal validieren zu können, bieten wir einen Usernamen-Validier-Handler an, der über folgende URL aufrufbar ist:

https://www.primeraportal.de/api/handler/check-user.(json|xml)

Der zu prüfende Username wird hierbei als check_username Parameter an den Handler übergeben. Die Rückgabe beinhaltet den Userstatus status. Dieser ist entweder active, inactive oder not-found. Ein Fehler mit dem Code 201 beschreibt einen zu kurzen übergebenen Usernamen (mindestens 2 Zeichen).

Eingabeparameter Beschreibung
username Username des API Accounts
password MD5-Hash des API-Schnittstellenpassworts
check_username Der zu überprüfende Username 
{"success":1,
 "check-user":{
    "username":"username",
     "status":"active"}}
                    
<response>
    <success>1</success>
    <check-user>
        <username>username</username>
        <status>active</status>
    </check-user>
</response>

API Kontostandsabfrage

Der Kontostand des API Accounts kann über den folgenden Handler abgefragt werden:

https://www.primeraportal.de/api/handler/get-primera.(json|xml)

Hierbei müssen keine weiteren Parameter übergeben werden.

Eingabeparameter Beschreibung
username Username des API Accounts
password MD5-Hash des API-Schnittstellenpassworts 
{"success":1,
 "get-primera":{
     "primera":"48017.00"}}
                    
<response>
    <success>1</success>
    <get-primera>
        <primera>48017.00</primera>
    </get-primera>
</response>

Primeraauszahlung

Für eine automatisierte Primeraauszahlung kann der folgende Handler verwendet werden:

https://www.primeraportal.de/api/handler/pay.(json|xml)

Hierbei muss der Empfängerusername als receiver übermittelt werden. Der Betreff subject muss mindenstens 2 Zeichen lang sein, und als UTF-8-String urlencoded übermittelt werden, damit die Sonderzeichen korrekt angezeigt werden. Die Höhe der Überweisung wird mit dem Parameter primera festgelegt. Es können die folgenden Fehlercodes zurückgegeben werden:

301 Der Empfänger ist fehlerhaft (oder nicht aktiv)
302 Nicht genügend Primera auf dem API Account
303 Der übermittelte Betrag ist fehlerhaft
304 Beschreibung zu kurz
Eingabeparameter Beschreibung
username Username des API Accounts
password MD5-Hash des API-Schnittstellenpassworts
subject Betreff
receiver Empfänger Username
primera Primeramenge 
{"success":1,
 "pay":{
    "receiver":"receiver","primera":48017.00}}
                
<response>
    <success>1</success>
    <pay>
        <receiver>receiver</receiver>
        <primera>48017.00</primera>
    </pay>
</response>

Kontostand eines Users abfragen

Mit diesem Handler kann der Kontostand eines Nutzers abgefragt werden, um beispielsweise vor einer Einzahlung den Betrag zu überprüfen. Die URL für diesen Handler lautet:

https://www.primeraportal.de/api/handler/get-user-primera.(json|xml)

Übergeben werden muss hierbei lediglich der Username und das Primerapasswort des Users mit den Parametern user_username und user_primera_password. Das Primerapasswort ist hier wieder als md5-Hash zu übertragen. Mögliche Rückmeldungen im Fehlerfall sind hierbei:

501 Der API Account besitzt nicht genug Rechte für eine Kontostandsabfrage
502 Der Username ist zu kurz
503 Die Daten des Users sind fehlerhaft
Eingabeparameter Beschreibung
username Username des API Accounts
password MD5-Hash des API-Schnittstellenpassworts
user_username Username des Users
user_primera_password Primerapasswort des Users als MD5 Hash übertragen 
{"success":1,
 "get-user-primera":{
    "primera":48017.00}}
                
<response>
    <success>1</success>
    <get-user-primera>
        <primera>48017.00</primera>
    </pay>
</response>

Primeraeinzahlung

Die Primeraeinzahlung ist nur für freigeschaltete API Accounts verfügbar. Die URL für diesen Handler lautet:

https://www.primeraportal.de/api/handler/deposit.(json|xml)

Hierbei wird der Betrag primera vom PrimeraPortal-User from abgezogen, und dem API Account gutgeschrieben. Hierzu muss das Primerapasswort des Users mit dem Parameter primera_password übertragen werden. Mögliche Fehlermeldungen sind:

401 Primerapasswort / Username falsch
402 Der User besitzt nicht genügend Primera
403 Der Betrag ist fehlerhaft
404 Beschreibung zu kurz
405 API Account ist nicht für Einzahlungen freigeschaltet
Eingabeparameter Beschreibung
username Username des API Accounts
password MD5-Hash des API-Schnittstellenpassworts
subject Betreff
from Username
primera Primeramenge
primera_password md5-Hash des Primerapassworts 
{"success":1,
 "deposit":{
    "amount":"1234","username":"username"}}
                
<response>
    <success>1</success>
    <deposit>
        <amount>1234</amount>
        <username>48017.00</username>
    </pay>
</response>