WebService Calls > Options for Growth

Beschreibung

Hinzufügen und Aktualisieren von Auftragsdokumenten. An Aufträge können verschiedene Dokumententypen angehängt sein. Typische Verwendung wäre das Übertragen einer Rechnung an die Software, damit diese an den Marktplatz übergeben werden kann.

Beispiel Request

Code

Feldliste Request

Name	Beschreibung	Anz.	Typ	sonstiges
request	Root-Element der Anfrage	1	Element
method	Attribut von request. Name der Webservice-Methode.	1	string	Fester Wert: „updateOrderDocuments“
version	Attribut von request. Legt die Version der Anfrage fest.	1	integer	Fester Wert: „1.0.0“ \| „1.1.0“
order	Wrapper-Element, das die Daten eines Auftrags zusammenfasst	0..N	Element
significant_key	Gibt an welches Feld zur Identifikation des Dokuments beim Update genutzt wird.	1	string	Feste Werte: "order_id", "order_number", "order_number_and_prefix", "external_order_number_1", "external_order_number_2", "marketplace_order_id_1", "marketplace_order_id_2", "transaction_id_1", "transaction_id_2"
reference_id	Optionales Attribut des Elements request. In diesem Feld kann eine beliebige ID angegeben werden die in den zugehörigen Response durchgereicht wird.	0..1	string
mandator_id	Mandanten-ID	1	integer
order_id	Auftrags-ID	0..1	integer
order_number	Auftragsnummer	0..1	integer
order_number_prefix	Auftragsnummernpräfix	0..1	string
external_order_number_1	Externe Auftragsnummer 1	0..1	string
external_order_number_2	Externe Auftragsnummer 2	0..1	string
transaction_id_1	Transaktionsnummer 1 zur Identifikation der Zahlung falls vorhanden.	0..1	string
transaction_id_2	Transaktionsnummer 2 zur Identifikation der Zahlung falls vorhanden.	0..1	string
marketplace_order_id_1	Marktplatzauftragsnummer 1	0..1	string
marketplace_order_id_2	Marktplatzauftragsnummer 2	0..1	string
invoice_number	Rechnungsnummer	0..1	integer
documents	Wrapper-Element, das die Dokumente eines Auftrags zusammenfasst.	0..1	Element
document	Wrapper-Element, das die Informationen für ein Dokument enthält.	1..N	Element
external_document_number	Externe Dokumentennummer (z. B. Rechnungsnummer).	0..1	string
local_doc_path	UNC-Pfad zum externen Dokument.	0..1	string
base64_doc	Das Dokument im Base64-Format.	0..1	string
document_type	Dokumententyp	1	string	Mögliche Werte.
document_name	Bezeichnung des Dokuments.	0..1	string	Hinweis
packet_id	ID des Paketes, dem das Dokument zugehörig ist.	0..1	integer	Hinweis

Beispiel Response

Code

Feldliste Response

Name	Beschreibung	Anz.	Typ	sonstiges
response	Root-Element der Antwort	1	Element
method	Attribut von response. Name der Webservice-Methode.	1	string	Fester Wert: „updateOrderDocuments“
version	Attribut von response. Legt die Version der Anfrage fest.	1	integer	Fester Wert: „1.1.0“
report	Information über die ausgeführte Operation. Für jedes OrderDocument-Element aus dem Request wird ein Report zurückgegeben.	0..N	Element
action	Attribut von report. Gibt an welche Operation mit dem Datensatz durchgeführt wurde.	1	string	Feste Werte: insert \| update
return_code	Attribut von report. Gibt an ob in der durchgeführten Operation Fehler aufgetreten sind.	1	integer	0 = OK. < 0 = Fehler Siehe Tabelle für Codes ab Version 1.1.0
reference_id	Optionales Attribut von report. Enthält die reference_id des zugehörigen Requests, falls diese angegeben wurde.	0..1	string	Hinweis
error_description	Falls bei der Durchführung der Operation Fehler aufgetreten sind wird in error_description eine Fehlerbeschreibung zurück geliefert	0..1	string
order	Wrapper-Element, das die Daten des Auftrags zusammenfasst	1	Element
mandator_id	Mandanten ID	1	integer
order_id	Auftrags-ID	1	integer
documents	Wrapper-Element, das die Dokumente eines Auftrags zusammenfasst.	1	Element
document	Wrapper-Element, das die Informationen für ein Dokument enthält.	1	Element
external_document_number	Externe Dokumentennummer (z. B. Rechnungsnummer).	0..1	string
local_doc_path	UNC-Pfad zum Dokumentenspeicherort. Der Dateiname weicht vom extern übergebenen Dateinamen ab, da die Software intern die Dokumente eigenständig verwaltet, abspeichert und benennt.	1	string
document_type	Dokumententyp	1	string	Mögliche Werte.
document_name	Originaler Dateiname des Dokuments inkl. Dateityp.	0..1	string
packet_id	ID des Paketes, dem das Dokument zugehörig ist.	0..1	integer	Hinweis
message	Optionale Statusmeldung. Wird Ausgegeben wenn z. B. kein Dokument übergeben wurde oder das Dokument nicht über den angegebenen Pfad aufrufbar ist.	0..1	string

Wertetabelle(n)

Aufgeführte Werte gelten für das Feld document_type.

Wert	Belegtyp
offer	Angebot
order	Auftrag
invoice	Rechnung
delivery note	Lieferschein
return ticket	Rücksendeschein
cancellation invoice	Stornorechnung
shipping label	Versandlabel
parcel label 1	Paketschein 1
parcel label 2	Paketschein 2
sepa debit agreement	SEPA Lastschriftmandat (Kann nicht durch die Software generiert werden. Kann als Typ verwendet werden um bestehende Dokumente am Auftrag zu hinterlegen.)

Hinweise

•Die Dateinamen der Dokumente müssen eindeutig sein.

•Die reference_id wird nicht in Speed4Trade CONNECT gespeichert und ist damit auch nicht fest an das betroffene Dokument gebunden. Die selbe ID kann daher in unterschiedlichen Calls problemlos wiederverwendet werden. Sie dient lediglich zur schnellen Zuordnung eines Reports zu einem Request. Dies ist insbesondere dann nützlich wenn es bei der Verarbeitung eines oder mehrerer der übergebenen Datensätze zu Fehlern kommt. So kann dennoch die Fehlermeldung zu einem Request zugeordnet werden.

•Dokumente sind entweder per base64_doc oder local_doc_path zu übergeben. Bei Übergabe im Base64-Format muss zwingend eine Dokumentenbezeichnung via document_name übergeben werden. Bei lokalen Dokumenten, hat document_name keine Funktion.

•Es muss getrennt werden, ob die Rechnungsgenerierung durch die Software erfolgt oder ob Rechnungsdokumente von extern eingelesen werden. Bei der Übergabe von Rechnungen die extern erstellt wurden, ist die Rechnungsgenerierung in der Software zu deaktivieren.

•Über updateOrderDocuments können Dokumente hinzugefügt und auch ersetzt werden. Die Definition ob ein Dokument ersetzt oder neue hinzugefügt wird, hängt am Dokumentennamen. Damit ein neues Dokument gespeichert wird, muss der Dokumentenname mind. für den Verkaufsaccount eindeutig sein. Zum Ersetzen eines Dokuments, muss ein neues Dokument mit dem selben Dateinamen und der bisherigen externen Dokumentennummer übergeben werden. Nur wenn beide Werte passen wird das Dokument ersetzt.

•Das Löschen von Dokumenten ist nicht vorgesehen.

•Bei Verwendung des significant_keys "order_number_and_prefix" müssen dann sowohl order_number als auch order_number_prefix übergeben werden.

•Die Zuordnung eines Dokuments zu eine Paket hat bisher keine funktionale Auswirkung. Das Mapping kann angelegt und über fetchOrderDocuments abgefragt werden.

•Der updateOrderDocuments-Request aktualisiert das letzte Änderungsdatum am zugehörigen Auftrag.

Liste der möglichen return_code bei Version: 1.1.0

return_code	Bedeutung
0	Vorgang erfolgreich
-2	Unerwarteter Fehler
-6	Auftrag konnte nicht geladen werden (z.B. Auftrags-ID übergeben die nicht existiert)
-10	Mandant oder Account konnte nicht geladen werden
-10001	Dokument ist am Auftrag schon vorhanden (Duplikat)
-10002	Die angegebene Datei konnte nicht gefunden werden
-10003	Bei der angegebenen Datei handelt es sich um ein Verzeichnis
-10004	Kein document_name angegeben (Nur relevant bei base64)
-10005	Es wurde kein valider document_type angegeben
-10006	Die übergebene packet_id ist nicht valide
-10007	Der übergebene String im base64_doc ist kein valides base64

Änderungsübersicht

Version	Änderungsbeschreibung
4.10.7	Einführung des updateOrderDocuments-Calls.
4.11.6	Erweiterung der Dokumenttypen um "parcel label 1/2".
4.11.7	Erweiterung der Dokumenttypen um "sepa debit agreement".
4.11.26	Dokumente können per packet_id einem Paket zugeordnet werden.
4.12.8	Erweiterung des Request um invoice_number.
4.13.6	Änderungen an den Auftragsdokumenten sorgen nun immer für eine Aktualisierung des letzten Änderungsdatums an Aufträgen.
4.13.26	Erweiterte Liste an return_codes bei Fehlern (Version 1.1.0)