EasyUp2, CSV-Dateiformat für Aufträge

Mit diesem Dateiformat können Transportaufträge einem 'Shipping Agent' übergeben werden.

Inhalt:
1) Dateiname, Zeichensatz, Kompression & Übergabe
2) Zeilendarstellung, Grenzen & Formalprüfungen
3) Felddarstellung
4) Feldliste
5) Beispieldateien


Copyleft-Hinweis: Dieses Spezifikation steht unter GNU Public Licence ("GPL"), siehe http://www.gnu.org/copyleft/gpl.html. Das bedeutet, sie darf kopiert werden, sie darf ohne Beschränkung und ohne Lizenzkosten verwendet werden und sie darf auch verändert werden. Dieser "Copyleft-Hinweis" muß allerdings erhalten bleiben. Die GPL-Eigenschaften dürfen nicht verletzt werden.
Geschrieben von Klaus Daum, DE-19067 Retgendorf, kd@orderrace.com, Erstversion Jan-2001

Änderungen:
2003-02-17, v24, kd: Neue Felder gival, gicurr, codval und codcurr
2003-02-20, v25, kd: Feldgruppierung verbessert
2004-03-05, v26, kd: Felder dk1 und dk1a ergaenzt
2004-04-13, v26, kd: GG Spec entfernt, LBH je Zeile neu, colliid neu
2004-06-30, v27, kd: GG redef
2004-07-18, v28, kd: Tippfehler in "dimheight" behoben, nur noch Zeilen-Dim.
2004-07-20, v29, kd: neues Feld "fzkids"
2004-11-30, v30, kd: lhanz/lhvp neu
2005-02-23, v31, kd: sub-anz/vp
2005-10-07, v32, kd: Ladedatum
2006-04-18, v33, kd: loadaids, eid1
2007-02-12, v34, kd: Hol-Adr (xh*) und eemail
2007-03-15, v35, kd: Absender-Adr (xa*)
2007-04-10, v36, kd: neu loadtime, termdata um die Bis-Zeit erweitert
2007-07-16, v37, kd: neu codtype
2008-03-17, v38, kd: Austraggeber (agkids)
2008-09-30, v39, kd: neue Spalte spl
2009-01-16, v40, kd: neue Spalten xhfone und xhtmsg
2009-05-02, v41, kd: neue Spalte lomo, Erweiterung dk1..5, Beispiel 1
2010-02-23, v42, kd: neue Spalte loadlen
2011-07-01, v43, kd: Frachtzahler, ggGug
2012-02-01, v44, kd: neue Spalten prod (produkt-schluessel), egln (empfaenger-gln), ggGbam1, wgroup/wg?
2019-11-13, v45, pl: neue Spalte control
2019-11-29, v46, pl: liter je Sendungszeile
2020-01-13, v47, pl: neue Spalte 'yellownote'



1) Dateiname, Zeichensatz, Kompression & Übergabe

Dateiname:
- max. Länge 30 Zeichen inkl. Endung
- nur aus den Zeichen a..z, A..Z, 0..9 (Ausnahme "." für dokumentierte Endungen)
- der Dateiname beginnt mit "eu2"

Zeichensatz und Kompression:
Endung des Dateinamens
Bedeutung
ohne
Zeichensatz ISO-8859-1, keine Kompression
".gz"
Zeichensatz ISO-8859-1, mit gz-Kompression
".utf8"
Zeichensatz UTF-8, keine Kompression
".utf8.gz"
Zeichensatz UTF-8, mit gz-Kompression
Dateien mit andere Endungen werden abgewiesen. OrderRace2 erlaubt derzeit keine Endung.

Wir raten aus folgenden Gründen zur Kompression mit "gzip" (gz):
- weniger Transportzeit
- weniger Transportkosten
- Sicherung gegen Bitfehler
- Prüfung auf Vollständigkeit / Transportabbruch
- geringe Anfälligkeit für Sicherheitsprobleme aufgrund des großen Nutzerbasis & Open Source
Das Datei- und Kompressionsformat "gz" ist verschieden vom Packer "pkzip" oder "zip" - der für diesen Zweck nicht unterstützt wird. Quellencode und ausführbare Programme für gzip (GNU-Zip) finden Sie auf der Homepage http://www.gzip.org.

PGP-Dateiverschlüsselung ist auf Anfage möglich.

Die Standard-Methode der Dateiübergabe ist HTTP-Upload via OrderRace ("Datei Senden" in "Verwaltung"). Nach Absprache sind auch email-Attach und FTP/SCP möglich.

Erwartete Eindeutigkeit der Dateinamen und Kompression je nach ja Übergabemethode:
Übergabe via
Eindeutigkeit Dateiname
Kompression
HTTP-Upload
Dateiname darf ohne Einschränkung wiederverwendet werden - immer der gleiche ok
freigestellt
email-Attach
Soll, muß aber nicht eindeutig sein (besser zur Fehlerdiagnose)
freigestellt
FTP / SCP
Dateiname darf innerhalb von 35 Kalendertagen nicht erneut verwendet werden.
oligatorisch



2) Zeilendarstellung, Grenzen & Formalprüfungen

Zeilenende wahlweise mit
- CR
- CR,LF
- LF oder
- LF, CR
OrderRace2 erlaubt als Zeilenende bisher nur CR gefolgt von LF.

Alle anderen nicht druckbaren Steuerzeichen sollen nicht vorkommen bzw. werden ausgefiltert.

Eine Datei muß zwischen 2 und 1000 Zeilen inkl. Kopfzeile enthalten. Also maximal 999 Aufträge je Datei.

Zum Abbruch des Ladevorganges auf der formalen Prüfebene führen:
- Fehler im Dateinamen
- Dekompressionsfehler (falls mit gz-Kompression)
- UTF-8 Formalfehler (ungültige UTF-Sequenzen)
- Dateigröße (nach Dekompression) < 15 oder > [slimitUpload])
- Zeilen mit einer Zeichenanzahl von weniger als 10 (auch Leerzeilen) oder mehr als 20000.
- Anzahl Zeilen kleiner 2 oder größer 1000
- Anzahl Header-Felder < 3 oder > 250
- Anzahl Datenfelder in einer Zeile ungleich Anzahl Headerfelder
- Länge eines Feldwertes > 250
- Die Abwesenheit eines der Pflichtfelder im Header



3) Felddarstellung

Feldtrennzeichen ist das Semikolon (";"). Nach dem letzten Feld einer Zeile folgt kein Semikolon sondern nur das Zeilenede laut 2).

Es gelten die üblichen CSV-Quote-Regeln. Feldwerte mit Semikolon oder " sind zu quoten. Das " wird als "" (2 mal ") übermittelt. Beispiel:
Datenwert
Darstellung als CSV-Feld
a
a
a;b
"a;b"
a"b
"a""b"
OrderRace1 kann das Zeichen " in Aufträgen nicht speichern und ignoriert es. OrderRace2 nimmt den gesamten Unicode-Zeichensatz an.

Feldtypen:
Typ
Formatierung im CSV-Feld
t
Text, ohne führende oder abschließende Blanks
anz
Anzahl, ohne führende Nullen. Erlaubte Zeichen nur 0..9. Keine Tausender-Punkte oder -Kommas



4) Feldliste

Die fetten Feldnamen sind Pflicht. Die Kleinschreibung in den Feldnamen ist signifikant. Die Feldreihenfolge ist frei.

4a) Sendungsbezogene Felder:

Feldname
Länge
Typ
Inhalt
orkidd
7
t
OrderRace-Kunden-DFÜ-id (Auftraggeber-Kennung). Muß innerhalb einer EasyUp-Datei gleich sein. OrderRace2: Feldinhalt ist ohne Funktion, bitte nur mit Ziffer 2 besetzen ("2").
abskids
0..15
t
Absender-Id (Kunden-Nr beim Spediteur/Id3). Der Absender muß unter dem Kunden bereits angelegt sein. Leere Spalte, falls Absender=Auftraggeber (also kein Absender)
fzkids
1..15
t
Frachtzahler-Id (Kunden-Nr beim Spediteur). Der Frachtzahler muß unter dem Kunden bereits mit eindeutiger Kunden-Nr angelegt sein.
agkids
1..15
t
Auftraggeber-Id3 (Kunden-Nr beim Spediteur). Der Auftraggeber muss unter dem Kunden bereits mit eindeutiger Kunden-Nr angelegt sein.
loadaids
1..15
t
Ladeadressen-Id (Kunden-Nr beim Spediteur). Der Ladeort muß unter dem Kunden bereits mit eindeutiger Kunden-Nr angelegt sein. (Nur in OrderRace2 moeglich)
sprod
1
t
Produkt, Serviceklasse: "v" = Versandlog, "b" = Belog, "u" = UPS, "t" = TOF
oref1
1..15
t
Auftragsnummer des Auftragsgebers - oft = Lieferscheinnr. Muß in OR eindeutig sein - sonst wird der Auftrag nicht eingebucht (= "A-Nr" in OrderRace)
eid1
0..10
t
Empfänger-Id1 (nur OrderRace2)
ename1
3..32
t
Empfängername1
ename2
0..32
t
2. Adr.Zeile (falls die Spalte ename2 nicht übergeben wird, darf der ename1 max. 64 Zeichen lang sein und wird in OrderRace auf EName1 und EName2 umgebrochen)
estreet1
3..32
t
Straße und Nr
ecc
0..2
t
Empfänger Ländercode nach ISO 3166-A2, Leerfeld = Land des Shipping-Agent. Siehe OrderRace Länderliste unter "ISO-Codes" (GB=Großbritannien, FR=Frankreich).
epc
0..9
t
Postleitzahl, linksbündig, (Länge wird gegen Ländertab geprüft, deutsche PLZ immer 5-stellig; ggf mit führender Null)
ecity1
3..30
t
Empfänger-Ort (Bitte nicht in Sperrschrift "K ö l n" - sonst Prüffehler)
eemail
0..30
t
Liefer-Avis email
eperson
0..32
t
Empfänger Person
efone
0..32
t
Empfänger Telefon
incoterm
0..4
t
Frankatur, OrderRace-Coding. Siehe "Verwaltung" -> "Frankaturen" -> "Code"
loadday
0 oder 8
t
Ladedatum. Nur mit OR2 moeglich. Format YYYYMMTT.
loadtime
0,4 oder 8
t
Ladezeit. Format HHMM oder HHMMhhmm ("hhmm" klein ist die bis-Zeit, falls der Service die Angabe erlaubt. )
loadlen
0..6
anz
Ladelaenge/Lademeter. Angabe in mm. Ein Lademeter wird hier als "1000" uebergeben.
dk1
0..2
t
Hinweisschluessel 1, OrderRace-Coding. Siehe "Verwaltung" -> "Hinweisschluessel" -> "Code"
dk1a
0..40
t
Argement zum Hinweisschluessel 1. Wenn dk1 ein "Tel-Avis" darstellt, wird hier die Rufnummer abgelegt.
Die Spaltenbnamen dk2, dk3, dk4, dk5 sowie dk2a, dk3a, dk4a, dk5a koennen fuer weitere Hinweisschluessel verwendet werden.
commentC
0..60
t
Sendungsbemerkung, die Maximallänge richtet sich nach Speditionsvorgaben. "C" laufend ab 1. Die maximale Anzahl Comment-Spalten richtet sich nach dem Shipping-Agent.
gival 0..9
anz
Good Insurance Value, Versicherungswert. Bei "100,00 Euro" bitte "10000" im Datensatz
gicurr
0..3 t
Währung des "gival" als ISO-Währungscode, Alpha (Euro = "EUR").
codval
0..9
anz
Collect on Delivery, Nachnahmewert. Bei "100,00 Euro" bitte "10000" im Datensatz
codcurr
0..3
t
Währung des "codval" als ISO-Währungscode, Alpha (Euro = "EUR").
codtype
0..3
t
Nachnahmeart. OrderRace-Coding
termcode
0..4
t
Terminart, OrderRace-Coding. Siehe "Verwaltung" -> "Terminarten" -> "Code"
termdata
0,6,8,12 oder 16
t
Terminzeit im Format JJJJMMTTHHMM oder JJJJMMTT oder JJMMTT oder JJJJMMTTHHMMhhmm ("hhmm" ist die Bis-Zeit - falls der Service die Angabe erlaubt)
volltr
0..6
anz
Sendunsgvolumen in Litern. 1 cbm = "1000" Liter im Datensatz
collid
0..
t
Nur nach Absprache: Colli-Ids. Falls NVE-Norm: 20-stellige NVE-Nummern durch jeweils ein Blank getrennt.
lhanz
0..2
anz
Anzahl zuaetzlicher Ladehilfen.
lhvp
0..2
t
Art der zuaetzlichen Ladehilfen (VP-Code)
spl
0..2
anz
Anzahl Stellplaetze
lomo
0..3
t
Logistikmodul
control
0..30
t
'i'+Leerzeichen+Benutzerlogin importiert Auftrag für Benutzer
'd' löscht Auftrag, wenn Auftrag mit A# genau 1x vorhanden ist.
'u' updatet Auftrag, wenn Auftrag mit A# genau 1x vorhanden ist.
yellownote
0..80
t
Gelber Zettel, Zusatzinformationen fuer Auftrag



4b1) Absender-Adr (xa)
Eine Absender-Adr wird nur importiert wenn, Absender-Adr im Service moeglich oder obligartorisch sind, beim Kunden nicht gesperrt ist, die Spalte "abskids" leer ist und die Spalte xaname1 vorhanden und nicht leer ist.
Feldname
Länge
Typ
Inhalt
xaname1
0..32
t
Name1 Absender-Adresse (wenn diese Spalte mit mindestens einem Zeichen belegt ist, wird ein Absender im Auftrag angelegt)
xaname2
0..32
t Name2 Absender
xaname3
0..32
t Name3 Absender. Wird nur uebernommen, wenn xaname2 auch gefuellt.
xastreet1 0..32
t
Strasse Absender
xacc
0..2
t
Absender Ländercode nach ISO 3166-A2, Leerfeld = Land des Shipping-Agent. Siehe OrderRace Länderliste unter "ISO-Codes" (GB=Großbritannien, FR=Frankreich)..
xapc
0..9
t
Absender, PLZ linksbündig, (Länge wird gegen Ländertab geprüft, deutsche PLZ immer 5-stellig; ggf mit führender Null)
xacity1
0..32
t
Absender, Ortsangabe
xaemail
0..30
t
Absender, email. Wird, falls gefuellt, in einer Lieferavis-email als "from" verwendet.



4b2) Hol-Adr (xh) . nur bei Beschaffungslogistik:
Eine Hol-Adr wird importiert wenn, Hol-Adr im Service obligartorisch sind, die Spalte xhname1 vorhanden und nicht leer ist.
Feldname
Länge
Typ
Inhalt
xhname1
0..32
t
Name1 Hol-Adresse (wenn diese Spalte mit mindestens einem Zeichen belegt ist, wird ein Holadresse angelegt)
xhname2
0..32
t Name2 Hol-Adr
xhstreet1 0..32
t
Strasse Hol-Adr
xhcc
0..2
t
Hol-Adr Ländercode nach ISO 3166-A2, Leerfeld = Land des Shipping-Agent. Siehe OrderRace Länderliste unter "ISO-Codes" (GB=Großbritannien, FR=Frankreich)..
xhpc
0..9
t
Hol-Adr, PLZ linksbündig, (Länge wird gegen Ländertab geprüft, deutsche PLZ immer 5-stellig; ggf mit führender Null)
xhcity1
0..32
t
Hol-Adr, Ortsangabe
xhfone
0..15
t
Hol-Adr, Telefonnr (nicht in jedem Service verfuegbar)
xhtmsg
0..
t
Hol-Adr, Abholtext/Instructionen (nicht in jedem Service verfuegbar. Maximale Laenge abhaengig vom Serviceprovider)

4b3) Frachtzahler-Adr (xf)
Eine Frachtzahler-Adr wird nur importiert wenn diese im Service moeglich oder obligartorisch sind, beim Kunden nicht gesperrt ist, die Spalte "fzkids" leer ist und die Spalte xfname1 vorhanden und nicht leer ist.
Feldname
Länge
Typ
Inhalt
xfname1
0..32
t
Name1 Frachtzahler (FZ) (wenn diese Spalte mit mindestens einem Zeichen belegt ist, wird ein FZ im Auftrag angelegt)
xfname2
0..32
t Name2 FZ
xfname3
0..32
t Name3 FZ. Wird nur uebernommen, wenn xfname2 auch gefuellt.
xfstreet1 0..32
t
Strasse FZ
xfcc
0..2
t
FZ Ländercode nach ISO 3166-A2, Leerfeld = Land des Shipping-Agent. Siehe OrderRace Länderliste unter "ISO-Codes" (GB=Großbritannien, FR=Frankreich)..
xfpc
0..9
t
FZ, PLZ linksbündig, (Länge wird gegen Ländertab geprüft, deutsche PLZ immer 5-stellig; ggf mit führender Null)
xfcity1
0..32
t
FZ, Ortsangabe



4c) Auf Sendungszeilen bezogene Felder:
Feldname
Länge
Typ
Inhalt
smarkN 1)
0..15
t
Marke in N. Sendungszeile (SZ)
sqN 1)
0..3
anz
Anzahl Packstücke in N. Sendungszeile. Die Maximalanzahl je Sendunsgzeile bestimmt der Shipping-Agent.
spcN 1)
0..2
t
VP-Code N. SZ
scontN 1)
0..40
t
Inhalt N. SZ Die Maximallänge der Inhaltsbeschreibung bestimmt der Shipping Agent. Eine Sendunsgzeile wird nur importiert, wenn ein Inhalt angegeben ist. Die erste Sendunsgzeile ist Pflicht.
sgN 1)
0..8
anz
Zeilengewicht in Gramm (1 kg = "1000" im Datensatz). Alternativ wird der Feldnamen "g" für das Sendungsgewicht verstanden. Bei mehreren Packstücken in der Sendunsgzeile ist das Gesamtgewicht anzugeben.
dimlenmmN 1)
0..5
anz
Laenge in Millimeter.
dimwidthmmN 1)
0..5
anz
Breite in Millimeter.
dimheightmmN 1)
0..5
anz
Hoehe in Millimeter.
ssubqN 1)
0..4
anz
Sub-Anzahl. Bei '5 KT auf 2 FP' hier eine '5'. In der Konfig muss die SubAnz freigegeben sein.
ssubvpN 1)
0..2
t
Sub-VP-Code. Im obigen Beispiel hier 'KT'
ggroupN 1)
0..2
t
Warengruppen in der N-ten Sendungszeile
literN 1)
0..9
anz
Liter


1) "N" steht in den Feldnamen für die n-te Sendungszeile. Die erste Sendungszeile ist 1. Das Feld "Inhalt" der ersten Sendungszeile hat den Namen "scont1". Bei mehreren Sendungszeilen sind die Zeilennummern bündig aufsteigend zu verwenden (ohne Auslassungen).


4d) Auf GG-Zeilen bezogene Felder: (GG-Import nur nach Absprache)
Feldname
Länge
Typ
Inhalt
ggGun
0..4
t
UN-Nr
ggGun2 0..7
t UN-Unter-Nr
ggGgz1 - ggGgz4
0..3
t
Gefahrzettelmuster-Nr (Hauptgefahr) 1 bis 4
ggGcc
0..4
t
Klassifizierungscode
ggGanz
1..4
anz
Anzahl Packstücke
ggGvp
0..5
t
GG-VP-Code (immer OrderRace-Coding)
ggGvpg
0..4
t
Verpackungsgruppe (leer, 'I', 'II' oder 'III').
ggGsv1
0..5
t
Sondervorschrift 1
ggGg
1..8
anz
Gewicht in Gramm
ggGltr
1..8
anz
Milliliter (1000=ein Liter)
ggGneg
0..6
anz
Nettoexplosivmasse in Gramm
ggGbc
0..1
t
Beförderungskategorie ("0" ,"1", "2", "3" oder "4") Mussfeld bei aktiven GG-Zeilen
ggGtext
0..70
t
Technische Name, Gefahrenauslöser (in lokaler Sprache oder Englisch)
ggGnag
0..70
t
N.A.G. Text (in lokaler Sprache oder Englisch)
ggGlq
0..1
t
Limited Quantity - Begrenzte Menge (1,Y,y,J oder j bedeuten LQ)
ggGug
0..1
t
Umweltgefaehrend. Ja wird durch 1,Y,y,J oder j dargestellt.
ggGtc
0..6
t
Tunnelcode

Das "G" in den GG-Feldnamen steht für die n-te GG-Zeile. Zu zählen ab 1 fortlaufend.



5) Beispieldateien

5a) 2 Aufträge des gleichen Absenders mit 20 und 150 kg

orkidd;abskids;sprod;oref1;ename1;estreet1;ecc;epc;ecity1;sg1;sq1;spc1;scont1
1234567;k33aa;v;auftrag47;Max AG;Leoweg 12;DE;19067;Retgendorf;20000;1;KT;Regenschirme
1234567;k33aa;v;auftrag48;Moin KG;Testallee 1;DE;42897;Remscheid;150000;2;FP;Regelware


5b) 2 Aufträge des gleichen Absenders mit max 2 Sendungszeilen
orkidd;abskids;sprod;oref1;ename1;estreet1;ecc;epc;ecity1;sq1;spc1;scont1;sg1;sq2;spc2;scont2;sg2
1234567;k33aa;v;auftrag47;Max AG;Leoweg 12;DE;19067;Retgendorf;1;KT;Bonbons;20000;;;;
1234567;k33aa;v;auftrag48;Moin KG;Testallee 1;DE;42897;Remscheid;1;KT;Bonbons;15000;2;FP;Regenschirme;123000



easyup2.html - end.