updateOrderDocuments

Navigation:  WebService Calls > Options for Growth >

updateOrderDocuments

Previous pageReturn to chapter overviewNext page

Texte ein-/ausblenden

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)