Converter Scripts

Mit Hilfe der integrierten Template-Engine Smarty können flexibel zeichenbasierte Ausgabestrukturen von Datenformaten wie CSV, XML oder JSON an die Bedürfnisse des Kunden angepasst werden. Es muss lediglich das vorhandene Zielformat in eine Textdatei kopiert und mit den entsprechenden Variablen gefüllt werden. Diese können dabei noch umformatiert werden.

Belegdaten befinden sich z.B. in der Smarty-Variable $beleg und werden in gewohnter PHP-Objektschreibweise angesprochen, z.B. $beleg->kundennummer oder $beleg->belegnr. Die Namensgebung gleicht der Benennung von Datenbank-Spaltennamen. Auch ein Zugriff auf komplexere Strukturen ist je nach Beleg möglich. So kann im Lieferschein auf den zugrundeliegenden Auftrag zugegriffen werden: $beleg->auftrag->lieferdatum.

Verkürztes Beispiel mit fiktivem Format

<?xml version="1.0" encoding="utf-8"?>
<lieferschein>

         {* Beleg-Stammdaten -------------------------------- *} 
         <status>{$beleg->status}</status>
         <datum>{$beleg->datum|date_format:'%d.%m.%Y'}</datum>
         <belegnummer>{$beleg->belegnr}</belegnr>
         <kundennummer>{$beleg->kundennummer}</kundennummer>
         <kundenname>{$beleg->name}</kundenname>

         {* Zugriff auf Daten des zugrundeliegenden Auftrages *} 
         <lieferdatum>{$beleg->auftrag->lieferdatum}</lieferdatum>
         {* Weitere Felder entfernt *} 

         {* Positionen - Beginn ------------------------------ *} 
         <positionen>

                {* Schleife durchläuft alle verfügbaren Positionen *} 
                {foreach from=$beleg->positionen key=keypos item=position}
                <position>
                        <artikelnummer>{$position->nummer}</artikelnummer>
                        <artikelbezeichnung>{$position->bezeichnung}</artikelbezeichnung>
                        <artikelbeschreibung>{$position->beschreibung}</artikelbeschreibung>
                        <menge>{$position->menge}</menge>
                        <preis>{$position->preis}</preis>
                        <ean>{$position->articledata->ean}</ean>
                        {* Weitere Felder entfernt *} 
                 </position>
                {/foreach}

        </positionen>
        {* Positionen - Ende -------------------------------- *} 
</lieferschein>

Über die übermittelten Daten hinaus, kann auch auf zusätzliche Daten, z.B. aus den Artikelstammdaten, zugegriffen werden. Diese sind über das Objekt articledata referenzierbar, wie im obigen Beispiel durch die EAN dargestellt. Alle Spalten der Artikeltabelle sind über diese Notation ansprechbar, also z.B. auch die Freifelder des Artikels, die im Auftrag selbst ggf. mit anderen Werten belegt sein können.

Im Folgenden sind einige Beispiele zusammengefasst, die die Ausgabe verschiedener Lieferscheinformate in den Formaten EDI, CSV und XML ermöglichen. Dabei sind die Spaltenbeschriftungen (CSV), Tagnamen (XML) und EDI-Spezifikationen zu prüfen. Weitere Ausgabeformate wie z.B. JSON sind denkbar.

- wird ergänzt -

{foreach from=$beleg->positionen key=keyrow item=position}{* Positionen *}\
"{$position->tracking}";\
"{$beleg->status}";\
"{$beleg->datum|date_format:'%d.%m.%Y'}";\
"{$beleg->lieferdatum}";\
"{$beleg->tatsaechlicheslieferdatum}";\
"{$beleg->versandart}";\
"{$beleg->zahlungsweise}";\
"{$beleg->belegnr}";\
"{$beleg->hauptbelegnr}";\
"{$beleg->kundennummer}";\
"{$beleg->name}";\
"{$beleg->abteilung}";\
"{$beleg->unterabteilung}";\
"{$beleg->adresszusatz}";\
"{$beleg->ansprechpartner}";\
"{$beleg->telefon}";\
"{$beleg->email}";\
"{$beleg->land}";\
"{$beleg->strasse}";\
"{$beleg->plz}";\
"{$beleg->ort}";\
"{$beleg->projekt}";\
"{$beleg->aktion}";\
"{$beleg->internebemerkung}";\
"{$beleg->internebezeichnung}";\
"{$beleg->freitext}";\
"{$beleg->ihrebestellnummer}";\
"{$beleg->lieferbedingung}";\
"{$beleg->art}";\
"{$position->nummer}";\
"{$position->bezeichnung}";\
"{$position->beschreibung}";\
"{$position->menge|string_format:'%.2f'}";\
"{$position->preis}";\
"{$position->rabatt}";\
"{$position->waehrung}";\
"{$position->lieferdatum}";\
"{$position->sort}";\
"{$position->umsatzsteuer}";\
"{$position->einheit}";\
"{$position->zolltarifnummer}";\
"{$position->herkunftsland}";\
"{$position->artikelnummerkunde}";\
"{$beleg->auftrag->lieferdatum}";\
"{$position->freifeld1}";\
"{$position->freifeld2}";\
"{$position->freifeld3}";\
{* Ggf. weitere Freifelder *}";\
"{$position->freifeld40}";\

{/foreach}

<?xml version="1.0" encoding="utf-8"?>
<lieferschein>

        <status>{$beleg->status}</status>
        <datum>{$beleg->datum|date_format:'%d.%m.%Y'}</datum>
        <lieferdatum>{$beleg->lieferdatum}</lieferdatum>
        <tatsaechlicheslieferdatum>{$beleg->tatsaechlicheslieferdatum}</tatsaechlicheslieferdatum>
        <versandart>{$beleg->versandart}</versandart>
        <zahlungsweise>{$beleg->zahlungsweise}</zahlungsweise>
        <belegnr>{$beleg->belegnr}</belegnr>
        <hauptbelegnr>{$beleg->hauptbelegnr}</hauptbelegnr>
        <kundennummer>{$beleg->kundennummer}</kundennummer>
        <name>{$beleg->name}</name>
        <abteilung>{$beleg->abteilung}</abteilung>
        <unterabteilung>{$beleg->unterabteilung}</unterabteilung>
        <adresszusatz>{$beleg->adresszusatz}</adresszusatz>
        <ansprechpartner>{$beleg->ansprechpartner}</ansprechpartner>
        <telefon>{$beleg->telefon}</telefon>
        <email>{$beleg->email}</email>
        <land>{$beleg->land}</land>
        <strasse>{$beleg->strasse}</strasse>
        <plz>{$beleg->plz}</plz>
        <ort>{$beleg->ort}</ort>
        <projekt>{$beleg->projekt}</projekt>
        <aktion>{$beleg->aktion}</aktion>
        <internebemerkung>{$beleg->internebemerkung}</internebemerkung>
        <internebezeichnung>{$beleg->internebezeichnung}</internebezeichnung>
        <freitext>{$beleg->freitext}</freitext>
        <ihrebestellnummer>{$beleg->ihrebestellnummer}</ihrebestellnummer>
        <lieferbedingung>{$beleg->lieferbedingung}</lieferbedingung>
        <art>{$beleg->art}</art>
        <positionen>

        {foreach from=$beleg->positionen key=keypos item=position}
                <position>
                <nummer>{$position->nummer}</nummer>
                <bezeichnung>{$position->bezeichnung}</bezeichnung>
                <beschreibung>{$position->beschreibung}</beschreibung>
                <menge>{$position->menge}</menge>
                <preis>{$position->preis}</preis>
                <rabatt>{$position->rabatt}</rabatt>
                <waehrung>{$position->waehrung}</waehrung>
                <lieferdatum>{$position->lieferdatum}</lieferdatum>
                <sort>{$position->sort}</sort>
                <umsatzsteuer>{$position->umsatzsteuer}</umsatzsteuer>
                <einheit>{$position->einheit}</einheit>
                <zolltarifnummer>{$position->zolltarifnummer}</zolltarifnummer>
                <herkunftsland>{$position->herkunftsland}</herkunftsland>
                <artikelnummerkunde>{$position->artikelnummerkunde}</artikelnummerkunde>
                <freifeld1>{$position->freifeld1}</freifeld1>
                <freifeld2>{$position->freifeld2}</freifeld2>
                <freifeld3>{$position->freifeld3}</freifeld3>
                {* Ggf. weitere Freifelder *} 
                <freifeld40>{$position->freifeld40}</freifeld40>
        </position>
 {/foreach}

        </positionen>
        {if $beleg->versand}
{foreach from=$beleg->versand key=keyversand item=tracking} {* Versand *}
        <tracking>{$tracking->tracking}</tracking>
{/foreach}
{/if}
</lieferschein>

- wird ergänzt -

- wird ergänzt -

- wird ergänzt -

- wird ergänzt -

- wird ergänzt -

- wird ergänzt -

- wird ergänzt -

- wird ergänzt -

- wird ergänzt -

Bei xentral wird großer Wert auf die Anbindung sowie die automatische Verarbeitung von Bestellungen in Online-Shops gelegt. Daher bietet xentral Schnittstellen zu diversen Shops an. Obwohl fast jeder Shop eine Schnittstelle besitzt, treten manchmal Probleme mit der Kompatibilität der anzubindenden Schnittstellen auf. Ein Importer, der als Adapter zwischen xentral und der Online-Shops-Schnittstelle dient, kann entwickelt werden. Dieser tritt als Middleware auf und übersetzt die Daten der Bestellungen aus dem Shop in ein Format, aus dem xentral wiederum Aufträge erstellen kann. Umgekehrt ist der Importer auch dafür zuständig, den Bestellstatus, Artikeldaten und Lagerzahlen an den Shop zu übertragen.

Der Ablauf innerhalb des Importers folgt immer einem festen Schema. Wenn bspw. Aufträge aus dem Shop abzuholen sind, wird zunächst geprüft, ob eine Verbindung zur Shop-Schnittstelle besteht. Anschließend wird ermittelt ob bzw. wie viele Aufträge im Shop abgeholt werden sollen. Wenn es Aufträge zur Abholung vorhanden sind, werden diese importiert und anschließend im Shop als „In Bearbeitung“ markiert. Wenn Artikel aus dem Shop importiert oder in den Shop exportiert werden, gilt ein ähnliches Schema. Zunächst erfolgt die Prüfung, ob eine Verbindung zwischen xentral und dem Shop besteht, anschließend werden die Daten übertragen.

Es ist die vorgegebene Struktur einzuhalten, wenn ein Importer geschrieben wird. Einige Punkte sind im Vorfeld festzulegen:

Es sind alle Voraussetzungen zu erfüllen: Zunächst ist die Funktion ImportAuth() zu verwenden. Im externen Importer ist diese Funktion für die Authentifizierung von xentral zum Importer notwendig, in internen Importern prüft die Funktion den Verbindungsaufruf zur API. Da diese Funktion jedes Mal aufgerufen wird, wenn der Importer in Aktion treten soll, liegt hier eine Anfrage oder ein Mechanismus zum Erstellen eines Tokens zugrunde. Wichtig ist dabei die Rückgabe von success, um mitzuteilen, dass der Importer bereit ist, Anweisungen entgegenzunehmen und an die Shop API weiterzuleiten.

public function ImportAuth()
{
        $params = ['limit' => 1];
        $responseJson  =$this->call('articles','GET',null, $params);
        $response = json_decode($responseJson,true);

        if($response['success']){
                return 'success';
        }

        return '';
}

Die Funktion ImportSendListLager() wird zusätzlich hinzugefügt. Wenn die Option für das Übertragen von Lagerzahlen in den Importeinstellungen aktiviert ist, führt diese Funktion zu einer Synchronisation der Bestände im Shop mit den Beständen in xentral. In diesem Beispiel geschieht das über die Artikelnummer. Es ist zu beachten, dass für diese Funktion im data-Parameter des Importer-Objekts die Daten für den zu aktualisierenden Artikel vorhanden sind.

public function ImportSendListLager()
{
        $updatedArticles = 0;
        $tmp = $this->CatchRemoteCommand('data');
        foreach ($tmp as $article){
                $nummer = $article['nummer'];
                $lageranzahl = $article['anzahl_lager'];

                $updateInStock = [
                        'mainDetail' => [
                'inStock' => $lageranzahl
                        ]
                ];

                $params = [
                        'useNumberAsId'=>true
                ];

                $result = $this->call('articles/'.$nummer, 'PUT',$updateInStock, $params);
                if($result['success']){
                        $updatedArticles++;
                }
        }
        return $updatedArticles;
}

Die Funktion ImportSendList() ist eine Version von ImportSendListLager(). Diese Funktion überträgt Artikel an den Shop bzw. aktualisiert deren Daten. So können Artikeleigenschaften oder Bilder an den Shop übertragen werden. Von der jeweiligen Shop-Schnittstelle hängt ab, wie und welche Daten übertragen werden können.

Es sollte auf die Trennung der beiden Funktionen geachtet werden, da ImportSendList nur in zwei Fällen aufgerufen wird:

In der Funktion ImportGetAuftraegeAnzahl wird ermittelt, wie viele offene Bestellungen im Shop vorhanden sind und abgeholt werden müssen. Denkbar ist das Abholen über den Status, ab einer bestimmten Bestellnummer oder aber auch über das Bestelldatum. Je nach Shopschnittstelle sind nicht alle Optionen realisierbar.

public function ImportGetAuftraegeAnzahl()
{
        $result = $this->getOrders($this->data);

        return count($result['data']);
}

Die wichtigste Grundfunktion aller Importer ist das Abholen und Übersetzen der Bestellungen aus dem Shop in das Warenkorbformat von xentral. Nachdem die Bestellung von der Shop API abgeholt wurde, werden im ersten Schritt die Adressdaten des Kunden an den Warenkorb übergeben:

$cart['anrede'] = 'herr';
$cart['strasse'] = $order['data']['billing']['street'];
$cart['plz'] = $order['data']['billing']['zipCode'];
$cart['ort'] = $order['data']['billing']['city'];
$cart['land'] = $order['data']['billing']['country']['iso'];
$cart['email'] = $order['data']['customer']['email'];
$cart['name'] = $order['data']['billing']['firstName'] . ' ' . $order['data']['billing']['lastName'];

Falls eine abweichende Lieferadresse vorliegt, muss diese ebenfalls übergeben werden und das Feld abweichendelieferadresse ist mit true zu befüllen, um zu gewährleisten, dass der Auftrag beim richtigen Empfänger ankommt. Zudem gibt es wichtige Daten, die für die weitere Verarbeitung von Bedeutung sind.

$cart['auftrag'] = $orderFromCollection['id'];
$cart['gesamtsumme'] = $orderFromCollection['invoiceAmount'];
$cart['transaktionsnummer'] = $orderFromCollection['transactionId'];
$cart['onlinebestellnummer'] = $orderFromCollection['number'];
...
$cart['zahlungsweise'] = $order['data']['payment']['name'];
$cart['lieferung'] = $order['data']['dispatch']['name'];
$cart['bestelldatum'] = substr($order['data']['orderTime'],0,10);
$cart['versandkostennetto'] = $order['data']['invoiceShippingNet'];

Gesamtsumme:

Die Gesamtsumme des Auftrags dient als Absicherung gegen einen falsch zusammengesetzten Warenkorb. Falls Artikeldaten nicht richtig übergeben wurden oder ein Problem mit der Besteuerung auftritt, weicht die Gesamtsumme des Auftrags von der Gesamtsumme des Warenkorbs ab und die Auto-Versandoption wird für die Bestellung deaktiviert. Dadurch wird sichergestellt, dass keine Lieferung das Lager verlässt, die nicht mit der Bestellung übereinstimmt.

Transaktionsnummer:

Die Transaktionsnummer ist für die Automatisierung des Rechnungswesens relevant und hilft, bezahlte Bestellungen zuzuordnen.

Auftrag:

In diesem Feld wird die eindeutige Kennzeichnung des Auftrags für den Shop übergeben. Nicht jede Shop-Schnittstelle erlaubt, den Versandstatus einer Bestellung über die Bestellnummer zu ändern. Gelegentlich wird eine interne ID benötigt, die an dieser Stelle übergeben werden kann. Auf den hier übergebenen Wert wird später Bezug genommen, wenn eine Änderung des Bestellstatus aus dem Shop übermittelt wird.

Onlinebestellnummer:

In diesem Feld ist die Bestellnummer einzupflegen. Diese erleichtert die Zuordnung und bei Rückfragen kann eine Bestellung aus dem Shop direkt einem Auftrag in xentral zugeordnet werden.

Zahlungsweise:

Das Übertragen der Zahlungsweise erlaubt es, Einstellungen wie Autoversand, Fast-Lane oder das Anlegen von Rechnungen spezifisch für bestimmte Zahlungsweisen in xentral zu aktivieren oder zu deaktivieren.

Lieferung:

Bei übergebener Lieferweise kann ein Matching in xentral vorgenommen werden, ähnlich wie bei der Zahlungsweise.

Versandkostenbrutto:

Bei einer Bestellung können die Versandkosten wie ein Artikel im Warenkorb übergeben werden. Durch dieses Spezialfeld werden die Versandkosten allerdings auf den, im Importer eingestellten, Portoartikel gebucht und in den Auftrag übernommen.

Bestelldatum: Das Bestelldatum zeigt das Datum des Bestellungseingangs an.

foreach ($order['data']['details'] as $article)
{
        $articlearray[] = [
                'articleid' => $article['articleNumber'],
                'name' => $article['articleName'],
                'price' => $article['price'],
                'quantity' => $article['quantity']
        ];
}

...

$orderData =[
        'id' => $cart['auftrag'],
        'warenkorb' => base64_encode(serialize($cart)),
        'warenkorbjson' => base64_encode(json_encode($cart))
];

Wenn die benötigten Grunddaten der Bestellung an den Warenkorb übergeben wurden, sind die einzelnen Positionen zum Warenkorb hinzuzufügen. Im Feld articleid wird die Artikelnummer übergeben. In den anderen Feldern steht ihr jeweiliges Äquivalent aus der Bestellposition.

Nachdem der Warenkorb mit allen Daten aus der Bestellung befüllt wurde, gibt die Funktion die Daten zurück.

Die Funktion ImportDeleteAuftrag ist dafür zuständig, eine offene Bestellung als „In Bearbeitung“ zu kennzeichnen. Die Partnerfunktion ImportUpdateAuftrag kennzeichnet die Bestellung als „Versendet“.

public function ImportDeleteAuftrag()
{
  $orderId = $this->data['auftrag'];
  $update = [
    'orderStatusId' => 1
  ];

  $this->call('orders/'.$orderId, 'PUT',$update);

  return true;
}

Die UNB Zeile definiert unter anderem den Empfänger und Absender. Hier ist ein eindeutiges Kennzeichen für den Kommunikationspartner einzutragen. Dafür existieren verschiedene Möglichkeiten:

Bei EDI/EDIFACT wird nahezu alles mit Codelisten übertragen. Dafür existieren einige Quellen, die das Format erläutern und den Umgang damit aufzeigen:

Die Datenübertragung erfolgt z.B. mit SFTP ausschließlich per keyfile (ssh pub-key), alternativ wird AS2 verwendet. Bei Bedarf stellt xentral einen AS2-Server bereit, hierfür ist der Vertrieb oder der Partner-Betreuer bei xentral zu kontaktieren.

Die EDI-Datei ist eine reine Textdatei, idealerweise codiert in UTF8; dies ist aber nicht zwingend im Standard vorgeschrieben. Wird eine Datei mit nur einer Zeile gesendet, kann das EDI Satzendzeichen ' (einfaches Anführungszeichen, wird im UNA Segment definiert) durch ein LF bzw. CR/LF ersetzen.

Bestimmte Segmente können in EDI mehrfach vorkommen und haben dann evtl. eine unterschiedliche Bedeutung, z.B. Daten im Kopf (Header) und auf Positions-Ebene.

Es wurden einige Segmente in einer ORDER zusammengefasst um zu zeigen, wie eine ORDER zu parsen wäre.

BGM+220+4HQ7EBLG+9'   --> Bestellung mit PO Nummer 4HQ7EBLG, 
                      --> die 9 am Schluss bedeutet es werden die EAN/GS1 Codelisten verwendet
DTM+137:20190107:102' --> Belegdatum im Format 102
DTM+63:20190111:102'  --> Lieferdatum spätestens im format 102
DTM+64:20190107:102'  --> Lieferdatum frühstens im Format 102
Benötigt wird das GLN Verzeichnis aus dem Vendor-Central, damit die Lieferadressen zugeordnet werden können.
NAD+BY+5450534000017::9'          --> Käufer, GLN Codiert
NAD+SU+4016428000009::9'          --> Lieferant, hier wird die eigene UNB-ID wieder angegeben
NAD+DP+5450534002325::9+++++++DE' --> Lieferadresse mit Land
NAD+IV+5450534005838::9++AMAZON EU SARL:NIEDERLASSUNG DEUTSCHLAND+MARCEL-BREUER-STR. 12+MUENCHEN++80807+DE' 
                                  --> Rechnungsadresse als GLN und Klartext muss in der INVOICE Message auch komplett 
                                  --> im Klartext übertragen werden.

Im Folgenden (ab LIN) beginnen die Positionen. Zwischen NAD und LIN sind weitere Zeilen möglich, zb. RFF (Referenz jeweils zum aktuellen Element) oder CUX (hier wird die Währung definiert).

Jedes LIN definiert den Beginn einer neuen Position(LIN+1, LIN+2, LIN+3 usw.):

LIN+1++4016428352115:EN'          --> Artikel Pos 1 mit Artikel EAN, EN=Datenherkunft EAN, könnte evtl. auch SA sein
QTY+21:52'                        --> Pos Menge in Stück
PRI+AAA:55.9'                     --> Preis pro Stück netto

Im Anschluss folgen Rahmendaten, die vor allem der Validierung dienen: Mit UMS+S beginnt der Summenblock, der mithilfe verschiedener Summen eine Validierung ermöglicht.

Sollten mehrere Belege einer UNB Übertragung enthalten sein, folgen diese nun durch ein UNH bzw. BGM, mit dem Belegkopf getrennt.