Dokumentation Custom CSV
Was ist Custom CSV?
Der Custom CSV Importer ermöglicht es dir, Daten aus Shops und Marktplätzen zu importieren, die nicht nativ von easybill unterstützt werden.
Es handelt sich um ein vordefiniertes CSV-Format, das vom Importer erwartet wird. Du musst sicherstellen, dass entweder der Shop die Daten im korrekten Format exportiert oder dass du die Datei in das passende Format umwandelst. Ein Beispiel für dieses Format findest du hier.
In diesem Beitrag erfährst du, wie du deine Daten optimal für den Custom CSV-Import vorbereiten und anschließend in easybill Connect einpflegen kannst.
CSV Dateiformat
Allgemeines Format
Das allgemeine Format bildet die Grundlage für den Import deiner Daten. Hierbei sind folgende Punkte besonders wichtig:
- Zeichencodierung: Die CSV-Dateien sollten idealerweise in UTF-8 kodiert sein (alternativ ist ISO-8859-1 möglich, wird aber nicht empfohlen).
- Feldtrenner: Im Custom CSV Import wird das Semikolon (;) als gültiger Feldtrenner akzeptiert. Bitte stelle sicher, dass deine CSV-Datei dieses Trennzeichen verwendet.
- Kopfzeile: Die erste Zeile der Datei muss die Feldnamen enthalten. Unser System nutzt diese Überschriften, um die Daten den entsprechenden internen Feldern korrekt zuzuordnen – unabhängig von der Reihenfolge der Spalten.
Diese Grundlagen sorgen dafür, dass der Importprozess reibungslos abläuft und deine Daten vollständig und fehlerfrei in easybill ankommen.
Feldtypen
Für einen fehlerfreien Import ist es entscheidend, dass die Daten in deiner CSV-Datei den vorgegebenen Feldtypen entsprechen. Jeder Feldtyp legt fest, wie die enthaltenen Werte interpretiert und verarbeitet werden:
-
String:
Dieser Typ wird für beliebigen Text verwendet – auch für Inhalte mit Zeilenumbrüchen, sofern sie in Anführungszeichen eingeschlossen sind.
Beispiel:"A SAMPLE TEXT" -
Text:
Dieser Typ wird für umfangreiche Textinhalte verwendet – beispielsweise für detaillierte Beschreibungen, Kommentare oder längere Notizen.
Beispiel:"Dies ist ein längerer Text, der über mehrere Zeilen gehen kann. Er enthält detaillierte Informationen, die für den Import relevant sind." -
Decimal:
Dezimalwerte werden im FormatXXX.YYerwartet. Es sind Werte bis zu einer definierten Präzision (z. B. bis zu9,999,999,999.9999) zulässig.
Beispiel:100.00 -
Integer:
Ganze Zahlen ohne Nachkommastellen.
Beispiel:1 -
Date:
Datumsangaben müssen im FormatYYYY-MM-DDerfolgen.
Beispiel:2012-07-19 -
Datetime:
Für kombinierte Datums- und Zeitangaben wird das ISO-8601-Format verwendet.
Beispiel:2012-07-19T19:29:20+02:00
Die exakte Einhaltung dieser Formate stellt sicher, dass unser System die Daten korrekt interpretieren und zuordnen kann. Abweichungen können zu Importfehlern oder einer fehlerhaften Datenzuordnung führen.
Auftragsspezifische Felder
In diesem Abschnitt werden die Felder beschrieben, die sich explizit auf einen Auftrag (Bestellung) beziehen. Wichtig zu wissen: Wenn eine Bestellung über mehrere Zeilen (z. B. bei mehreren Artikeln) dargestellt wird, werden ausschließlich die Angaben der ersten Zeile für die Auftragsverarbeitung herangezogen. Alle weiteren Zeilen dienen lediglich zur Detailbeschreibung einzelner Artikel und werden hinsichtlich der übergeordneten Auftragsdaten ignoriert.
Hier die wichtigsten Felder im Überblick:
| Feldname | Beschreibung | Erforderlich | Format |
order_number |
Die eindeutige Bestellnummer dient als primärer Identifikator und stellt sicher, dass doppelte Importe vermieden werden. | Ja | String(1..255) |
order_number_2 |
Alternative oder sekundäre Bestellnummer. | Nein | String(0..255) |
email |
E-Mail-Adresse des Kunden. Optional, aber empfohlen für automatischen Rechnungsversand. | Nein | String(0..255) |
name |
Vollständiger Name oder Firmenbezeichnung. Erforderlich, wenn firstname und lastname nicht angegeben sind. |
Siehe Beschreibung | String(1..255) |
firstname |
Vorname des Kunden. Nicht notwendig, wenn name gesetzt ist. |
Siehe Beschreibung | String(1..255) |
lastname |
Nachname des Kunden. Nicht notwendig, wenn name gesetzt ist. |
Siehe Beschreibung | String(1..255) |
street |
Straße und ggf. Hausnummer. | Ja | String(1..255) |
address_1 |
Zusätzliche Adressinformationen. | Nein | String(0..255) |
address_2 |
Zusätzliche Adressinformationen. | Nein | String(0..255) |
address_3 |
Zusätzliche Adressinformationen. | Nein | String(0..255) |
zipcode |
Postleitzahl des Kunden. | Ja | String(0..255) |
city |
Ort des Kunden. | Nein | String(0..255) |
state |
Staat des Kunden. | Nein | String(0..255) |
country |
Ländercode im ISO-3166-1 Format (z. B. DE). | Ja | String(0..255) |
phone_number |
Telefonnummer des Kunden. Kann für Lieferdienste (z. B. DHL) benötigt werden. | Nein | String(0..255) |
fax_number |
Faxnummer des Kunden. | Nein | String(0..255) |
currency |
Währungscode (z.B. EUR, USD) | Ja | String(3) |
order_shipping_price |
Versandkosten, die unabhängig von den Artikeln für den gesamten Auftrag gelten. | Nein | Decimal(16,5) |
purchase_date |
Datum bzw. Datum und Uhrzeit des Kaufs. | Nein | Date oder DateTime |
shipping_date |
Versanddatum des Auftrags. | Nein | Date oder DateTime |
estimated_arrival_date |
Versanddatum des Auftrags. | Nein | Date order DateTime |
shipping_tracking |
Versand-Trackingnummer. | Nein | String(0..255) |
shipping_type |
Versandart (z. B. DHL, Hermes). Kann als Freitext verwendet werden. | Nein | String(0..255) |
payment_date |
Datum der Zahlung. | Nein | Date oder DateTime |
payment_type |
Verwendete Zahlungsmethode. | Nein | String(0..255) |
payment_reference |
Wird auf der Rechnung ausgegeben, ohne Weiterverarbeitung. | Nein | Text |
customer_number |
Externe Kundennummer, falls im Shop genutzt. | Nein | String(0..255) |
customer_username |
Externer Benutzername des Kunden. | Nein | String(0..255) |
customer_since |
Datum, seit dem der Kunde besteht. | Nein | Date oder DateTime |
shipping_name |
Empfängername bei separater Versandadresse. | Nein | String(0..255) |
shipping_firstname |
Vorname des Empfängers bei separater Versandadresse. | Nein | String(0..255) |
shipping_lastname |
Nachname des Empfängers bei separater Versandadresse. | Nein | String(0..255) |
shipping_city |
Ort der separaten Versandadresse. | Nein | String(0..255) |
shipping_zipcode |
PLZ der separaten Versandadresse. | Nein | String(0..255) |
shipping_state |
Bundesland der separaten Versandadresse. | Nein | String(0..255) |
shipping_country |
Ländercode der separaten Versandadresse. | Nein | String(2) |
shipping_street |
Straße der separaten Versandadresse. | Nein | String(0..255) |
shipping_address_1 |
Weitere Adressinfo zur Versandadresse. | Nein | String(0..255) |
shipping_address_2 |
Weitere Adressinfo zur Versandadresse. | Nein | String(0..255) |
shipping_address_3 |
Weitere Adressinfo zur Versandadresse. | Nein | String(0..255) |
invoice_number |
Bereits vergebene Rechnungsnummer. | Nein | String(0..255) |
store_id |
ID des Shops (z.B. für Multistore-Lösungen). | Nein | String(0..255) |
vat_id |
Umsatzsteuer-ID des Kunden. | Nein | String(0..255) |
tax_type |
Überschreibt die automatische Steuerarten-Erkennung. Mögliche Werte: - intra-community-trade- reverse-charge- not-taxable- not-taxable-eu- not-taxable-eu-no-vatid- export
|
Nein | String(0..255) |
fulfillment_country |
Ursprungsland der Lieferung, relevant für die Steuerberechnung. | Nein | String(0..255) |
comments |
Freitextfeld für interne Hinweise oder Notizen. | Nein | Text |
Artikelspezifische Felder
Wenn eine Bestellung mehrere Artikel enthält, wird jeder Artikel in einer separaten Zeile innerhalb der CSV-Datei erfasst. Die artikelspezifischen Felder liefern dabei detaillierte Informationen zu jedem einzelnen Produkt, wie zum Beispiel Artikelnummer, Beschreibung, Menge, Preis und weitere ergänzende Angaben. Eine korrekte und vollständige Angabe dieser Felder ist entscheidend, damit die einzelnen Artikel während des Importprozesses eindeutig identifiziert und verarbeitet werden können.
Nachfolgend findest du eine Übersichtstabelle, die alle relevanten Felder, deren Beschreibungen, ob es ein Pflichtfeld ist, sowie Formatvorgaben zusammenfasst:
| Feldname | Beschreibung | Erforderlich | Format/Hinweise |
|---|---|---|---|
item_number |
Interne Artikelnummer zur Identifikation eines Artikels. | Nein | String(0..255) |
item_number_2 |
Sekundäre Artikelnummer für den Artikel. | Nein | String(0..255) |
sku |
Die SKU des bestellten Produkts. Falls diese im externen System definiert ist, sollte sie in der CSV-Datei hinterlegt werden, da wir die SKU für bestimmte Funktionen nutzen (z. B. automatische Mehrwertsteuerberechnungen basierend auf dem Produkt). | Nein | String(0..255) |
title |
Produktbeschreibung, die auf dem Dokument ausgegeben wird. | Ja | String(0..255) |
title_2 |
Zusätzliche optionale Produktbeschreibung. | Nein | String(0..255) |
quantity |
Anzahl der bestellten Einheiten des Artikels. | Ja | Integer |
item_price |
Bruttopreis pro Einheit des Artikels. | Ja | Decimal(16,5) |
item_shipping_price |
Versandkosten, die speziell diesem Artikel zugeordnet werden. | Nein | Decimal(16,5) |
vat_percent |
Mehrwertsteuersatz in Prozent, z. B. 19.00. Wird vat_percent nicht angegeben, erfolgt die Berechnung basierend auf Shop-Einstellungen oder alternativ über vat_rate. |
Nein | Decimal(5,2) |
vat_rate |
Alternativ zu vat_percent nutzbar. Unterstützte Werte: default, discount, digital_discount, reduced, reduced_1, reduced_2, super_reduced, parking. |
Nein | String(0..255) |
item_type |
Art des Artikels, z. B. product, discount, virtual. |
Nein | Product, discount, virtual |
item_weight |
Gewicht des Artikels, nutzbar z. B. über die Template-Variable {{item_weight}}. |
Nein | String(0..255) |
variant_yourKey |
Beliebig viele Varianteninformationen möglich, z. B. variant_color, variant_size, variant_model. Diese werden nicht automatisch verarbeitet, stehen aber z. B. als Platzhalter wie {{item_variant.color}} zur Verfügung. |
Nein |
Beispiel: Der Teil nach |
Hinweis zu mehreren Artikeln in einer Bestellung
Wenn eine Bestellung mehrere Artikel enthält, muss jeder Artikel in einer eigenen Zeile aufgeführt werden. Alle Zeilen zu derselben Bestellung müssen dabei aufeinanderfolgend sein. Die Reihenfolge ist entscheidend, damit unser System die Artikel korrekt einer Bestellung zuordnet.
Richtiges Beispiel (zwei Artikel in Bestellung order-1, dann ein Artikel in Bestellung order-2):
order-1;john doe;...;first-item;...
order-1;john doe;...;second-item;...
order-2;peter pan;...;first-item;...
Falsches Beispiel (die Zeilen zu order-1 sind unterbrochen von einer Zeile zu order-2):
order-1;john doe;...;first-item;...
order-2;peter pan;...;first-item;...
order-1;john doe;...;second-item;...
Kommentare in der CSV-Datei
Du hast die Möglichkeit, in deiner CSV-Datei Kommentarzeilen einzufügen. Diese können zum Beispiel dazu dienen, die Herkunft der Daten zu kennzeichnen oder interne Hinweise für Entwickler zu hinterlegen.
-
Ignorierte Zeilen:
Alle Zeilen, die mit #! beginnen, werden von unserem System ignoriert und nicht weiter verarbeitet.
-
Empfehlung für Entwickler:
Um bei der Fehleranalyse zu helfen oder die Datenquelle leichter zu identifizieren, empfehlen wir, mindestens eine Zeile einzufügen, die den Export- bzw. Systemnamen enthält, beispielsweise:
#! exported-by: NAME-IHRES-SYSTEMSAuf diese Weise können sowohl du als auch unser Support schnell erkennen, von welchem System die CSV-Datei stammt.
Daten importieren
easybill bietet dir mehrere flexible Methoden, um deine CSV-Dateien hochzuladen. Wähle die für deinen Workflow passende Variante:
Direkter Datei-Upload
Lade deine CSV-Datei einfach über unsere Web-Oberfläche hoch. Dies ermöglicht dir, den Import zunächst zu testen – unser System prüft automatisch das Dateiformat und signalisiert eventuelle Fehler.
Automatischer FTP-Datenabruf
Möchtest du deine CSV-Dateien vollautomatisch in easybill importieren, nutze den automatisierten FTP-Abruf über unser FTP-Polling. Dabei überprüft unser System in regelmäßigen Abständen einen vordefinierten FTP-Server auf neue CSV-Dateien. Sobald diese gefunden werden, erfolgt die automatische Verarbeitung der Dateien.
Hinweis: Da eine Übertragung per FTP unverschlüsselt erfolgt, empfehlen wir dringend die Nutzung von FTPS, um eine sichere Datenübertragung zu gewährleisten.
Zugriff auf die FTP-Polling-Einstellungen:
Du kannst die FTP-Polling-Einstellungen direkt in easybill Connect vornehmen. Navigiere dazu zu Einstellungen > Weitere Shops.
In der Shop Übersicht suchst du nach Custom CSV und klickst auf Einrichten, um zu den Custom CSV Einstellungen zu gelangen.
Anschließend scrollst du herunter, um deine FTP-Zugangsdaten einzugeben.
Einstellungen
-
FTP-Zugang hinterlegen
In deinem easybill-Konto kannst du unter den Importeinstellungen die Zugangsdaten für deinen FTP-Server hinterlegen. Hier definierst du Pfad und Dateiname(n), damit unser System die richtigen Dateien erkennen kann.
-
Zeitintervall
Unser System ruft den FTP-Server in regelmäßigen Abständen auf und prüft, ob neue Dateien vorliegen. Dadurch musst du dich nicht mehr manuell um den Upload kümmern.
-
Optionale URL (HTTP Ping)
Zusätzlich kannst du eine URL angeben, die von unserem System vor dem eigentlichen Download aufgerufen wird. Dies kann sinnvoll sein, wenn die CSV-Datei erst noch generiert werden muss.
REST API
Nutze unsere neue REST API, um den Import direkt und automatisiert anzustoßen. Unsere API-Dokumentation findest du unter:
https://connect-api-docs.easybill.com/#post-/orders/upload