Schnittstellenleitfaden
- für den Stammdatenexport an externe Webshop-Systeme
- für den Auftragsimport aus externen Webshop-Systemen
Stand Dezember 2021
Vorbemerkungen
Im Folgenden werden die Austauschformate für die nicht spezifische Webshop-Schnittstelle aufgeführt. Die Schnittstelle ist eine von mehreren Schnittstellen, die genutzt werden können.
Formate
Neben den branchenspezifischen Schnittstellen (KOLLEX, OctopusOrder, Refill, Gastivo) unterstützt FAKTURA-X auch algemeine EDI Formate.
Formatkennzeichen
- A: String (Zeichenkette alphanumerisch), Länge wird zusätzlich angegeben
- N: Float (Numerisch), Wertebereich optional angegeben
- I: Integer (Ganzzahl), Wertebereich optional angegeben
- B: Boolean (Logisch), Wertebereich (FALSCH, WAHR)
- D: Date (Datum), Format [TT.MM.JJJJ]
- T: Time (Uhrzeit), Format [HH:NN:SS]
- @: DateTime (Zeitstempel), Format [TT.MM.JJJJ HH:NN:SS]
Abweichende Definitionen
Sollte eine Anforderung mit diesem Leitfaden nicht abgedeckt werden können, sprechen Sie uns bitte an.
Bereitstellung von Daten
Im einfachsten Fall werden Stammdaten als CSV-Daten bereitgestellt und auf einen FTP-Server übertragen. Die Auftragsdaten werden als XML-Dateien von einem FTP-Server herutergeladen und verarbeitet. Das Abrufen und Verarbeiten der Aufträge kann automnatisch oder manuell erfolgen.
- Informationen für die Auftragsverarbeitung finden Sie hier.
- Die Einstellungen für für den Datenaustausch mit WEBDRINK finden Sie hier.
- Die Einstellungen für für den Datenaustausch mit Shopware oder Magento u.ä. finden Sie hier.
Stammdatenexport als CSV
Die Daten werden mit einer FTP-Verbindung übertragen. Nach erfolgreichem Verbindungsaufbau werden die CSV-Daten in einem zu definierenden Ordner kopiert.
Folgende Standards werden vereinbart:
- Daten werden durch Semikola getrennt, bereitgestellt. Jeder Datensatz wird mit einem Semikolon abgeschlossen.
- Es werden keine Delimiter verwendet, der Typ eines Datensatzes ergibt sich aus der Reihenfolge.
- Der Zeichensatz ist Windows 1252 (ANSI).
Feldbeschreibungen Datei "Kunden.csv“
Nachfolgend wird ein Kundendatensatz beschrieben.
Feld Typ Information KDNr A20 (eingeschränkter Zeichensatz) Eindeutige Identnummer Anrede A10 Anrede, optional Vorname A80 Vorname, optional Name/Firma A80 Firmenname oder Name Zusatz A80 optional Abteilung etc. Strasse A20 Straße mit Hausnummer PLZ A5 ohne Nationalitätskennzeichen Ort A80 Ort Telefon A20 Telefon 1, optional Mobil A20 Telefon 2, optional Email A255 Mehrfacheinträge mit „,“ getrennt StNr A40 StNr. oder USt.ID, optional BIC A10 ohne Leerzeichen, optional IBAN A30 Darf Leerzeichen enthalten, optional Bar B Kunde muss bei Lieferung zahlen Gewerbe B Gewerbe oder Privatkunde Limit N (-1, 0..n) -1 = gesperrt, 0 = kein Limit Preisgruppe I (1..n) Preisgruppenliste
Optional: Feldbeschreibungen Datei "Lieferadressen.csv“
Nachfolgend wird ein Adressdatensatz beschrieben. Diese Liste enthält zusätzliche Adressen eines Kunden. Die Datei ist optional. Sind keine Zusatzadressen vorhanden, wird die Baissadresse des Kundendatensatzes als Lieferadresse verwendet.
Feld Typ Information KDNr A20 (eingeschränkter Zeichensatz) Eindeutige Identnummer Anrede A10 Anrede, optional Vorname A80 Vorname, optional Name/Firma A80 Firmenname oder Name Zusatz A80 optional Abteilung etc. Strasse A20 Straße mit Hausnummer PLZ A5 ohne Nationalitätskennzeichen Ort A80 Ort Telefon A20 Telefon 1, optional Ident A20 Kennung der Adresse
Feldbeschreibungen Datei "Artikel.csv“
Nachfolgend wird ein Artikeldatensatz beschrieben.
Feld Typ Information Versionsnummer I Wird nicht verwendet ArtNr A20, eingeschränkter Zeichensatz Eindeutige Identnummer Artikelbezeichnung A80 Artikelbezeichnung Menge I (0..n) Flaschen im Kasten, Einzel = 0 Gebinde-Inhalt N (0..n) Liter Warengruppe A40 Warengruppe Untergruppe A40 Wird nicht verwendet Hersteller A40 Hersteller Bruttopreis N Basispreis 1 des Artikels inkl. MwSt. Brutto-Pfand N Basispreis 1 des Pfands inkl. MwSt. Brutto-Literpreis N Basispreis 1 pro Liter inkl. MwSt. Nettopreis N Basispreis 2 des Artikels exkl. MwSt. Netto-Pfand N Basispreis 2 des Pfands exkl. MwSt. Netto-Literpreis N Basispreis 2 pro Liter exkl. MwSt. MwSt N (0..n) MwSt.-Satz in Prozent Barcode A20 EAN des Teilgebinde oder Einzelartikel Lieferbar I Wird nicht verwendet Angebotsart I Wird nicht verwendet
Optional: Feldbeschreibungen Datei "Favoriten.csv“
Nachfolgend wird ein Kundensortimentsdatensatz beschrieben. Diese Liste enthält die bisher bestellten Artikel eines Kunden. Die Datei ist optional.
Feld Typ Information KDNr A20 (eingeschränkter Zeichensatz) Eindeutige Identnummer des Kunden ArtNr A20, eingeschränkter Zeichensatz Eindeutige Identnummer des Artikels Anzahl I übliche Bestellmenge
Optional: Feldbeschreibungen Datei "Sonderpreise.csv“
Nachfolgend wird eine Tabelle mit kundenspezifischen oder zeitlich beschränkten Sonderpreisen beschrieben. Die Datei ist optional.
Feld Typ Information KDNr A20 (eingeschränkter Zeichensatz) Eindeutige Identnummer des Kunden ArtNr A20, eingeschränkter Zeichensatz Eindeutige Identnummer des Artikels NettoVK N Netto Sonderpreis Start @ Zeitstempel Gültigkeitsbeginn eines Aktionspreises Ende @ Zeitstempel Gültigkeitsende eines Aktionspreises Gruppe A20 Aktionspreis gilt für Preisgruppe Ersetzen A5 (Ja, Nein) Aktionspreis kann Sonderpreise überschreiben Vorrat I (-1, 1..n) Beschränkter Vorrat eines Aktionspreises, -1 = kein Vorrat
Auftragsimport als XML
Die Daten werden mit einer FTP-Verbindung übertragen. Nach erfolgreichem Verbindungsaufbau werden die XML-Daten aus einem zu definierenden Ordner geladen.
Folgende Standards werden vereinbart:
- Elemente ohne Daten werden XML-konform als <Tag-Name /> dargestellt.
- Jede Bestellung wird einzeln erfasst.
- Der Datensatz enthält Bestellmerkmale sowie alle Details des Kunden.
- Der Zeichensatz ist UTF-8.
- Der Name der XML-Datei besteht aus dem Zeitstempel (YYYY-MM-DD-HHNNSS) sowie der Auftragsnummer, welche vom Shopsystem vergeben werden muss.
Entität "Order"
Nachfolgend die Entitäten, in welche sich der Tag <order></order> unterteilt. Da ausschließlich eine Bestellung pro Datei dargestellt wird, ist dieses Tag einmalig.
Entität Typ Beispiel Erläuterungen <orderID> I 5456 Auftragsnummer des WebShop <ip> A 91.53.190.30 IP-Adresse des Kunden während der Bestellung <orderDate> @ 2012-06-02 14:15:45 Bestellzeitpunkt <deliveryDate> D 2012-07-02 Lieferdatum <deliveryPeriod> A Vormittags Kommentar zur Bestellung <comment> A Leergut steht im Garten Kommentar zur Bestellung <payment> A (Auswahl) bankCollection Cash (Bar), Invoice (Rechnung), bankCollection (Einzug), paypal (PayPal) <priceMode> A (Auswahl) gross gross (Brutto), net (Netto) <taxRate> N (10.2) 19.00 Mehrwertsteuersatz <merchandiseValue> N (10.2) 75.69 Warenwert <deliveryCosts> N (10.2) 0.00 Lieferkosten <smallVolumePurchase> N (10.2) 0.00 Mindermengenzuschlag <discountPercent> N (10.2) 3.00 3% Rabatt auf den Warenwert <discountFix> N (10.2) 5.45 Gutscheineinlösung <sumTotal> N (10.2) 75.69 Gesamtbetrag inklusive Rabatte, Lieferkosten, Zuschläge, Gutscheine, Mehrwertsteuer
Entität "Article"
Nachfolgend wird dokumentiert in welche Entitäten sich der Tag <article></article> unterteilt, welcher sich innerhalb von order befindet. Der Tag kann je nach Anzahl unterschiedlicher Artikel mehrfach hintereinander erscheinen.
Entität Typ Beispiel Erläuterungen <amount> N 3 Anzahl <articleNumber> A 301012 Artikelnummer <name> A Coca Cola Bezeichnung <package> A 12x1,0 Gebindeformat <price> N (10.2) 11.99 Einzelpreis <deposit> N (10.2) 3.30 Pfandwert <taxRate> N (10.2) 19.00 Mehrwertsteuersatz <ean> A 4008287077018 EAN Code
Entität "DeliveryDetails"
Nachfolgend wird dokumentiert in welche Entitäten sich der Tag <deliveryDetails></deliveryDetails> unterteilt, welcher sich innerhalb von order befindet. Sofern es keine Lieferdetails gibt, ist dieser Tag nicht enthalten.
Entität Typ Beispiel Erläuterungen <type> A (Auswahl) flat flat=Anfahrtspauschale, article=Artikelaufschlag, individual=individuell <name> A Anfahrtspauschale Name <price> N 10.2 5.99 Preis (Brutto)
Entität "Customer"
Folgende Entitäten sind bei dem Tag <customer></customer> enthalten. Das Tag <customer> ist pro Bestellung einmalig.
Entität Typ Beispiel Erläuterungen <wdCustomerID> I 5456 Interne Kundennummer <customerNumber> A20 1101 FAKTURA-X Kundennummer <street> A Musterstraße Straße <streetNumber> A 10 Hausnummer <additionalAddressInformation A 5. Etage Zusatz <postcode> A 35708 Postleitzahl <town> A Haiger Ort <title> A Herr Prof. Dr. Anrede <company> A Mustermann AG Firma <name> A Mustermann Name <firstName> A Max Vorname <phone> A 02773-12345 Telefon <fax> A 02773-12346 Telefax (optional) <mobile> A 0175-1234567 Mobiltelefon (optional) <email> A info@mail.de E-Mail <registrationDate> @ YYYY-MM-DD HH:NN:SS Registrierungstag <newsletter> I (0..1) 0 0= Keine Newsletter, 1=Newsletter
Entität "DeliveryAddress"
Der Tag <deliveryAddress></deliveryAddress> innerhalb von customer ist nur vorhanden, wenn eine abweichende Lieferadresse existiert.
Entität Typ Beispiel Erläuterungen <street> A Musterstraße Straße <streetNumber> A 10 Hausnummer <additionalAddressInformation A 5. Etage Zusatz <postcode> A 35708 Postleitzahl <town> A Haiger Ort <title> A Herr Prof. Dr. Anrede <company> A Mustermann AG Firma <name> A Mustermann Name <firstName> A Max Vorname
Entität "BankDetails"
Der Tag <bankDetails></bankDetails> innerhalb von customer ist nur vorhanden, wenn diese hinterlegt ist. Bitte beachten Sie, dass der tag <payment></payment> innerhalb von <order> den Wert "bankCollection" enthält, sofern der Kunde bei dieser Bestellung Bankeinzug wünscht.
Entität Typ Beispiel Erläuterungen <accountOwner> A Max Mustermann Kontoinhaber <accountNumber> A 1234567890 Kontonummer (obsolet) <bankCode> A 41650001 BLZ (obsolet) <bank> A Sparkasse Bank (obsolet) <Iban> A DE67416500011234567890 IBAN <bic> A WELADED1LIP BIC (kann leer belieben)
Beispieldateie
Das folgende Listing veranschaulicht eine Auftragsdatei. Die zugehörige XML-Datei "2012-02-06-105730-5432.xml" kann [hier] heruntergeladen werden.
<xml version="1.0" encoding="UTF-8" standalone="yes">
<order>
<orderID>8372</orderID>
<ip>87.153.22.57</ip>
<orderDate>2012-06-04 13:46:40</orderDate>
<deliveryDate>2012-07-07</deliveryDate>
<deliveryPeriod>Vormittags</deliveryPeriod>
<comment/>
<payment>bankCollection</payment>
<priceMode>gross</priceMode>
<taxRate>19.00</taxRate>
<merchandiseValue>55.95</merchandiseValue>
<deliveryCosts>10.00</deliveryCosts>
<smallVolumePurchase>0.00</smallVolumePurchase>
<sumTotal>80.05</sumTotal>
<discountPercent>0.00</discountPercent>
<discountFix>0.00</discountFix>
<article>
<amount>2</amount>
<articleNumber>17106</articleNumber>
<name>Possmann Apfelwein 1 l (6x1,00)</name>
<package>6x1,00</package>
<price>8.49</price>
<deposit>2.40</deposit>
<taxRate>19</taxRate>
<ean/>
</article>
<article>
<amount>3</amount>
<articleNumber>23105</articleNumber>
<name>Veltins Pils 0,5 (20x0,50)</name>
<package>20x0,50</package>
<price>12.99</price>
<deposit>3.10</deposit>
<taxRate>19</taxRate>
<ean>4005249000367</ean>
</article>
<deliveryDetails>
<name>Anfahrtspauschale</name>
<price>4.00</price>
</deliveryDetails>
<deliveryDetails>
<name>5 Artikel à 1,20€</name>
<price>6.00</price>
</deliveryDetails>
<customer>
<wdCustomerID>2578</wdCustomerID>
<customerNumber/>
<street>Musterstr.</street>
<streetNumber>1</streetNumber>
<additionalAddressInformation/>
<postcode>35708</postcode>
<town>Haiger</town>
<title>Frau </title>
<company/>
<name>Mustermann</name>
<firstName>Max</firstName>
<phone>5468715687</phone>
<fax/>
<mobile/>
<email>mustermann@mustermann.de</email>
<registrationDate>2012-06-01 18:48:49</registrationDate>
<newsletter>0</newsletter>
<bankDetails>
<accountOwner>Max Mustermann</accountOwner>
<accountNumber>99999999</accountNumber>
<bankCode>999999999</bankCode>
<bank>Mustermann eG</bank>
<iban>999999999</iban>
<bic>DE0075XX</bic>
</bankDetails>
</customer>
</order>
</xml>