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.

Informationen dazu erhalten Sie vom Hersteller

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.

Eine Anpassung oder Erweiterung ist nach Absprache kostenpflichtig möglich.

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).

Eine Anpassung oder Erweiterung ist nach Absprache kostenpflichtig möglich.

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

Aktionspreise: Ist das Feld KDNr leer, wird der eingetragene Preis NettoVK als zeitlich gesteuerter Aktionspreis behandelt, der im Zeitraum von Start bis Ende unter Beachtung der Zugehörigkeit eines Kunden zur Preisgruppe in „Gruppe“, der Vorgabe der Möglichkeit zum Überschreiben eines möglichen Sonderpreises eines Kunden für den Artikel und Einschränkung der Gültigkeit eines Aktionspreises auf eine maximale Abverkaufsmenge Vorrat gilt.

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.

Beispiel: 2012-02-06-105730-5432.xml

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

Abhängig vom <priceMode> werden die Preise Brutto oder Netto übergeben. Ausnahme ist der Wert <sumTotal>, welcher immer die Gesamtsumme inklusive der gesetzlichen Steuer enthält.

Die Tags <discountPercent und <discountFix> definieren mögliche Rabatte sowie Gutscheine. Bei prozentualen Rabatten sind diese direkt in den Artikelpreisen berücksichtigt. Bei einem Einmalbetrag werden die Werte in dem Tag <sumTotal> berücksichtigt.

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)

Beispieldateien

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>