Schnittstellenleitfaden: Unterschied zwischen den Versionen

Zur Navigation springen Zur Suche springen
Die Seite wurde neu angelegt: „* '''für den Stammdatenexport an externe Webshop-Systeme''' * '''für den Auftragsimport aus externen Webshop-Systemen''' ''Stand Dezember 2021'' =Vorbemerk…“
 
 
(124 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
* '''für den Stammdatenexport an externe Webshop-Systeme'''
* '''Stammdatenexport an externe Webshop-Systeme'''
* '''für den Auftragsimport aus externen Webshop-Systemen'''
* '''Auftragsimport aus externen Webshop-Systemen'''


''Stand Dezember 2021''
''Stand Frühjahr 2026''


=Vorbemerkungen=
=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.
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==
==Hinweise für externe Entwickler==
Neben den branchenspezifischen Schnittstellen (KOLLEX; OctopusOrder, Refill, Gastivo) unterstützt FAKTURA-X auch algemeine EDI Formate.
{{Achtung|Wir weisen explizit darauf hin, dass die vorliegende Schnittstelle seit vielen Jahren von verschiedenen Schnittstellenpartnern eingesetzt wird}}


{{Tipp1|Informationen dazu erhalten Sie vom Hersteller}}
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:'''


==Abweichende Definitionen==
* Die Schnittstelle ist voll funktionsfähig
Sollte eine Anforderung mit diesem Leitfaden nicht abgedeckt werden können, sprechen Sie uns bitte an.
* Alle zugrundeliegenden Normen und Spezifikationen werden eingehalten


{{Tipp1|Eine Anpassung oder Erweiterung ist nach Absprache kostenpflichtig möglich.}}
'''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.
 
{{Achtung|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.
 
==Formatkennzeichen==
 
{| class="wikitable"
! Zeichen !! Bedeutung
|-
| Alphanumerisch || UTF-8 Zeichenkette, 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
|}
 
=Dateien=
 
==Dateiformate==
 
'''[[wikipedia:de:CSV_%28Dateiformat%29|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
 
'''[[wikipedia:de:Extensible_Markup_Language|XML-Dateien]]'''
* RFC- und W3C-konform
* Zeichensatz ist UTF-8
 
==Dateitransfer==
Im einfachsten Fall werden Stammdaten als [[wikipedia:de:CSV_%28Dateiformat%29|CSV]]-Daten bereitgestellt und auf einen [[wikipedia:de:File_Transfer_Protocol|FTP]]-Server übertragen. Die Auftragsdaten werden als [[wikipedia:de:Extensible_Markup_Language|XML]]-Dateien von einem FTP-Server heruntergeladen und verarbeitet. Das Abrufen
 
* Das ''[[wikipedia:de:File_Transfer_Protocol|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<ref>https://en.wikipedia.org/wiki/List_of_FTP_commands</ref>
 
{{Tipp1|Neben den branchenspezifischen Schnittstellen (KOLLEX, OctopusOrder, Gastivo) unterstützt die Anwendung auch EDI-Formate}}


==Bereitstellung von Daten==
==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.
Im einfachsten Fall werden Stammdaten als [[wikipedia:de:CSV_%28Dateiformat%29|CSV]]-Daten bereitgestellt und auf einen [[wikipedia:de:File_Transfer_Protocol|FTP]]-Server übertragen. Die Auftragsdaten werden als [[wikipedia:de:Extensible_Markup_Language|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 [[Aufträge_importieren|hier]].
* Informationen für die Auftragsverarbeitung finden Sie [[Aufträge_importieren|hier]].
* Die Einstellungen für für den Datenaustausch mit WEBDRINK finden Sie [[WEBDRINK-Schnittstelle|hier]].
* Die Einstellungen für für den Datenaustausch mit WEBDRINK finden Sie [[WEBDRINK-Schnittstelle|hier]].
* Die Einstellungen für für den Datenaustausch mit Shopware oder Magento u.ä. finden Sie  [[Webshop-Schnittstelle|hier]].
* Die Einstellungen für für den Datenaustausch mit Shopware oder Magento u.ä. finden Sie  [[WEBDRINK-Schnittstelle|hier]].
 
=Stammdatenexport als CSV=
Die Daten werden mit einer FTP-Verbindung übertragen. Nach erfolgreichem Verbindungsaufbau werden die [[wikipedia:de:CSV_%28Dateiformat%29|CSV]]-Daten in einem zu definierenden Ordner kopiert.
 
==Kunden.csv==
Nachfolgend wird ein Kundendatensatz beschrieben.
 
<!--//////////    Tabelle ANFANG      //////////-->
:{| class="wikitable" style="text-align:left"
! style="background:#B3B7FF" | Feld
!! style="background:#B3B7FF" | Typ
!! style="background:#B3B7FF" | 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
|-
|Telefon 1
|Alphanumerisch
|optional
|-
|Telefon 2
|Alphanumerisch
|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
|}
<!--//////////    Tabelle ENDE      //////////-->


==Stammdatenexport als CSV==
==Lieferadressen.csv==
'''Folgende Standards werden voreingestellt:'''
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.


* Daten werden durch Semikola getrennt, bereitgestellt. Jeder Datensatz wird mit einem Semikolon abgeschlossen.
<!--//////////    Tabelle ANFANG      //////////-->
* Es werden keine Delimiter verwendet, der Typ eines Datensatzes ergibt sich aus der Reihenfolge.
:{| class="wikitable" style="text-align:left"
* Der Zeichensatz ist Windows 1252 (ANSI).
! style="background:#B3B7FF" | Feld
!! style="background:#B3B7FF" | Typ
!! style="background:#B3B7FF" | 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
|-
|Telefon
|Alphanumerisch
|Telefon 1, optional
|-
|Ident
|Alphanumerisch
|Kennung der Adresse
|}
<!--//////////    Tabelle ENDE      //////////-->


{{Tipp1|Eine Anpassung oder Erweiterung ist nach Absprache kostenpflichtig möglich.}}
==Artikel.csv==
Nachfolgend wird ein Artikeldatensatz beschrieben.  


===Feldbeschreibungen Datei "Kunden.csv“===
//->
<!--//////////    Tabelle ANFANG      //////////-->
<!--//////////    Tabelle ANFANG      //////////-->
{| class="wikitable"
:{| class="wikitable" style="text-align:left"
! style="background:#B3B7FF" | Feld
!! style="background:#B3B7FF" | Typ
!! style="background:#B3B7FF" | Information
|-
|Versionsnummer
|Alphanumerisch
|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
|}
<!--//////////    Tabelle ENDE      //////////-->
 
==Favoriten.csv==
Nachfolgend wird ein Kundensortimentsdatensatz beschrieben. Diese Liste enthält die bisher bestellten Artikel eines Kunden. Die Datei ist optional.
 
<!--//////////    Tabelle ANFANG      //////////-->
:{| class="wikitable" style="text-align:left"
! style="background:#B3B7FF" | Feld
!! style="background:#B3B7FF" | Typ
!! style="background:#B3B7FF" | Information
|-
|KDNr
|Alphanumerisch
|Eindeutige Identnummer des Kunden
|-
|ArtNr
|Alphanumerisch
|Eindeutige Identnummer des Artikels
|-
|Anzahl
|Ganzzahl
|übliche Bestellmenge
|}
<!--//////////    Tabelle ENDE      //////////-->
 
==Sonderpreise.csv==
Nachfolgend wird eine Tabelle mit kundenspezifischen oder zeitlich beschränkten Sonderpreisen beschrieben. Die Datei ist optional.
 
<!--//////////    Tabelle ANFANG      //////////-->
:{| class="wikitable" style="text-align:left"
! style="background:#B3B7FF" | Feld
!! style="background:#B3B7FF" | Typ
!! style="background:#B3B7FF" | 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
|}
<!--//////////    Tabelle ENDE      //////////-->
 
''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 [[wikipedia:de:Extensible_Markup_Language|XML]]-Daten aus einem zu definierenden Ordner geladen.
 
'''Bedingungen:'''
 
* Elemente ohne Daten werden [[wikipedia:de:Extensible_Markup_Language|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 [[wikipedia:de:Extensible_Markup_Language|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.
 
<!--//////////    Tabelle ANFANG      //////////-->
:{| class="wikitable" style="text-align:left"
! style="background:#B3B7FF" | Entität
!! style="background:#B3B7FF" | Typ
!! style="background:#B3B7FF" | Beispiel
!! style="background:#B3B7FF" | 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)
|}
<!--//////////    Tabelle ENDE      //////////-->
 
== Die Entität "paymentDetails"==
 
Die Entität ist in <order> enthalten, optional und einmalig. Sie enthält optionale Informationen zur Zahlweise
 
<!--//////////    Tabelle ANFANG      //////////-->
:{| class="wikitable" style="text-align:left"
! style="background:#B3B7FF" | Entität
!! style="background:#B3B7FF" | Typ
!! style="background:#B3B7FF" | Beispiel
!! style="background:#B3B7FF" | Erläuterungen
|-
|<paymentSystem>
|Alphanumerisch
|Bank
|Zahlweise
|-
|<externalId>
|Alphanumerisch
|58
|EDI-Code der Zahlweise
|}
<!--//////////    Tabelle ENDE      //////////-->
 
==Die Entität "DeliveryDetails"==
 
Die Entität ist in <order> enthalten, optional und wiederholbar. Sie enthält optionale Informationen zu Transportkosten
 
<!--//////////    Tabelle ANFANG      //////////-->
:{| class="wikitable" style="text-align:left"
! style="background:#B3B7FF" | Entität
!! style="background:#B3B7FF" | Typ
!! style="background:#B3B7FF" | Beispiel
!! style="background:#B3B7FF" | Erläuterungen
|-
|<type>
|Auswahl (flat = pauschal, tba.)
|flat
|Berechnungsweise
|-
|<name>
|Alphanumerisch
|Anfahrtspauschale
|Bezeichnung
|-
|<price>
|Kommazahl
|5.00
|Betrag
|}
<!--//////////    Tabelle ENDE      //////////-->
==Die Entität "article"==
 
Die Entität ist in <order> enthalten, (thoretisch) optional und wiederholbar. Sie enthält Informationen zu Bestellposten
 
<!--//////////    Tabelle ANFANG      //////////-->
:{| class="wikitable" style="text-align:left"
! style="background:#B3B7FF" | Entität
!! style="background:#B3B7FF" | Typ
!! style="background:#B3B7FF" | Beispiel
!! style="background:#B3B7FF" | 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
|}
<!--//////////    Tabelle ENDE      //////////-->
 
==Die Entität "customer"==
 
Die Entität ist primär, notwendig und einmalig. Sie enthält Informationen zum Kunden
 
<!--//////////    Tabelle ANFANG      //////////-->
:{| class="wikitable" style="text-align:left"
! style="background:#B3B7FF" | Entität
!! style="background:#B3B7FF" | Typ
!! style="background:#B3B7FF" | Beispiel
!! style="background:#B3B7FF" | 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
|-
|-
! Feld!! Typ!! Information
|<town>
|Alphanumerisch
|Haiger
|Ort
|-
|-
KDNr || A20 (eingeschränkter Zeichensatz) || Eindeutige Identnummer
|<salutation>
|Alphanumerisch
|Herr
|Anrede
|-
|-
Anrede A10 Anrede, optional
|<title>
|Alphanumerisch
|Prof. Dr.
|Titel
|-
|-
Vorname A80 Vorname, optional
|<company>
|Alphanumerisch
|Mustermann AG
|Firma
|-
|-
Name/Firma A80 Firmenname oder Name
|<name>
|Alphanumerisch
|Mustermann
|Name
|-
|-
Zusatz A80 optional Abteilung etc.
|<firstName>
|Alphanumerisch
|Max
|Vorname
|-
|-
Strasse A20 Straße mit Hausnummer
|<phone>
|Alphanumerisch
|02773-12345
|Telefonnummer
|-
|-
PLZ A5 ohne Nationalitätskennzeichen
|<fax>
|Alphanumerisch
|
|Telefaxnummer
|-
|-
Ort A80 Ort
|<mobile>
|Alphanumerisch
|0175-1234567
|Mobilfunknummer
|-
|-
Telefon A20 Telefon 1, optional
|<email>
|Alphanumerisch
|info@mail.de
|E-Mailadresse
|-
|-
Mobil A20 Telefon 2, optional
|<registrationDate>
|Zeitstempel ISO-8601
|2012-04-03 15:00:00
|Registrierdatum
|-
|-
Email A255 Mehrfacheinträge mit „,“ getrennt
|<dateOfBirth>
|Zeitstempel ISO-8601
|
|Geburtsdatum (wird nicht ausgewertet)
|-
|-
StNr A40 StNr. oder USt.ID, optional
|<dataStatus>
|Auswahl(new = Neu, tba)
|new
|
|-
|-
BIC A10 ohne Leerzeichen, optional
|<newsletter>
|Logisch (ja, nein/leer)
|
|Newsletteranmeldung
|}
<!--//////////    Tabelle ENDE      //////////-->
 
==Die Entität "DeliveryAddress"==
 
Die Entität ist in <customer> enthalten, optional und einmalig. Sie enthält optionale Informationen zur Lieferadresse
 
<!--//////////    Tabelle ANFANG      //////////-->
:{| class="wikitable" style="text-align:left"
! style="background:#B3B7FF" | Entität
!! style="background:#B3B7FF" | Typ
!! style="background:#B3B7FF" | Beispiel
!! style="background:#B3B7FF" | Erläuterungen
|-
|-
IBAN A30 Darf Leerzeichen enthalten, optional
|<street>
|Alphanumerisch
|Musterstraße
|Straße (darf Hausnummer enthalten)
|-
|-
Bar L [FALSCH, WAHR] Kunde muss bei Lieferung zahlen
|<streetNumber>
|Alphanumerisch
|10b
|Hausnummer (optional)
|-
|-
Gewerbe L [FALSCH, WAHR] Gewerbe oder Privatkunde
|<additionalAddressInformation
|Alphanumerisch
|5. Etage
|Zusatzinformationen
|-
|-
Limit N [-1, 0, n] -1 = gesperrt, 0 = kein Limit
|<postcode>
|Ganzzahl
|35708
|Postleitzahl
|-
|-
Preisgruppe I [1-n] Preisgruppenliste
|<town>
|Alphanumerisch
|Haiger
|Ort
|-
|-
|<title>
|Alphanumerisch
|Prof. Dr.
|Titel
|-
|<company>
|Alphanumerisch
|Mustermann AG
|Firma
|-
|<name>
|Alphanumerisch
|Mustermann
|Name
|-
|<firstName>
|Alphanumerisch
|Max
|Vorname
|}
<!--//////////    Tabelle ENDE      //////////-->
==Die Entität "BankDetails"==
Die Entität ist in <customer> enthalten, optional und einmalig. Sie enthält optionale Informationen zur Bankverbindung
<!--//////////    Tabelle ANFANG      //////////-->
:{| class="wikitable" style="text-align:left"
! style="background:#B3B7FF" | Entität
!! style="background:#B3B7FF" | Typ
!! style="background:#B3B7FF" | Beispiel
!! style="background:#B3B7FF" | Erläuterungen
|-
|<accountOwner>
|Alphanumerisch
|Max Mustermann
|Kontoinhaber
|-
|<Iban>
|Alphanumerisch
|DE67416500011234567890
|IBAN
|-
|<bic>
|Alphanumerisch
|WELADED1LIP
|BIC
|}
<!--//////////    Tabelle ENDE      //////////-->
{{Hinweis|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.}}
{{Hinweis|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.}}
==Beispiel einer 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></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>


=JSON =
Die Anwendung unterstützt den Auftragsimport mittels REST-API. Die Kommunikation erfolgt über eine HTTPS-Schnittstelle, welche JSON-Objekte im Request-Body erwartet. Die Zeichenkodierung ist UTF-8.
==JSON-Objekte==
JSON Request-Objekt:
*'''id:''' Eindeutiger Identifier innerhalb des Requests.
*'''command:''' String für den auszuführenden Command.
*'''params:''' Parameter für den Command.
JSON Response-Objekt:
*'''id:''' Hierbei handelt es sich um die übergebene Id des Requests.
*'''result:''' Bei einer erfolgreichen Verarbeitung wird immer ein result übergeben. Bei einem error existiert dieser Wert nicht.
*'''error:''' Ausschließlich bei einem Fehler existiert dieses Objekt. Es unterteilt sich immer in code und message. Bei einem Validierungsfehler wird ein Objekt input übergeben. Die Keys des Objektes enthalten die fehlgeschlagenen Parameter einschließlich der Fehlermeldung.
* Single data sent to Server:
{"id":"1","command":"articles/set","params":{"data":{"articleNumber":"H64326426","name":"Testartikel","quantity":3,"unit":1.74,"taxRate":19,"prices":[{"priceGroup":"1","fromArticleQuantity":1,"fromCartQuantity":1,"netPrice":8.15,"netDeposit":0}],"groups":[{"groupName":"Testgruppe"}]}}}
* Single data receive from Server:
{"id":"1","result":{"articles":{"data":{"id":"63f8340b5f86a975e10f8725"}}}}
*Batch data sent to Server:
[{"id":"1","command":"articles/update","params":{"data":{"articleNumber":"1","availability":"Kein Bestand"}}}, {"id":"2","command":"articles/update","params":{"data":{"articleNumber":"2","availability":"Kein Bestand"}}}]
*Batch data received from Server:
[{"id":"1","result":{"articles":{"updated":{"matched":1,"upserted":0,"modified":1}}}}, {"id":"2","result":{"articles":{"updated":{"matched":1,"upserted":0,"modified":1}}}}]
==Authentifizierung==
Die Authentifizierung erfolgt über einen API-Token, welcher über den Header "Authorisation: Bearer apiToken" wird.
cURL Beispiel-Request:
curl -X POST <domain>
-H "Authorisation: Bearer apiToken"
-H "Content-Type: application/json"
-d "{"id": 1,"command":"articles/delete", "params": {"data":{"articleNumber": "123"}}}"
= Stammdatenexport als JSON =
== Artikel ==
<!--//////////    Tabelle ANFANG      //////////-->
:{| class="wikitable" style="text-align:left"
! style="background:#B3B7FF" | Entität
!! style="background:#B3B7FF" | Typ
!! style="background:#B3B7FF" | Beispiel
!! style="background:#B3B7FF" | Erläuterungen
|-
|articleNumber
|Alphanumerisch (20 Zeichen)
|12345
|Eindeutige Artikelnummer
|-
|articleName
|Alphanumerisch (225 Zeichen)
|Coca Cola Classic 12x 1,00l PET
|Artikelbezeichnung
|-
|articleManufacturer
|Alphanumerisch (255)
|Coca Cola
|Hersteller
|-
|articleGroup
|Alphanumerisch (255)
|Limonade
|Warengruppe
|-
|articlePackage
|Alphanumerisch (20)
|Kasten
|Verpackungseinheit
|-
|articleVolume
|Kommazahl
|12.00
|Inhalt (Liter)
|-
|articleWeight
|Kommazahl
|15.00
|Masse (kg)
|-
|availGeneral
|Alphanumerisch (255)
|lagernd
|Informatione zur Verfügbarkeit
|-
|availStock
|Ganzzahl
|123
|Bestand
|-
|articleDescription
|Objekt
|Koffeinhaltiges Erfrischungsgetränk mit Pflanzenextrakten
|Artikelbeschreibung
|-
|articleAdditionalData
|Objekt
|Entdecke die Welt von Coca-Cola!
|Weitere Artikelinformationen
|-
|articleLegalInfo
|Objekt
|Wasser, Zucker, Kohlensäure, Farbstoff E 150d, Phosphorsäure, natürliche Aromen, koffeinhaltig
|Pflichtangaben
|-
|articlekeywords
|Objekt
|Cola, Limonade
|Suchwörter
|-
|articleImages
|Objekt
|keine
|Artikelabbildungen
|-
|articleTaxRate
|Kommazahl
|19.0
|Mehrwertsteuersatz
|-
|articlePriceGroups
|Array
|Gewerbe, Privat
|Preisgruppen
|-
|articlePriceNetto
|Array
|9.99, 10.9159
|Preise (Netto)
|-
|unitContentCount
|Ganzzahl
|12
|Einzelgebinde in der Verpackungseinheit
|-
|UnitContentVol
|Kommazahl
|1.00
|Inhalt Einzelgebinde in Liter
|-
|depositTaxRate
|Kommazahl
|19.0
|Mehrwertsteuersatz Pfand
|-
|depositNetto
|Kommazahl
|3.30
|Pfandwert (Netto)
|-
|depositPackageType
|Alphanumerisch (40)
|Kasten 3,30 (12x 0,15 €)
|Pfandbezeichnung
|-
|depositType
|Alphanumerisch (20)
|MEHRWEG
|Einweg oder Mehrweg
|}
|}
<!--//////////    Tabelle ENDE      //////////-->
<!--//////////    Tabelle ENDE      //////////-->


===Optional: Feldbeschreibungen Datei "Lieferadressen.csv“===
==Bestandsänderungen==
//->
<!--//////////    Tabelle ANFANG      //////////-->
===Feldbeschreibungen Datei "Artikel.csv“===
:{| class="wikitable" style="text-align:left"
//->
! style="background:#B3B7FF" | Entität
===Optional: Feldbeschreibungen Datei "Favoriten.csv“===
!! style="background:#B3B7FF" | Typ
//->
!! style="background:#B3B7FF" | Beispiel
===Optional: Feldbeschreibungen Datei "Sonderpreise.csv“===
!! style="background:#B3B7FF" | Erläuterungen
//->
|-
==Auftragsimport als XML==
|storageIdent
//->
|Alphanumerisch(20)
===Entität "Order"===
|10110
//->
|Artikelnummer
===Entität "Article"===
|-
//->
|storageStock
===Entität "DeliveryDetails"===
|Ganzzahl
//->
|119
===Entität "Customer"===
|Neuer Bestand
//->
|}
===Entität "DeliveryAddress"===
<!--//////////    Tabelle EDE      //////////-->
//->
 
===Entität "BankDetails"===
==Kunden==
//->
<!--//////////    Tabelle ANFANG      //////////-->
==Beispieldateien==
:{| class="wikitable" style="text-align:left"
//->
! style="background:#B3B7FF" | Entität
!! style="background:#B3B7FF" | Typ
!! style="background:#B3B7FF" | Beispiel
!! style="background:#B3B7FF" | Erläuterungen
|-
|customerNumber
|Alphanumerisch (20)
|10210
|Kundennummer
|-
|customerMail
|Alphanumerisch (255)
|muellermeierschmidt@gmx.de
|E-Mail
|-
|customerPriceGroup
|Alphanumerisch (20)
|Gewerbe
|Preisgruppe
|-
|customerAddresses
|Array
|Lieferadressen (ident, strasse, plz, ort, vorname, name, zusatz, telefon)
|-
|customerpriceMode
|Integer
|1
|Preismodus (1: Gewerbe, 2: Privat)
|-
|customerStatus
|Alphanumerisch (20)
|Status (new, changed, unchanged, inactive)
|-
|customerDiscount
|Kommazahl
|3.00
|Prozentualer Rabatt
|-
|customerFavorites
|Array
|12345, 10
|Liste von Artikelnummern und Bestellmengen
|-
|customerPrices
|Array
|12345, 9.50
|Kundensepzifische Preise
|-
|customerPaymentType
|Ganzzahl
|59
|Zahlweise als EDI Payment Means Typ Code
|-
|customerPaymentIdent
|Alphanumerisch 30
|DE3541507001000567305
|Information zur Zahlweise (Einzug: IBAN)
|}
 
=Bestellimport als JSON=
 
<!--//////////    Tabelle ANFANG      //////////-->
:{| class="wikitable" style="text-align:left"
! style="background:#B3B7FF" | Entität
!! style="background:#B3B7FF" | Typ
!! style="background:#B3B7FF" | Beispiel
!! style="background:#B3B7FF" | Erläuterungen
|-
|orderIdent
|Alphanumerisch(20)
|10110
|Auftragsnummer
|-
|orderDeliveryAdressIdent
|Ganzzahl
|1
|Identnummer der Lieferadresse
|-
|orderInvoiceAdressIdent
|Ganzzahl
|1
|Identnummer der Rechnungsadresse
|-
|orderDate
|Zeitstempel
|2026-06-20 13:05:21
|Bestellzeitpunkt
|-
|orderIP
|Alphanumerisch
|123.456.789.012
|IP Adresse der Bestellung
|-
|DeliveryDate
|Zeitstempel
|2026-06-22 14:00:00
|Wunschtermin Lieferung
|-
|DeliveryInfo
|Alphanumerisch(255)
|bitte in Garage abstellen
|Hinweise zur Bestellung
|-
|paymentType
|Ganzzahl
|59
|Zahlweise als EDI Payment Means Typ Code
|-
|paymentIdent
|Alphanumerisch 30
|DE3541507001000567305
|Information zur Zahlweise (Einzug: IBAN)
|-
|orderPositions
|array
|12345, 5
|Bestellposten (articleIdent, articleQuantity)
|}
 
= Einzelnachweise =
 
<references />
Abgerufen von „https://wiki.fakturax.de/index.php?title=Schnittstellenleitfaden“