Mit unserer integrierten API-Schnittstelle können Sie nicht nur neue Vertriebspartner, Kunden und Bestellungen anlegen, sondern auch bestehende Daten modifizieren. Diese Lektion bietet Ihnen eine technische Übersicht über diese Schnittstelle, die Ihnen als Grundlage dient.
In der Entwicklungsumgebung werden mehrere Musterdateien integriert, die Ihnen als Ausgangspunkt für diverse Prozesse dienen. Diese direkt einsetzbaren Beispiele können Sie unmittelbar in Ihrer Umgebung nutzen und sie entsprechend Ihren Abläufen modifizieren.
Inhaltsverzeichnis
Sie müssen immer zwei Parameter im JSON-Format per POST an „/wbo /api/request/run“ übergeben.
Im ersten Array übergeben Sie API-Schlüssel (Hash) wie unter Prunkt 1 beschrieben, um sich an der API unserer Software zu autorisieren.
Im zweiten Array übergeben Sie die Daten mit Inhalten des Vertriebspartners und Auftrages wie unter Punkt 2 beschrieben.
1. Allgemeine Informationen.
URL API: host/wbo /api/request/run
Daten werden an die API als POST übergeben.
M – Pflichtfeld (Mandatory)
O – Optional (Optional)
Sie müssen immer zwei Parameter im JSON-Format übergeben.
A. Сonnection:
Beschreibung von dem Array «connection»
| Feld | Pflicht oder optional | Typ | Beschreibung |
| websiteId | M | string(256) | Identifizierung von dem Client |
| hash | M | string(256) | hash Abfrage |
| Action | M | string(256) | Name der API – Aufgabe |
B. Variable mit Daten (Die Bezeichnung ist von der Art der Aufgabe abhängig, die folgend näher beschrieben sind.)
Nach der Ausführung liefert die API Antwort im JSON-Format mit zwei Variablen.
- connection – Allgemeine Informationen
- response – Detaillierte Information (abhängig von der Art der Aufgabe)
Beschreibung des allgemeinen Teils der Serverantwort (Array „connection“
| Feld | Typ | Beschreibung |
| responseCode | Int | Status der API-Antwort 1 = Aufgabe erfolgreich abgeschlossen. Ansonsten Fehlercode. |
| stamp | string | Datum und Uhrzeit der Anfrage |
| responseStatus | Kurze Textmeldung mit Status | |
| responseMessage | Ausführliche Meldung. |
Die Meldungen müssen immer auf die Fehler geprüft werden. Außer 1 darf keine andere Antwort ignoriert werden.
2. Hash erzeugen.
Alle API-Anfragen werden verschlüsselt. Um Hash zu bekommen, ist es notwendig die Anfrage in folgender Reihenfolge zu generieren.
hashString = “websiteId.action.variables.APISecureCode”
websiteId, APISecureCode = API – Zugangsdaten
Action = Name der API – Aufgabe
Variables = Liste aller Variablen (Format „Variable = Wert“) alphabetisch sortiert
In PHP sieht die Funktion für das Erzeugen von „variables“ könnte wie folgt aussehen.
public function getHashString($data){
$hashstr = „“;
foreach($data as $key => $val){
if(is_array($data[$key])){
$hashstr.=$this->getHashString($val);
} else {
$hashstr.=$val;
}
}
return $hashstr;
}
Hash-Wert erhalten Sie wie folgt.
Hash= md5(hashString)
3. Neuen User (Vertriebspartner, Kunde) registrieren.
Name der Aufgabe – user
Name der Variablen mit Daten – user
Beschreibung von dem Array «user»
| Feld | Pflichtfelder | Typ | Beschreibung |
| username | M | string(256) | Benutzername |
| password | O | string(256) | Passwort |
| webname | O | string(256) | Der Text für Affiliate-Link |
| M | string(256) | Email des Benutzers | |
| usertype | M | string(256) | Typ des zu erstellenden Benutzers 0 = Nur Benutzer 1 = Kunde 2 = Vertriebspartner |
| number | O | string(256) | Externe Vertriebspartner-Nummer, die auf allen Belegen angezeigt wird. |
| language | O | string(2) | Schreibweise der Sprache „de“ oder „en“ Falls Sie weitere Sprachen wünschen, teilen uns das bitte mit. Wir werden diese in Ihrem Projekt aktivieren. Sonst kommt eine Fehlermeldung. |
| agentid | O | string(256) | Vermittler Nr. |
| birthday | O | string(10) | Geburtsdatum des Benutzers im Format dd.mm.YYYY |
| reference | O | string(256) | Benutzer-Nummer aus der externen Quelle. Nach dieser Nummer kann künftig Kommunikation zwischen unsere und der Quelldatenbank erfolgen. |
| taxId | O | string(256) | Steuernummer |
| paypalemail | O | string(256) | Das Feld für die zweite E-Mail-Adresse in den Vertriebspartnerdaten |
| adresses | O | Array | Array mit der Adressdaten des Benutzers. |
| bank | O | Array | Array mit Bankdaten. |
Beschreibung von dem Array «adresses»
| Feld | Pflicht | Typ | Beschreibung |
| primaryAdress | M | Int | 1 = Immer übergeben |
| typeAdress | M | Int | 1 = Immer übergeben |
| company | string(256) | Firmenname | |
| salutation | string(256) | Anrede 0 = Firma 1 = Herr 2 = Frau | |
| firstName | string(256) | Vorname | |
| lastName | string(256) | Nachname | |
| street | O | string(256) | Straße |
| country | O | string(2) | Land. Zwei Buchstaben ISO-Code (z.B. de) |
| town | O | string(256) | Ort |
| postCode | O | string(256) | PLZ |
| phone | O | string(256) | Telefon |
| Mobile | O | string(256) | Mobil |
| additionalPhone | O | string(256) | Telefon 2 |
| fax | O | string(256) | Telefax |
| O | string(256) | ||
| skype | O | string(256) | Skype |
Beschreibung des Arrays «bank»
| Feld | Pflicht | Typ | Beschreibung |
| primaryBank | M | Int | 1 = Immer übergeben |
| typeBank | M | Int | 1 = Immer übergeben |
| IBAN | M | string(256) | |
| BIC | M | string(256) |
Beschreibung des Arrays «response» – Antwort des Servers
| Feld | Typ | Beschreibung |
| internemitarbeiternr | Int | Internet Nr. des angelegten Vertriebspartners |
| mitarbeiternr | Int | Externe Nr. des angelegten Vertriebspartners. (Nummer, die er kennt) |
| internekdnr | string(256) | Internet Nr. des angelegten Kunden |
| kundennr | string(256) | Externe Nr. des angelegten Kunden. (Nummer, die er kennt) |
| uid | Internet Nr. des angelegten Benutzers |
4. Bestellung anlegen.
Name der Aufgabe – orderCreate
Name der Variablen mit Daten – orderCreate
Beschreibung des Arrays «orderCreate»
| Feld | Pflichtfeld | Typ | Beschreibung |
| buyerId | M | Int | Kundennummer. In unserer Warenwirtschaft existieren zwei Kundennummern. tb_kundendaten.internekdnr = ist eine interne Nummer, die unsere Warenwirtschaft für alle Berechnungen verwendet. Wen Sie diese Nummer kennen, können Sie diese hier verwenden. tb_kundendaten.kundennr = In diesem Textfeld befindet sich die Kundenummer, die nach außen auf allen Belegen angezeigt wird. Um diese externe Nummer in der API an dieser Stelle zu übergeben müssen Sie folgende Schreibweise verwenden index:10002 anstatt 10002 tragen Sie die Kundennummer ein. |
| paymentMethod | M | Int | Nummer der Zahlungsart |
| shippingMethod | M | Int | Nummer der Versandart |
| orderItems | M | Array | Liste aller Produkte und Pakete aus der Bestellung |
| invoiceaddress | O | Array | Rechnungsadresse |
| shippingddress | O | Array | Lieferadresse |
| bank | O | Array | Bankdaten |
Beschreibung des Arrays «orderItems»
| Feld | Pflicht | Typ | Beschreibung |
| product | O | Array | Liste der Produkte |
| package | O | array | Liste der Pakete |
Beschreibung des Arrays «product»
| Feld | Pflicht | Typ | Beschreibung |
| id | O | Int | Auftragsnummer aus der externen Quelle für die Verbindung. |
| productId | M | Int | Artikelnummer |
| quantity | M | Decimal | Menge |
| sortorder | O | Int | Reihenfolge für die Sortierung |
Beschreibung der Arrays «invoiceaddress» und «shippingddress»
| Feld | Pflicht | Typ | Beschreibung |
| company | string(256) | Firmenname | |
| salutation | string(256) | Anrede: 0 – Firma 1 – Herr 2 – Frau | |
| firstName | string(256) | Vorname | |
| lastName | string(256) | Nachname | |
| street | O | string(256) | Straße |
| country | O | string(2) | Land. Zwei Buchstaben ISO-Code (z.B. de) |
| town | O | string(256) | Ort |
| postCode | O | string(256) | PLZ |
| phone | O | string(256) | Telefon |
| mobile | O | string(256) | Mobil |
| fax | O | string(256) | Telefax |
| O | string(256) |
Beschreibung des Arrays «bank»
| Feld | Pflicht | Typ | Beschreibung |
| IBAN | M | string(256) | IBAN |
| BIC | M | string(256) | BIC |
Beschreibung des Arrays «response» – Antwort des Servers
| Feld | Typ | Beschreibung |
| cartId | Int | Warenkorb-Nummer |
| hash | string(256) | Hash-Code des Warenkorbes |
5. User (Vertriebspartner, Kunde) ändern.
Name der Aufgabe – userUpdate
Name der Variablen mit Daten – userUpdate
Array «userUpdate» enthält die gleichen Daten wie auch beim Anlegen eines Users zusätzlich kommen folgenden Variablen dazu.
| Feld | Pflicht | Typ | Beschreibung |
| reference | M | string(256) | Benutzer-Nummer für die Identifikation des Users in Abhängigkeit von «referenceType». |
| referenceType | M | string(256) | Mögliche Identifikations-Typen «reference» = Benutzer-Nummer aus der externen Quelle, falls beim Anlegen des Users angegeben.«uid» im Feld „reference“ übergeben Sie unsere interne Nummer des Users“internekdnr” im Feld „reference“ übergeben Sie unsere interne Kunden–Nummer.«internemitarbeiternr» im Feld „reference“ übergeben Sie unsere interne Vertriebspartner–Nummer. «KundenNr» im Feld „reference“ übergeben Sie Kunden–Nummer die nach außen auf allen Belegen angezeigt wird.«MitarbeiterNr» im Feld „reference“ übergeben Sie Vertriebspartner–Nummer die nach außen auf allen Belegen angezeigt wird. |
6. Zahlungseingang verbuchen
Bezeichnung der Anfrage: orderPaymentEecute
Bezeichnung des Datenarrays mit Variablen: orderPaymentEecute
Bestellungen, die Sie mit API angelegt haben, können mit dieser Funktion als bezahlt markiert werden. Bei einer Bestellung handelt es sich um einen Warenkorb, der aus mehreren Bestellpositionen zusammengesetzt werden kann.
Mit dieser Anfrage verbuchen Sie den Zahlungseingang für eine Bestellung.
Reicht das Geld aus, um die ganze Bestellung zu bezahlen, wird diese Bestellung komplett als bezahlt markiert.
Reicht das bezahlte Geld nicht aus, wird diese Bestellung nur zum Teil bezahlt.
Beschreibung des Datenarrays «orderPaymentEecute»
| Feld | Pflicht | Typ | Beschreibung |
| hash | M | string(32) | Beim Anlegen der Bestellung haben Sie als Antwort eindeutigen hash – Wert zurückerhalten. Diesen Wert müssen Sie jetzt angeben, um die Bestellung identifizieren zu können. |
| sum | M | Decimal | Bezahlter Betrag (Wert muss größer als 0 sein) |
| currency | M | Int | Währungsindex |
| paymentdate | M | string(10) | Zahlungsdatum im dd.mm.yyyy Format |
| invoiceId | O | Int | Rechnungsnummer, wenn bekannt. Damit vermeiden Sie Missverständnisse in dem Mahnwesen. |
| accountId | O | Int | Index der Buchhaltungs-Kontonummer. Im Office müssen Sie in diesem Fall zuerst die Konten einrichten. |
Als Antwort bekommen Sie eine Standard-Antwort mit dem Status der Ausführung.
Im Falle eines Fehlers bekommen Sie die detaillierte Beschreibung des Fehlers.
