API-Grundlagen

Über die Digistore24-API können externe Anwendungen auf Ihr Digistore24-Konto zugreifen. Diese Seite ist die technische Dokumentation zur API und für Sie nur interessant, falls Sie Anwendungsentwickler sind.

1. Die Digistore24-API

Die Digistore24-API ermöglicht Ihren Anwendungen, Daten – wie z.B. eine Liste von Produkten oder Bestellungen – auszulesen. Je nach Zugriffsberechtigung können auch Daten verändert werden – z.B. Bestellungen storniert werden. Der Zugriff erfolgt mittels des API-Schlüssels des Benutzers Ihrer Anwendung per HTTP.


2. API-Schlüssel

Für den Zugriff auf die Digistore24-API benötigen Sie einen API-Schlüssel. Um einen API-Schlüssel zu erstellen, gehen Sie wie folgt vor:

Der API-Schlüssel wird dann angezeigt. Es ist eine lange Buchstaben-Zahlen-Kombination wie z.B.:

123-iKWIrTsUTbCyrFuotOdV8yO20nfMI5bbrZhDCUAG

Für jeden API-Schlüssel können Sie eines der folgenden Zugriffsrechte festlegen:

  • readonly = Lesezugriff: Mit dem Schlüssel können keine Änderungen am  Konto vorgenommen werden. Es können aber Informationen abgerufen werden, wie z.B. Umsätze oder Details zu einer Bestellung.
  • writable = Vollzugriff: Änderungen am Konto sind möglich, wie z.B. das Stornieren einer Bestellung. Es können – wie beim Lesezugriff auch – Informationen abgerufen werden.
  • developer = Entwicklerschlüssel: Mit diesem Schlüssel kann Ihre App für Ihre Benutzer API-Schlüssel erstellen. Siehe die Kapitel API-Schlüssel interaktiv erstellen. Ein Lese- oder Vollzugriff ist mit diesem Schlüssel nicht möglich. Sie können den Entwicklerschlüssel im Quellcode Ihrer App veröffentlichen.


3. PHP-Klasse

Wir haben eine PHP-Klasse und einige Beispiele für Sie vorbereitet.

Dies können Sie hier herunterladen: https://www.digistore24.com/download/package/digistore-api.zip

Alle Funktionen, die Sie per Digistore24-API aufrufen können, finden Sie in der API-Referenz.

Die PHP-Klasse ist auch mit zukünftigen Versionen der DigiStore24-API kompatibel. D.h. auch wenn die Digistore24-API erweitert wird, können Sie die jetzige Version der PHP-Klasse verwenden.


4. Javascript-API

Einen API-Connector in Javascript können Sie hier herunterladen: https://www.digistore24.com/download/package/digistore-js-api.zip

Auch dieser Connector funktioniert mit allen Funktionen der API-Referenz.

Hinweis: API-Schlüssel, die mit der Javascript-API verwendet werden, sind leicht einzusehen. Verwenden Sie deshalb clientseitig nur Entwicklerschlüssel mit der Javascript-API.


5. HTTP-Aufruf

Falls Sie die obige PHP-Klasse verwenden, können Sie diesen Abschnitt überspringen.

Um die API ohne PHP-Klasse zu verwenden, führen Sie HTTP-Aufrufe an folgende URL durch:

https://www.digistore24.com/api/call/APIKEY/FORMAT/FUNCTION

Dabei ersetzen Sie:

  • APIKEY: Ihr Digistore24-API-Schlüssel
  • FORMAT: ‚json‚, ‚xml‘, ‚php‘ (siehe unserialize()) oder ‚text‘
  • FUNCTION: Funktionsname – siehe API-Referenz

Sie können Funktionsargumente als GET- oder POST-Parameter übergeben.


Beispiel für einen Funktionsaufruf

Es soll folgender Funktionsaufruf durchgeführt werden:

  • resendPurchaseConfirmationMail( ‚X26QE8GN‘ )

Dann ist die URL beispielsweise:

https://www.digistore24.com/api/call/123-iKWIrTsUTbCyrFuotOdV8yO20nfMI5bbrZhDCUAG/json/resendPurchaseConfirmationMail?purchase_id=X26QE8GN

Als Antwort gibt der Server ein Text-Dokument zurück mit beispielsweise folgendem Inhalt:

{„api_version“:“1.234″,“current_time“:“2014-03-14 17:30:08″,“result“:“success“,“data“:{„modified“:“Y“,“note“:“Die Best\u00e4tigungsmail wurde verschickt.“}}

Die Antwort ist hier ein Datensatz im JSON-Format.

Im Erfolgsfall erhalten Sie ein Objekt mit folgenden Feldern:

  • api_version – die (serverseitige) Version der Digistore24-API, z.B. 1.234.
  • result – „success“.
  • data – Datenobjekt, das die aufgerufene Funktion zurückgegeben hat.

Im Fehlerfall erhalten Sie ein Objekt mit folgenden Feldern:

  • api_version – die (serverseitige) Version der Digistore24-API, z.B. 1.234.
  • result – „error“.
  • message – die Fehlermeldung.
  • code – ein Fehlercode.

Nummerierte oder benannte Parameter

Wenn Sie die Funktionsargumente als POST- oder GET-Parameter übergeben, können Sie wählen:

  • Sie übergeben die Parameter mit nummerierten Namen: arg1, arg2, arg3 usw. Dies ist hilfreich, falls Sie einen generischen Adapter für die API entwickeln, wie z.B. die oben erwähnte PHP-Klasse.
  • Oder Sie verwenden die benannten Namen aus der API-Referenz, z.B. purchase_id, transaction_id usw. Dies erhöht die Lesbarkeit Ihres Quellcodes.

Arrays als Parameter

Einige Funktionen (wie createBuyUrl()) erwarten Arrays als Funktionsargumente.

Beispiel: Sie möchten folgenden Array übergeben:

buyer = array(
name   => Udo,
email  => uw@ds24mail.com
)

Dann übergeben Sie die Daten des Array folgendermaßen:

…&buyer[name]=Udo&buyer[email]=uw@ds24mail.com

oder bei nummerierten Parametern

…&arg1[name]=Udo&arg1[email]=uw@ds24mail.com


Allgemeine Parameter

Abgesehen von den ggf. akzeptierten Parametern arg1/arg2/… können immer folgende Parameter übergeben werden:

  • language: ‚de‘ oder ‚en‘ – Sprache für die Meldungen der API. Standardmäßig wird die Sprache des Digistore24-Kontos verwendet, zu dem der API-Schlüssel gehört.
  • operator: string – Name eines Verantwortlichen für die Änderungen, die per API-Aufruf im Digistore24 gemacht werden. Dies wird nur für die Protokollierung verwendet, sodass Sie nachvollziehen können, welcher User Ihrer Anwendung z.B. eine Zahlung storniert hat.

Weiterentwicklung der API

Wir werden die API in Zukunft weiterentwickeln. Dabei werden wir die Abwärtskompatibilität erhalten.

Folgende Änderungen werden wir unangekündigt durchführen:

  • Wir fügen neue Funktionen zur API hinzu.
  • Bestehende Funktionen erhalten zusätzliche Funktionsargumente, die optional sind (sodass ihre bestehende Software weiter funktioniert).
  • Texte und Fehlermeldungen können sich im Wortlaut ändern. Beispielsweise könnten sich die Klartext-Bezeichungen für den Bestellstatus ändern (d.h. der Rückgabewert von billing_status_msg) – die internen Bezeichnungen (der Wert von billing_status) werden sich nicht ändern, höchstens um neue Werte ergänzt werden.
  • Die Antworten des Servers erhalten zusätzliche Datenfelder (die Ihre Anwendung ignorieren kann).
  • Die API-Version wird sich ändern.

Bitte gestalten Sie Ihre Anwendung so, dass sie mit diesen Änderungen sofort und ohne Änderungen am Sourcecode klarkommt. Ansonsten wird es passieren, dass Ihre Anwendung in Zukunft nicht mehr ordentlich funktioniert.

Folgende Dinge ändern sich nicht:

  • die Namen der Funktionen und die vorhandenen Funktionsargumente.
  • die API-URL sowie der gesamte Mechanismus des API-Zugriffs.
Aktualisiert am 16. Oktober 2018

War dieser Artikel hilfreich?

Relevante Artikel