Schnittstellenleitfaden: Unterschied zwischen den Versionen

Zur Navigation springen Zur Suche springen
← Zum vorherigen Versionsunterschied
Keine Bearbeitungszusammenfassung
 
(10 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 26: Zeile 26:
Der entstandenen Aufwand wird dokumentiert.
Der entstandenen Aufwand wird dokumentiert.


=Dateiformate=
==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]]'''
'''[[wikipedia:de:CSV_%28Dateiformat%29|CSV-Dateien]]'''
Zeile 39: Zeile 61:
* Zeichensatz ist UTF-8
* Zeichensatz ist UTF-8


=Dateitransfer=
==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  
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  


Zeile 49: Zeile 71:
{{Tipp1|Neben den branchenspezifischen Schnittstellen (KOLLEX, OctopusOrder, Gastivo) unterstützt die Anwendung auch EDI-Formate}}
{{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 [[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.
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.


Zeile 59: Zeile 81:
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.
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.


==Formatkennzeichen==
==Kunden.csv==
 
{| class="wikitable"
! 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.
Nachfolgend wird ein Kundendatensatz beschrieben.


Zeile 120: Zeile 122:
|Ort
|Ort
|-
|-
|Telefon 1
|Alphanumerisch
|Alphanumerisch
|A20
|optional
|Telefon 1, optional
|-
|-
|Telefon 2
|Alphanumerisch
|Alphanumerisch
|A20
|optional
|Telefon 2, optional
|-
|-
|Email
|Email
Zeile 162: Zeile 164:
<!--//////////    Tabelle ENDE      //////////-->
<!--//////////    Tabelle ENDE      //////////-->


==Optional: Feldbeschreibungen Datei "Lieferadressen.csv“==
==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.
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.


Zeile 192: Zeile 194:
|-
|-
|Strasse
|Strasse
|A20
|Alphanumerisch
|Straße mit Hausnummer
|Straße mit Hausnummer
|-
|-
Zeile 213: Zeile 215:
<!--//////////    Tabelle ENDE      //////////-->
<!--//////////    Tabelle ENDE      //////////-->


==Feldbeschreibungen Datei "Artikel.csv“==
==Artikel.csv==
Nachfolgend wird ein Artikeldatensatz beschrieben.  
Nachfolgend wird ein Artikeldatensatz beschrieben.  


Zeile 296: Zeile 298:
<!--//////////    Tabelle ENDE      //////////-->
<!--//////////    Tabelle ENDE      //////////-->


==Optional: Feldbeschreibungen Datei "Favoriten.csv“==
==Favoriten.csv==
Nachfolgend wird ein Kundensortimentsdatensatz beschrieben. Diese Liste enthält die bisher bestellten Artikel eines Kunden. Die Datei ist optional.
Nachfolgend wird ein Kundensortimentsdatensatz beschrieben. Diese Liste enthält die bisher bestellten Artikel eines Kunden. Die Datei ist optional.


Zeile 319: Zeile 321:
<!--//////////    Tabelle ENDE      //////////-->
<!--//////////    Tabelle ENDE      //////////-->


==Optional: Feldbeschreibungen Datei "Sonderpreise.csv“==
==Sonderpreise.csv==
Nachfolgend wird eine Tabelle mit kundenspezifischen oder zeitlich beschränkten Sonderpreisen beschrieben. Die Datei ist optional.  
Nachfolgend wird eine Tabelle mit kundenspezifischen oder zeitlich beschränkten Sonderpreisen beschrieben. Die Datei ist optional.  


Zeile 362: Zeile 364:
<!--//////////    Tabelle ENDE      //////////-->
<!--//////////    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.
''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=
=Auftragsimport als XML=
Zeile 378: Zeile 380:
  <order>
  <order>
   [notwendig, einmal]
   [notwendig, einmal]
 
   <paymentDetails>
   <paymentDetails>
     [optional, einmal]
     [optional, einmal]
   </paymentDetails>
   </paymentDetails>    
   
   <DeliveryDetails>
   <DeliveryDetails>
     [optional, mehrfach]
     [optional, mehrfach]
   </DeliveryDetails>
   </DeliveryDetails>  
   <article>
   <article>
     [optional, mehrfach]
     [optional, mehrfach]
Zeile 392: Zeile 391:
  </order>
  </order>
  <customer>
  <customer>
   [notwendig, einmal]
   [notwendig, einmal]
 
   <DeliveryAddress>
   <DeliveryAddress>
     [optional, einmal]
     [optional, einmal]
   </DeliveryAddress>
   </DeliveryAddress>
   <BankDetails>
   <BankDetails>
     [optional, einmal]
     [optional, einmal]
Zeile 965: Zeile 962:
  </customer>
  </customer>


= Auftragsimport als JSON =
=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"}}}"
 
==Artikel==
= Auftragsimport als 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.
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.


Zeile 1.034: Zeile 996:
  -d "{"id": 1,"command":"articles/delete", "params": {"data":{"articleNumber": "123"}}}"
  -d "{"id": 1,"command":"articles/delete", "params": {"data":{"articleNumber": "123"}}}"


==Artikel==
= Stammdatenexport als JSON =
== Artikel ==
<!--//////////    Tabelle ANFANG      //////////-->
<!--//////////    Tabelle ANFANG      //////////-->
:{| class="wikitable" style="text-align:left"
:{| class="wikitable" style="text-align:left"
Zeile 1.241: Zeile 1.204:
|}
|}


==Bestellungen==
=Bestellimport als JSON=
 
<!--//////////    Tabelle ANFANG      //////////-->
<!--//////////    Tabelle ANFANG      //////////-->
:{| class="wikitable" style="text-align:left"
:{| class="wikitable" style="text-align:left"
Abgerufen von „https://wiki.fakturax.de/index.php?title=Schnittstellenleitfaden“