Schnittstellenleitfaden

Aus FAKTURA-X Wiki
Zur Navigation springen Zur Suche springen
  • 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.

Hinweise für externe Entwickler

Wir weisen explizit darauf hin, dass die vorliegende Schnittstelle seit vielen Jahren von verschiedenen Schnittstellenpartnern eingesetzt wird

Es handelt sich um eine praxiserprobte und erwiesenermaßen robuste, funktionsfähige Schnittstelle. Die Schnittstelle wurde mit Fachleuten aus mehreren Unternehmen gemeinsam entwickelt. Sie wurde bereits erfolgreich in Systeme wie "Shopware" oder "Drinkware" implementiert und wird im Produktivbetrieb von Anwendern genutzt:

  • Die Schnittstelle ist voll funktionsfähig
  • Alle zugrundeliegenden Normen und Spezifikationen werden eingehalten

Daraus folgt:

  • Es werden keine Anpassung aufgrund von Einschränkungen oder Inkompatibilitäten auf der Seite des Shopsystems durchgeführt, auch nicht auf Anfrage oder gegen Kostenerstattung
  • Eine Erweiterung der Schnittstelle ist auf Anfrage und in jedem Fall kostenpflichtig, möglich.
  • Es muss nicht die Schnittstelle, sondern immer das Shopsystem angepasst werden. Dies ist nicht Aufgabe des Schnittstellenanbieters, sondern des Webshopentwicklers.
Sie erhalten auf Anfrage Hilfestellung zu Schnittstellendefinitionen, jedoch keinesfalls zu branchenspezifischen Themen. Zu branchenspezifische Themen sprechen Sie ausschließlich den Auftraggeber an

Vor der Implementierung fordern wir beim Auftraggeber eine Freigabe zur Erstattung der Beratungskosten an. Der entstandenen Aufwand wird dokumentiert.

Dateiformate

CSV-Dateien

  • Es werden deutsche Formatierungen und Zeichensätze verwendet
  • Zeichensatz ist UTF-8
  • Spalten werden, durch Semikola getrennt
  • Jeder Datensatz wird mit einem Semikolon abgeschlossen
  • Es werden keine Delimiter verwendet, der Typ eines Datensatzes ergibt sich aus der Reihenfolge

XML-Dateien

  • RFC- und W3C-konform
  • Zeichensatz ist UTF-8

Dateitransfer

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 heruntergeladen und verarbeitet. Das Abrufen

  • Das FTP-Protokoll wird RFC- und W3C-konform angewendet.
  • Der FTP-Client der Anwendung arbeitet im passiven Modus, es wird der Standardport verwendet
  • Die Anmeldung am Server erfolgt mit einem Benutzernamen und einem Passwort.
  • Der Befehlssatz des Servers muss ASCII, CWD, DELE, GET, NLST und STOR umfassen[1]
Neben den branchenspezifischen Schnittstellen (KOLLEX, OctopusOrder, Gastivo) unterstützt die Anwendung auch EDI-Formate

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.

Formatkennzeichen

Zeichen Bedeutung
Eindimensionaler alphanumerischer String UTF-8, ohne Delimiter
Gleitkommazahl (-)n0,n, maximal 32-Bit
Ganzzahl (-)i, maximal 32-Bit
Logischer Wert True/False oder Wahr/Falsch, ohne Delimiter
Datum ISO 8601 JJJJ-MM-TT, Zeitanteil wird ignoriert
Uhrzeit ISO 8601 hh:nn:ss, Millisekunden werden ignoriert
Datumsstempel JJJJ-MM-TT hh:nn:ss, Millisekunden werden ignoriert

Feldbeschreibungen Datei "Kunden.csv“

Nachfolgend wird ein Kundendatensatz beschrieben.

Feld Typ Information
KDNr Alphanumerisch Eindeutige Identnummer
Anrede Alphanumerisch Anrede, optional
Vorname Alphanumerisch Vorname, optional
Name/Firma Alphanumerisch Firmenname oder Name
Zusatz Alphanumerisch optional Abteilung etc.
Strasse Alphanumerisch Straße mit Hausnummer
PLZ Ganzzahl ohne Nationalitätskennzeichen
Ort Alphanumerisch Ort
Alphanumerisch A20 Telefon 1, optional
Alphanumerisch A20 Telefon 2, optional
Email Alphanumerisch Mehrfacheinträge werden mit Komma getrennt
StNr Alphanumerisch StNr. oder USt.ID, optional
BIC Alphanumerisch ohne Leerzeichen, optional
IBAN Alphanumerisch Darf Leerzeichen enthalten, optional
Bar Logisch Kunde muss bei Lieferung zahlen
Gewerbe Logisch Gewerbe oder Privatkunde
Limit Ganzzahl -1 = gesperrt, 0 = kein Limit
Preisgruppe Ganzzahl 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 Alphanumerisch Eindeutige Identnummer
Anrede Alphanumerisch Anrede, optional
Vorname Alphanumerisch Vorname, optional
Name/Firma Alphanumerisch Firmenname oder Name
Zusatz Alphanumerisch optional Abteilung etc.
Strasse A20 Straße mit Hausnummer
PLZ Ganzzahl ohne Nationalitätskennzeichen
Ort Alphanumerisch Ort
Telefon Alphanumerisch Telefon 1, optional
Ident Alphanumerisch Kennung der Adresse

Feldbeschreibungen Datei "Artikel.csv“

Nachfolgend wird ein Artikeldatensatz beschrieben.

Feld Typ Information
Versionsnummer I Wird nicht verwendet
ArtNr Alphanumerisch Eindeutige Identnummer
Artikelbezeichnung Alphanumerisch Artikelbezeichnung
Menge Ganzzahl Flaschen im Kasten, Einzel = 0
Gebinde-Inhalt Kommazahl Liter
Warengruppe Alphanumerisch Warengruppe
Untergruppe Alphanumerisch Wird nicht verwendet
Hersteller Alphanumerisch Hersteller
Bruttopreis Kommazahl Basispreis 1 des Artikels inkl. MwSt.
Brutto-Pfand Kommazahl Basispreis 1 des Pfands inkl. MwSt.
Brutto-Literpreis Kommazahl Basispreis 1 pro Liter inkl. MwSt.
Nettopreis Kommazahl Basispreis 2 des Artikels exkl. MwSt.
Netto-Pfand Kommazahl Basispreis 2 des Pfands exkl. MwSt.
Netto-Literpreis Kommazahl Basispreis 2 pro Liter exkl. MwSt.
MwSt Kommazahl MwSt.-Satz in Prozent
Barcode Alphanumerisch EAN des Teilgebinde oder Einzelartikel
Lieferbar Ganzzahl Wird nicht verwendet
Angebotsart Ganzzahl 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 Alphanumerisch Eindeutige Identnummer des Kunden
ArtNr Alphanumerisch Eindeutige Identnummer des Artikels
Anzahl Ganzzahl ü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 Alphanumerisch Eindeutige Identnummer des Kunden
ArtNr Alphanumerisch Eindeutige Identnummer des Artikels
NettoVK Kommazahl Netto Sonderpreis
Start Zeitstempel Zeitstempel Gültigkeitsbeginn eines Aktionspreises
Ende Zeitstempel Zeitstempel Gültigkeitsende eines Aktionspreises
Gruppe Alphanumerisch Aktionspreis gilt für Preisgruppe
Ersetzen Logisch (ja/nein) Aktionspreis kann Sonderpreise überschreiben
Vorrat Ganzzahl 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.

Bedingungen:

  • Elemente ohne Daten werden XML-konform als <Tag-Name/> dargestellt
  • Jede Bestellung wird einzeln erfasst
  • Der Datensatz enthält alle Informationen zur Bestellung und zum Kunden
  • Zeichensatz ist UTF-8
  • Der Name der XML-Datei besteht aus dem Zeitstempel (YYYY-MM-DD-HHNNSS) sowie der Auftragsnummer, welche vom Webshop vergeben wird. Beispiel: 2012-02-06-105730-5432.xml

Aufbau der XML-Datei

<order>
 [notwendig, einmal]
 
 <paymentDetails>
   [optional, einmal]
 </paymentDetails>
    
 <DeliveryDetails>
   [optional, mehrfach]
 </DeliveryDetails>

 <article>
   [optional, mehrfach]
 </article>
</order>

<customer>
 [notwendig, einmal]
 
 <DeliveryAddress>
   [optional, einmal]
 </DeliveryAddress>

 <BankDetails>
   [optional, einmal]
 </BankDetails>
</customer>

Die Entität "order"

Die Entität ist primär, notwendig und einmalig. Sie enthält Informationen zur Bestellung.

Entität Typ Beispiel Erläuterungen
<orderID> Alphanumerisch 5456 Bestellnummer des Shop (optional)
<type> Auswahl (order = Bestellung, request = Anfrage) order Typ des Auftrags (wird nicht ausgewertet)
<randomPinCode> Alphanumerisch 48664411 Zufallspin (wird nicht ausgewertet)
<ip> Alphanumerisch formatiert 91.53.190.30 IP Adresse (optional)
<orderDate> Zeitstempel ISO-8601 2012-06-02 14:15:45 Bestelldatum
<deliveryDate> Zeitstempel ISO-8601 2012-07-02 11:00:00 Lieferdatum
<deliveryPeriod> Alphanumerisch Vormittags Lieferzeit (optional)
<comment> Alphanumerisch Leergut steht im Garten Kommentar (optional)
<payment> Auswahl (Cash = bar, Invoice = Rechnung, bankCollection = Einzug, paypal = PayPal) bankCollection Zahlweise
<paymentDeadlineInDays> Ganzzahl 5 Zahlungsziel in Tagen
<paymentFeeForPaymentDeadlineInPercent> Ganzzahl (wird nicht ausgewertet) 0 Mahnzins in Prozent (wird nicht ausgewertet)
<paymentFeeForPaymentDeadline> Kommazahl 0.00 Mahngebühr als Betrag (wird nicht ausgewertet)
<priceMode> Auswahl (gross = Verbraucher, net = Wiederverkäufer) gross Kundentyp
<merchandiseValue> Kommazahl 81.84 Gesamt Netto (wird nicht ausgewertet)
<deliveryCosts> Kommazahl 5.00 Liefergebühren (wird nicht ausgewertet)
<smallVolumePurchase> Kommazahl 0.00 Mindermengenzuschlag (wird nicht ausgewertet)
<discountPercent> Kommazahl 3.00 Rabatt in Prozent (wird nicht ausgewertet)
<discountFix> Kommazahl 5.45 Rabatt als Betrag (wird nicht ausgewertet)
<sumDeposit> Kommazahl 6.60 Pfand (wird nicht ausgewertet)
<sumFee> Kommazahl 0.00 Gebühren (wird nicht ausgewertet)
<sumDeliveryCosts> Kommazahl 0.00 Summe Transportkosten (wird nicht ausgewertet)
<sumTotal> Kommazahl 75.24 Gesamtsumme ohne Pfand (wird nicht ausgewertet)

Die Entität "paymentDetails"

Die Entität ist in <order> enthalten, optional und einmalig. Sie enthält optionale Informationen zur Zahlweise

Entität Typ Beispiel Erläuterungen
<paymentSystem> Alphanumerisch Bank Zahlweise
<externalId> Alphanumerisch 58 EDI-Code der Zahlweise

Die Entität "DeliveryDetails"

Die Entität ist in <order> enthalten, optional und wiederholbar. Sie enthält optionale Informationen zu Transportkosten

Entität Typ Beispiel Erläuterungen
<type> Auswahl (flat = pauschal, tba.) flat Berechnungsweise
<name> Alphanumerisch Anfahrtspauschale Bezeichnung
<price> Kommazahl 5.00 Betrag

Die Entität "article"

Die Entität ist in <order> enthalten, (thoretisch) optional und wiederholbar. Sie enthält Informationen zu Bestellposten

Entität Typ Beispiel Erläuterungen
<amount> Ganzzahl 2 Anzahl
<articleQuantity> Ganzzahl 2 Anzahl
<articleNumber> Alphanumerisch 301012 Artikelnummer ERP
<name> Alphanumerisch Coca Cola Zero Bezeichnung
<package> Alphanumerisch 12x1,00 Gebinde
<price> Kommazahl 11.99 Ware Einzel
<unitPrice> Kommazahl 11.99 Ware Einzel
<deposit> Kommazahl 3.30 Pfand Einzel
<unitDeposit> Kommazahl 0.00 Pfand pro Einheit
<unitFee> Kommazahl 0.00 Gebühr
<taxRate> Kommazahl 19.00 MwSt.Satz
<ean> Alphanumerisch 4008287077018 EAN

Die Entität "customer"

Die Entität ist primär, notwendig und einmalig. Sie enthält Informationen zum Kunden

Entität Typ Beispiel Erläuterungen
<externalAddressID> Alphanumerisch 4535 Externe Adressnummer
<priceGroupID> Ganzzahl 1 Nummer der Preisgruppe
<wdCustomerID> Alphanumerisch 5456 Kundennummer Shop
<customerNumber> Alphanumerisch 1101 Kundennummer ERP
<street> Alphanumerisch Musterstraße Straße (darf Hausnummer enthalten)
<streetNumber> Alphanumerisch 10b Hausnummer (optional)
<additionalAddressInformation Alphanumerisch 5. Etage Zusatzinformationen
<floor> Alphanumerisch 2 Etage
<elevator> Logisch (ja, nein/leer) Fahrstuhl vorhanden
<postcode> Ganzzahl 35708 Postleitzahl
<town> Alphanumerisch Haiger Ort
<salutation> Alphanumerisch Herr Anrede
<title> Alphanumerisch Prof. Dr. Titel
<company> Alphanumerisch Mustermann AG Firma
<name> Alphanumerisch Mustermann Name
<firstName> Alphanumerisch Max Vorname
<phone> Alphanumerisch 02773-12345 Telefonnummer
<fax> Alphanumerisch Telefaxnummer
<mobile> Alphanumerisch 0175-1234567 Mobilfunknummer
<email> Alphanumerisch info@mail.de E-Mailadresse
<registrationDate> Zeitstempel ISO-8601 2012-04-03 15:00:00 Registrierdatum
<dateOfBirth> Zeitstempel ISO-8601 Geburtsdatum (wird nicht ausgewertet)
<dataStatus> Auswahl(new = Neu, tba) new
<newsletter> Logisch (ja, nein/leer) Newsletteranmeldung

Die Entität "DeliveryAddress"=

Die Entität ist in <customer> enthalten, optional und einmalig. Sie enthält optionale Informationen zur Lieferadresse

Entität Typ Beispiel Erläuterungen
<street> Alphanumerisch Musterstraße Straße (darf Hausnummer enthalten)
<streetNumber> Alphanumerisch 10b Hausnummer (optional)
<additionalAddressInformation Alphanumerisch 5. Etage Zusatzinformationen
<postcode> Ganzzahl 35708 Postleitzahl
<town> Alphanumerisch Haiger Ort
<title> Alphanumerisch Prof. Dr. Titel
<company> Alphanumerisch Mustermann AG Firma
<name> Alphanumerisch Mustermann Name
<firstName> Alphanumerisch Max Vorname

Die Entität "BankDetails"

Die Entität ist in <customer> enthalten, optional und einmalig. Sie enthält optionale Informationen zur Bankverbindung

Entität Typ Beispiel Erläuterungen
<accountOwner> Alphanumerisch Max Mustermann Kontoinhaber
<Iban> Alphanumerisch DE67416500011234567890 IBAN
<bic> Alphanumerisch WELADED1LIP BIC


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.

Beispieldatei

Das folgende Listing veranschaulicht eine Auftragsdatei: 

<order>
 <orderID>5456</orderID>
 <type>order</type>
 <randomPinCode/>
 <ip>91.53.190.30</ip>
 <orderDate>2012-06-02 14:15:45</orderDate>
 <deliveryDate>2012-07-02 11:00:00</deliveryDate> 
 <deliveryPeriod>Vormittags</deliveryPeriod>
 <comment>Leergut steht im Garten</comment>
 <payment>bankCollection</payment>
 <paymentDetails>
  <paymentSystem>Bank</paymentSystem>
  <externalId>1200</externalId>
 </paymentDetails>  
 <paymentDeadlineInDays>5</paymentDeadlineInDays>
 <paymentFeeForPaymentDeadlineInPercent>0</paymentFeeForPaymentDeadlineInPercent>
 <paymentFeeForPaymentDeadline>0</paymentFeeForPaymentDeadline>
 <priceMode>gross</priceMode>
 <taxRate>19.00</taxRate>
 <merchandiseValue>75.69</merchandiseValue>
 <deliveryCosts>5.00</deliveryCosts>
 <smallVolumePurchase>0.00</smallVolumePurchase>
 <discountPercent>3.00</discountPercent>
 <discountFix>5.45</discountFix>
 <sumDeposit>0.00</sumDeposit>
 <sumFee>0.00</sumFee>
 <sumDeliveryCosts>0.00</sumDeliveryCosts>
 <sumTotal>75.24</sumTotal>
 <DeliveryDetails>
   <type>flat</type>
   <name>Anfahrtspauschale</name>
   <price>5.00</price>
 </DeliveryDetails>
 <article>
   <amount>2</amount>
   <articleQuantity>2</articleQuantity>    
   <articleNumber>301012</articleNumber>
   <name>Coca Cola Zero</name>
   <package>12x1,00</package>
   <price>11.99</price>
   <unitPrice>11.99</unitPrice>   
   <deposit>3.30</deposit>
   <unitDeposit>1.76</unitDeposit>
   <unitFee>0.00</unitFee>
   <taxRate>19.00</taxRate>
   <ean>4008287077018</ean>
 </article> 
</order>
<customer>
 <externalAddressID/>
 <priceGroupID>1</priceGroupID>
 <wdCustomerID>5456</wdCustomerID>
 <customerNumber>1101</customerNumber>
 <street>Musterstraße</street>
 <streetNumber>10</streetNumber>
 <additionalAddressInformation>5. Etage</additionalAddressInformation>
 <floor>2</floor>
 <elevator></elevator>
 <postcode>35708</postcode>
 <town>Haiger</town>
 <salutation>Herr</salutation>  
 <title>Prof. Dr.</title>
 <company>Mustermann AG</company>
 <name>Mustermann</name>
 <firstName>Max</firstName>
 <phone>02773-12345</phone>
 <fax></fax>
 <mobile>0175-1234567</mobile>
 <email>info@mail.de</email>
 <registrationDate>2012-04-03 15:00:00</registrationDate>
 <dateOfBirth/>
 <dataStatus>new</dataStatus>  
 <newsletter> 
 <DeliveryAddress>
   <street>Musterstraße</street>
   <streetNumber>10</streetNumber>
   <additionalAddressInformation>5. Etage</additionalAddressInformation
   <postcode>35708</postcode>
   <town>Haiger</town>
   <title>Prof. Dr.</title>
   <company>Mustermann AG</company>
   <name>Mustermann</name>
   <firstName>Max</firstName>
 </DeliveryAddress>
 <BankDetails>
   <accountOwner>Max Mustermann</accountOwner>
   <Iban>DE67416500011234567890</Iban>
   <bic>WELADED1LIP</bic>
 </BankDetails>
</customer>

Einzelnachweise

  1. ↑ https://en.wikipedia.org/wiki/List_of_FTP_commands
Abgerufen von „https://wiki.fakturax.de/index.php?title=Schnittstellenleitfaden&oldid=20971“