Dokumentation Custom CSV
Was ist Custom CSV?
Der Custom CSV Importer ermöglicht es Ihnen, 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. Sie müssen sicherstellen, dass entweder der Shop die Daten im korrekten Format exportiert oder dass Sie die Datei in das passende Format umwandeln. Ein Beispiel für dieses Format finden Sie hier.
In diesem Beitrag erfahren Sie, wie Sie Ihre Daten optimal für den Custom CSV-Import vorbereiten und anschließend in easybill Connect (ehem. Import Manager) einpflegen können.
CSV Dateiformat
Allgemeines Format
Das allgemeine Format bildet die Grundlage für den Import Ihrer 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 stellen Sie sicher, dass Ihre 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 Ihre Daten vollständig und fehlerfrei in easybill ankommen.
Feldtypen
Für einen fehlerfreien Import ist es entscheidend, dass die Daten in Ihrer 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 finden Sie 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
Sie haben die Möglichkeit, in Ihrer 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 Sie als auch unser Support schnell erkennen, von welchem System die CSV-Datei stammt.
Daten importieren
easybill bietet Ihnen mehrere flexible Methoden, um Ihre CSV-Dateien hochzuladen. Wählen Sie die für Ihren Workflow passende Variante:
Direkter Datei-Upload
Laden Sie Ihre CSV-Datei einfach über unsere Web-Oberfläche hoch. Dies ermöglicht Ihnen, den Import zunächst zu testen – unser System prüft automatisch das Dateiformat und signalisiert eventuelle Fehler.
Automatischer FTP-Datenabruf
Möchten Sie Ihre CSV-Dateien vollautomatisch in easybill importieren, nutzen Sie 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:
Sie können die FTP-Polling-Einstellungen direkt in easybill Connect vornehmen. Navigieren Sie dazu zu Einstellungen > Weitere Shops.
In der Shop Übersicht suchen Sie nach Custom CSV und klicken auf Einrichten, um zu den Custom CSV Einstellungen zu gelangen.
Anschließend scrollen Sie herunter, um Ihre FTP-Zugangsdaten einzugeben.
Einstellungen
-
FTP-Zugang hinterlegen
In Ihrem easybill-Konto können Sie unter den Importeinstellungen die Zugangsdaten für Ihren FTP-Server hinterlegen. Hier definieren Sie 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 müssen Sie sich nicht mehr manuell um den Upload kümmern.
-
Optionale URL (HTTP Ping)
Zusätzlich können Sie 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
Nutzen Sie unsere neue REST API, um den Import direkt und automatisiert anzustoßen. Unsere API-Dokumentation finden sie unter:
https://connect-api-docs.easybill.com/#post-/orders/upload