cludes API
Dieser Artikel beinhaltet die Nutzung des Application Programming Interface (kurz API) von cludes. Er soll Ihnen dabei helfen, Ihnen die Schnittstellen, die cludes Ihnen bietet, noch effizienter zu nutzen und bietet für individuelle Programme und Skripte die Möglichkeit, auf das System zuzugreifen und spezielle Aufgaben zu verrichten.

 

Allgemeine Informationen

Eine API ist eine Sammlung von Funktionen, welche Programmierer zur Verfügung stellen, um einen gewissen Zugriff auf das System zu erstellen, auch wenn der spätere Nutzer nicht weiß, wie genau die Funktion programmiert wurde oder welche Stellung sie in der Software besitzt. So ist es selbst bei Software, welche Ihre Wirkungsweise nicht offenlegt, möglich, über diese Funktionen und Schnittstellen auf das System zuzugreifen.

Man muss sich das Ganze wie ein Fernseher vorstellen: Sie wissen nicht genau, wie das Gerät im Inneren funktioniert oder aus welchen Bestandteilen es zusammengebaut wurde, aber Sie können, solange das Gerät nicht defekt ist, den Fernseher an- und ausschalten, die Lautstärke verändern, Farbeinstellungen vornehmen usw. Mit cludes verhält es sich ähnlich – Sie müssen Sie nicht darum kümmern, wie die zur Verfügung gestellten Funktionen aufgebaut sind, solange die Funktionalität gewährleistet wird.

So können Sie sich zum Beispiel eigene Programme schreiben lassen, die auf Ihre cludes-Instanz zugreifen und Daten verarbeiten. Hierfür werden jedoch zumindest marginale Programmierkenntnisse gefordert, um die Art und Weise, wie die API benutzt wird, zu verstehen.

 

Die cludes API bietet Ihnen folgende Möglichkeiten:

  • Kunden anlegen
  • Produkte anlegen
  • Kategorien anlegen
  • Produkt/Kategorie-Zuordnungen setzen
  • Bestellungen abrufen

 

 

API Freischaltung

Für die Anbindung einer neuen Schnittstelle via API schreiben Sie bitte eine E-Mail an den Support, in welcher Sie angeben um welche Schnittstelle es sich handelt. Nach Möglichkeit sollten Sie beim Support der Schnittstelle eine Schnittstellendokumentation anfragen und dem Support diese ebenfalls zukommen lassen.

 

 

 

Architektur der Schnittstelle

Die API von cludes selbst arbeitet mit URL-Requests, welche Sie, ähnlich wie ein Link in der Adresszeile Ihres Browsers eingeben können. In diesem Request werden alle Parameter, die das System braucht, um die gewünschte Aktion auszuführen, eingefügt. Nach der Angabe des Ziels wird eine Parameterliste gefordert, deren Beginn Sie mit einem Fragezeichen "?" einleiten können. Den Wert des Parameters bestimmen Sie mit einen Gleichheitszeichen "=" im Sinne einer Anweisung, wobei auf der linken Seite des Gleichheitszeichens der gewünschte Parameter steht(wird von cludes aufgelöst). Mehrere Anweisungen können über ein kaufmännisches und "&" getrennt werde. So sieht eine Psyeudo-Parameterliste aus, welche die Syntax der zu verwendenden Befehle beschreibt:

?ErsterParamter=ErsterWert&ZweiterParameter=ZweiterWert&DritterParamter=DritterWert

Diese Art der Nutzung einer URL findet man häufig in Internet-Skripten, welche dynamisch mit diesen Einstellungen eine Seite generieren sollen. So wäre es beispielsweise möglich, ein Skript zum Anzeigen eines Produktes zu erstellen, wobei das anzuzeigende Produkt in der Parameterzeile der URL angegeben wird. Zur Verarbeitung der Befehle können Sie GET- und POST-Requests nutzen, in dieser Dokumentation wird allerdings die GET-Methode präferiert, zumal die Parameterangabe in POST die Gleiche ist und sich lediglich in der Position der Angabe unterscheidet:

 

GET: https://<CLUDES-URL>/admin/?mtl=api&sid= <IhreSessionID>&do=exec_login_ses&usr_login=<IhrBenutzername>&usr_pwd=<IhrPasswort>

POST: https://<CLUDES-URL>/admin/
POST-DATA: mtl=api&sid=<IhreSessionID>&do=exec_login_ses&usr_login=<IhrBenutzername>&usr_pwd=<IhrPasswort>

 

Die Anfragen müssen an Ihre Instanz von cludes gerichtet sein und benötigen das Erstellen einer Session-ID (siehe unten) mit Ihren Zugangsdaten. Die Adresse Ihrer Instanz wird wie folgt definiert:

https://<CLUDES-URL>/admin/?mtl=api&do=<BEFEHL>

Das 'https://' gibt an, dass es sich bei der Verbindung um eine besonders sichere Variante des HTTP-Protokolls handelt, welche mit einem Zertifikat arbeitet, um die Seite zu verifizieren. Der Bezeichner "<CLUDES-URL>" bezeichnet den Namen Ihrer Instanz, welchen Sie ebenfalls beim Zugriff auf das Admin-Interface angeben, und das "mtl=api" teilt cludes mit, dass Sie eine API-Funktion aufrufen wollen. Der Bezeichner "<BEFEHL>" gibt die Aktion an, die Sie ausführen wollen.

Bevor Sie jedoch einen gültigen Befehl an Ihre Instanz schicken können, benötigen Sie eine gültige Session (auch "sid" genannt). Diese Session-ID wird generiert, sobald Sie sich auf Ihrer cludes-Instanz anmelden, und ist eine halbe Stunde nach Anmeldung gültig (wenn Sie keine Aktualisierungen, Änderungen oder Modifikationen vornehmen – ansonsten wird das Zeitfenster immer wieder auf eine halbe Stunde gesetzt). Wenn also jemand in Besitz dieser temporären Session-ID kommt, kann er mit einem entsprechenden Cookie (einer Datei, welches die Session-ID auf Ihrem Computer festhält, damit der Rechner verifiziert werden kann) ohne Anmeldung auf Ihre Instand zugreifen. Aus diesem Grund ist es nicht empfehlenswert, eine Session dauerhaft einzurichten.

 

Um eine Session-ID zu erhalten, senden Sie einfach einen Request an die Adresse:

https://<CLUDES-URL>/admin/

Worauf Ihnen folgende Antwort zurückgegeben wird:

 

Connection: close
Content-Type: text/plain; charset=iso-8859-1
Client-Response-Num: 1
Client-Transfer-Encoding: chunked
X-Session: <IhreSessionID>
Location: ?do=login_ses&sid= <IhreSessionID>

 

Sowohl das Feld "X-Session" als auch der Parameter "sid" im "Location"-Feld beinhalten Ihre gegenwärtig gültige Session-ID. Diese müssen Sie nutzen, um sich mit Ihren Zugangsdaten für weitere Befehle anzumelden. Die Zugangsdaten versenden Sie mit folgendem Befehl:

 

https://<CLUDES-URL>/admin/?mtl=api&sid= <IhreSessionID>&do=exec_login_ses&usr_login=<IhrBenutzername>&usr_pwd=<IhrPasswort>

 

Das Feld "<IhreSessionID>" muss die im vorherigen Feld abgefragte Session-ID beinhalten. Danach beginnt die Parameterangabe mit den Namen-Wertpaaren "do" und "exec_login_sec" (meldet Sie auf Ihrer cludes-Instanz an), "usr_login" und "<IhrBenutzername>" (verwendet zur Anmeldung das angegebene Konto) und "usr_pwd" und "<IhrPasswort>" (verwendet zur Anmeldung das angegebene Passwort). Bei erfolgreicher Anmeldung wird Ihnen cludes eine Antwort nach folgendem Schema senden:

 

Connection: close
Location: ?sid=<
IhreSessionID>
Content-Length: <Variable Länge des Requests, muss nicht beachtet werden>
Content-Type: text/html; charset=iso-8859-1
Client-Response-Num: 1
Title: 302 Found

 

Falls die Anmeldung jedoch fehlschlug, versucht Ihre Instanz, den Browser auf die normale Admin-Anmeldeseite zu bringen. In diesem Fall wird im "Location"-Feld der Befehl "do=login_ses" ausgeführt, sodass Sie diesen Wert abfragen können, um ein Fehlschlagen der Anmeldung zu überprüfen:

 

Connection: close
Location: ?
do=login_ses&sid=<IhreSessionID>
Content-Length: <Variable Länge des Requests, muss nicht beachtet werden>
Content-Type: text/html; charset=iso-8859-1
Client-Response-Num: 1
Title: 302 Found

 

Wenn die Anmeldung erfolgreich war, können Sie nun weitere Befehle an Ihre Instanz senden.

 

 

Dokumentierte API-Funktion

In diesem Abschnitt werden Ihnen einige Befehle, die oft in cludes genutzt werden, aufgelistet und beschrieben:

  • adm_logout_ex: Schließt die gegenwärtige Session. Diese Funktion können Sie nutzen, um nach einer Reihe von Anweisungen an die Schnittstelle den Zugang wieder zu sperren.

  • wsa_add_ex: Legt einen Werkstattauftrag an.

  • wsa_mod_ex: Modifiziert einen Werkstattauftrag.

  • kdn_mod_ex: Modifiziert einen Kunden.

  • kdn_add_ex: Legt einen Kunden an (siehe auch kdn_import_ex).

  • boni_change_ex: Ändert die Bonität eines Kunden.

  • pdt_add_ex: Legt ein Produkt an.

  • pdt_mod_ex: Modifiziert ein Produkt.

  • pdt_verpacken_ex: Verpackt einen Artikel in einer Bestellung.

  • gru_add_ex: Legt eine Preisgruppe an.

  • gru_mod_ex: Modifiziert eine Preisgruppe.

  • trl_mod_ex: Modifiziert Übersetzungen für Produkte und CLUDES-Shop.

  • bta_add_ex: Legt einen Auktionsagent.

  • bta_mod_ex: Modifiziert einen Auktionsagent.

  • pers_add_ex: Fügt einen Kunden für eine manuelle Bonitätsprüfung hinzu.

  • vdg_add_ex: Legt eine eBay-Versandgruppe an.

  • vdg_mod_ex: Modifiziert eine eBay-Versandgruppe.

  • lie_add_ex: Legt einen Lieferanten an.

  • lie_mod_ex: Modifiziert einen Lieferanten.

  • kat_add_ex: Legt eine Kategorie an.

  • kat_mod_ex: Modifiziert eine Kategorie.

  • sst_add_ex: Legt eine Schnittstelle an, wenn möglich.

  • sst_mod_ex: Modifiziert die Schnittstellenkonfiguration.

  • grp_add_ex: Legt eine Rechtegruppe an.

  • grp_mod_ex: Modifiziert eine Rechtegruppe.

  • bhk_add_ex: Legt einen Belegnummernkreis an.

  • bhk_mod_ex: Modifiziert einen Belegnummernkreis.

  • ods_list: Legt eine Bestellung an. Der Parameter 't' kann hierbei folgende Werte annehmen:
    • 'new': Erstellt eine neue Bestellungen ohne Freigabe.
    • 'paid': Erstellt eine bezahlte oder zumindest freigegebene Bestellungen.
    • 'finish': Erstellt eine abgeschlossene Bestellungen.
    • 'storn': Erstellt eine stornierte Bestellungen.
    • 'nachnahme_bestaetigt': Erstellt eine Bestellung, deren Nachnahme bestätigt wurde.
    • 'nachnahme_unbestaetig': Erstellt eine Bestellung, deren Nachname nicht bestätigt wurde.
    • 'v_bereit': Erstellt eine versandbereite Sendungen.
    • 'im_versand': Erstellt eine noch nicht zugestellte Sendungen im Versand.
    • 'problemfaelle': Erstellt eine als Problemfall markierte Bestellungen.
    • 'zeitueberschreitung': Erstellt eine Bestellung, die 5 Tage nach Freigabe noch noch nicht versandfertig ist.
    • 'zahlstorn': Erstellt eine Sendungen mit Rücklastschrift.
    • 'faelligkeit': Erstellt eine Bestellung mit Rechnung als Zahlungsart.
    • 'offene_rechnungen': Erstellt eine offene Rechnungen.
  • kdn_import_ex: Importiert Kunden. Siehe KundenImport

  • pdt_import_ex: Importiert Produkte. Siehe ProduktImport

  • kat_import_ex: Importiert Kategorien. Siehe KategorieImport

  • kdn_dump_db_csv_ex: Exportiert nach Wunsch bestimmte Kundendaten in eine CSV-Datei. Sie können die gewünschten Spalten durch die wiederholte Angabe des Parameters "kdn_csv_spalten" mit dem jeweiligen Tabellenfeld beim Request definieren. Falls Sie also nur Namen und Kundennummer aus der CLUDES-Datenbank in eine CSV-Datei geschrieben bekommen wollen, lautet der Request:

    https://<CLUDES-URL>/admin/?mtl=api&do=kdn_dump_db_csv_ex&tabelle=kdn&kdn_csv_spalten=kdn&kdn_csv_spalten=kdn_name&kdn_csv_spalten=kdn_vname.

    Unter KundenTabelle finden sie die zulässigen Tabellenüberschriften.

  • kat_dump_db_csv_ex: Exportiert nach Wunsch bestimmte Kategoriedaten in eine CSV-Datei. Sie können die gewünschten Spalten durch die wiederholte Angabe des Parameters 'kat_csv_spalten' mit dem jeweiligen Tabellenfeld beim Request definieren. Falls Sie also nur den Namen, das Datum der Erstellung und die Kategorienummer aus der CLUDES-Datenbank in eine CSV-Datei geschrieben bekommen wollen, lautet der Request:

    https://<CLUDES-URL>/admin/?mtl=api&do=kat_dump_db_csv_ex&tabelle=kat&kat_csv_spalten=kat&kat_csv_spalten=kat_name&kat_csv_spalten=kat_date_create


Unter KategorieTabelle finden sie die zulässigen Tabellenüberschriften.

  • pdt_dump_db_csv_ex: Exportiert nach Wunsch bestimmte Kategoriedaten in eine CSV-Datei. Sie können die gewünschten Spalten durch die wiederholte Angabe des Parameters 'pdt_csv_spalten' mit dem jeweiligen Tabellenfeld beim Request definieren. Falls Sie also nur den Namen, das Datum der Erstellung und die Kategorienummer aus der CLUDES-Datenbank in eine CSV-Datei geschrieben bekommen wollen, lautet der Request:

    https://<CLUDES-URL>/admin/?mtl=api&do=pdt_dump_db_csv_ex&tabelle=pdt&pdt_csv_spalten=pdt&pdt_csv_spalten=pdt_name&pdt_csv_spalten=pdt_hersteller

    Unter ProduktTabelle finden sie die zulässigen Tabellenüberschriften.

  • pdt_sellercentral_ex: Produkt-Attribute für Amazon hinterlegen

  • ods_send: Abruf einer Liste alle freigegebener Aufträge, für welche Rechnungen oder Labels ausgedruckt werden können. Ohne Optionen wird eine Liste von mit Anführungszeichen umrahmten Bestellnummern zurückgeliefert. Es können zusätzliche Optionen angegeben werden:
    Parameter:

    'fc=label': Die Liste beinhaltet Bestellnummern druckbarer Versandlabels,

    'fc=gls_labels': Wird direkt über die GLS-Box abgefragt - nur wenn Sie GLS als Versanddienstleister nutzen und selbst eine GLS-Unibox betreiben.

    'loc=in' oder loc=out': Gilt beim Ausdrucken von Tourenaufträgen und wird zusammen mit dem Parameter count=8 oder count=60 verwendet. Das System druckt wahlweise Inlandsaufträge oder Auslandsaufträge (Standardmäßig wird Inland als Deutschland angesehen) in jeweils 8er Blöcken oder 60ziger Blöcken, zusätzlich werden die Lieferscheine bei einem Warenwert von unter EUR 20,- mit dem Hinweis "Warensendung" versehen.

    • 'v=2': Variante 2 vom Drucktool, statt nach Bestellnummer werden die Rechnungen nach Pack-ID gespeichert, wobei die Pack-ID als Parameter mit übertragen wird (gilt nicht bei Tourenplanung).

 

 

 

Herausfinden eigener Befehle

Die Liste der zu verwendenden Funktionen ist lang und muss in diesem Dokument nicht vollständig sein. Für den Fall, dass Sie eine Funktion benötigen, die zwar in cludes vorhanden ist, diese aber nicht gelistet wird, können Sie eigene API-Befehle herauszufinden und dokumentieren. Allerdings benötigten Sie für diesen Vorgang den Internetbrowser "Mozilla Firefox" (ein freier und kostenloser Browser mit Plugin-Unterstützung und zahlreichen Einstellungsmöglichkeiten) und das Plugin "Live HTTP Headers". Dieses Plugin läuft im Hintergrund von Firefox und registriert jeden Request/Response, welcher an den Browser geht oder von dort kommt. Diese Mitschnitte werden Ihnen dann angezeigt, zusammen mit dem verwendeten Befehl.

Nachdem Sie den Browser mit dem Plugin installiert haben, melden Sie sich mit diesem an Ihrer cludes-Instanz an und navigieren zu der Funktion, welche sie ausgeführt wissen wollen, führen diese jedoch noch nicht aus. Starten Sie dann das Plugin "HTTP-Headers" über die Menüleiste Ihres Browsers ("Extras" → "HTTP-Headers"), löschen Sie eventuell vorhandene Mitschnitte und setzen Sie den Haken in das Kästchen "Mitschneiden". Führen Sie dann die Funktion aus, warten Sie, bis diese ausgeführt wurde, und lassen sich den Inhalt des HTTP-Headers anzeigen (Sie können diesen auch mit einem Klick auf die Schaltfläche "Alles speichern" sichern). Am Anfang des Mitschnitts können Sie nun die Art des Requests "GET" oder "POST" und in dem Feld "form_frame_name" links neben dem Gleichheitszeichen den Request selbst betrachten. Diese Funktion können Sie nun mit einem "mtl=api&do=<IhreErmittelteFunktion>" in der URL aufrufen.