Skip to content

PlentyAddOrders - PlentyONE

Version: REST 1.0

← PlentyONE Add-On Übersicht

Mit diesem Step können Sie neue Aufträge in Plentymarkets anlegen und / oder Zahlungen(Payments) für vorhandene Bestellungen importieren.

Benötigte Plentymarkets REST API  Berechtigungen 

(es sind nicht immer alle notwendig):

  • Aufträge - Auftragsadressen - Auftragsadressen erstellen
  • Aufträge - Aufträge erstellen
  • Aufträge - Auftragseigenschaften - Eigenschaft erstellen
  • Aufträge - Referenzen für Auftragsrelationen - Referenz erstellen
  • Aufträge - Aufträge anzeigen
  • Aufträge - Aufträge aktualisieren
  • Kommentare - Kommentar erstellen

Step Konfiguration:

Input
Beschreibung
account

Ihr Plentymarkets-Account um auf die Schnittstelle zuzugreifen.

limit

Damit kann eingeschränkt werden wie viele Aufträge angelegt werden. Gerade während der Erstellung eines Flows ist es praktisch diesen Wert eher klein zu halten (z.B. 10), damit nur wenige Aufträge angelegt werden.

Default: 50

datastore

Geben Sie hier den Datastore an, in denen die jeweiligen Auftragskopfdaten abgespeichert sind. Es werden automatisch alle verknüpften Auftragspositionen gefunden und an den Kopf angehangen. Der Datastore mit den Auftragskopfdaten benötigt ein PlentyOrderPayload Schema (siehe Datastores - Schema) und der zugehörige Child-Datastore ein PlentyOrderItemsPayload. Die Bestellpositionen müssen über eine Master-Child Beziehung mit dem Auftrag verbunden sein.

folder

Geben Sie den Folder an, aus denen Sie die Aufträge aus dem Datastore abholen wollen.

Payment Options

Hier können sie auswählen ob die Zahlungsvorgang für Bestellungen angelegt und die Bestellung somit als vollständig bezahlt importiert wird. Folgende Optionen sind möglich:

  • Don't create payments - Bestellung wird ohne Zahlungsvorgang / unbezahlt angelegt (Default)
  • Auto-Create payments for all orders - Erzeugt eine vollständige Zahlung für alle importierten Bestellungen.
  • Create payment if paymentTransactionID is set - Beim Anlegen der Bestellung wird nur eine (vollständige) Zahlung angelegt, wenn die Spalte paymentTransactionID gefüllt ist. Als paymentTransactionID können Sie einen eindeutigen Wert (z.B. externe Bestellnummer oder timestamp) verwenden.
  • Only link paymentID to order - Diese Option kann gewählt werden, wenn Zahlungsvorgänge bereits in ihrem Plentymarkets System vorhanden sind. Importieren Sie die ID der Zahlung dazu in die paymentID Spalte in den Auftragkopfdaten.

Default: No

Vorbereitung:

Datastores mit Auftragskopf und Auftragspositionen anlegen

Damit der PlentyAddOrders Step funktioniert, müssen die Auftragsdaten bereits in 2 Datastores vorliegen:

  • Im Master Datastore sind dabei die Kopfdaten der Bestellung gespeichert.
  • Im Child Datastore sind die jeweiligen Artikelpositionen gespeichert und müssen per master_identifier dem jeweiligen Masterdatastore-Item (Bestellkopf) zugewiesen sein.

Schema:

Bestellung - Kopfdaten Bestellung - Auftragspositionen

Nachdem Sie die oberen Schritte ausgeführt haben, sehen Sie die beiden Datastores in der Datastore Ansicht so aus:

Dastores:

Aufträge in Datastores speichern

Benötigte Daten für Auftragskopf
Die Daten können sie manuell oder automatisch über einen Flow in den Datastore importieren. In der Regel wird es über einen Flow gemacht.
Einge Felder werden automatisch beim Import der Bestellung vom Step gefüllt und dürfen nicht gesetzt werden:
orderId, remoteStatusMessage, remoteStatusCode, remotePaymentStatus

Benötigte SpaltenErläuterung
KundendatencustomerId (und customerAddressId) oder billingCustomer… Spalten. Wenn keine customerId angegeben ist, wird automatisch ein neuer Kunde auf Grundlage der billingCustomer… Spalten angelegt. Die Spalten customerId und customerAddressId werden in diesem Fall automatisch bei Import befüllt.
LieferadressdatenDeliveryAddressId oder deliveryCustomer… Spalten. Wenn keine deliveryAddressId angeben ist, wird eine neue Lieferadresse auf Basis der deliveryCustomer… Spalten angelegt. In diesem Fall wird die deliveryAddressId automatisch vom Step befüllt.
plentyIDDie Plentymarkets ID des Webshops.

Benötigte Daten für Auftragsposition (Pflichtfelder)
Zur Positionsanlage sind die beiden in der Tabelle aufgeführten Spalten notwendig.
Ist kein Preis (Netto oder Brutto) angegeben wird dieser automatisch anhand der angegebenen Variante zugeordnet.

Benötigte Spalten
variantId
quantity
itemText

Spaltenbeschreibung:

Auftragskopf

Spaltenbezeichnung Erläuterung
ID Spalten (werden teilweise, je nach Use-Case automatisch befüllt )
orderID Von Plenty vergebene Aufrags ID
deliveryAddressID ID der Versandadresse
customerID Kunden ID
customerAddressID ID der Rechnungsadresse
paymentID ID des Zahlungsvorgangs

Status Spalten (werden automatisch befüllt)

remoteStatusMessage

Wird von Synesty mit der "Antwort" von Plenty befüllt

OrderID=XXX,OrderStatus=XXX

remoteStatusCode

Wird von Synesty bei Übertragung der Bestellung an Plenty gesetzt

SUCCESS = Erfolgreich übermittelt
ERROR = Fehler bei der Übertragung

remotePaymentStatus

Wird von Synesty bei Anlage einer Zahlung mit dem Status befüllt

Auftragseinstellungen

plentyID

ID des Mandanten / Webshops
ownerID
ID des Benutzers / Eigners der Bestellung
customerReference Zeichen Kunde
referrerID Auftragsherkunft ID
orderStatus Auftragsstatus
externalCustomerNumber Externe Kundennummer
externalOrderID Externe Auftragsnummer
warehouseID Lager ID
shippingProfileID Versandprofil ID (z.B. für Paket)
methodOfPaymentID Zahlungsmethode ID
orderType Auftragstyp
marking1ID Markierung 1 ID
shippingCosts Versandkosten
estimatedTimeOfShipment vorrausichtliches Versanddatum
referenceOrderID ID des referenzierten Auftrags, z.B. bei Retouren

Zahlungsvorgang

paymentTransactionID Zahlungstransaktion ID
paymentBookingText Verwendungszweck der Zahlung

Kunden- / Rechnungsadressdaten

billingCustomerFormOfAddress Anrede (Rechnungsadresse)
billingCustomerCompany Firma (Rechnungsadresse)
billingCustomerFirstName Vorname (Rechnungsadresse)
billingCustomerSurname Nachname (Rechnungsadresse)
billingCustomerAdditionalName Namenszusatz (Rechnungsadresse)
billingCustomerStreet Straße (Rechnungsadresse)
billingCustomerHouseNumber Hausnummer (Rechnungsadresse)
billingCustomerZip Postleitzahl (Rechnungsadresse)
billingCustomerCity Stadt (Rechnungsadresse)
billingCustomerCountryID Land ID (Rechnungsadresse), siehe auch https://developers.plentymarkets.com/en-gb/interface/stable7/Order.html#order_countries
billingCustomerEmail E-Mail Adresse (Rechnungsadresse)
billingCustomerTelephone Telefon (Rechnungsadresse)
billingCustomerFax Fax (Rechnungsadresse)
billingCustomerLanguage Sprache (Rechnungsadresse), siehe https://developers.plentymarkets.com/en-gb/interface/stable7/Order.html#order_currency
billingCustomerVatID Umsatzsteuer-Identifikationsnummer (Rechnungsadresse)
billingDebitorAccount Mandant (Kunde)
billingCustomerPlentyID Kundenklasse (Kunde)
billingCustomerPostNumber Postnummer (Rechnungsadresse)
billingCustomerContactPerson Ansprechpartner (Kunde)
billingCustomerClass Kundenklasse (Kunde)
billingCustomerPaymentDueWithin Zahlungsziel (Kunde)

Lieferadressdaten

deliveryCustomerCompany Firma (Lieferadresse)
deliveryCustomerFirstName Vorname (Lieferadresse)
deliveryCustomerSurname Nachname (Lieferadresse)
deliveryCustomerAdditionalName Namenszusatz (Lieferadresse)
deliveryCustomerStreet Straße (Lieferadresse)
deliveryCustomerHouseNumber Hausnummer (Lieferadresse)
deliveryCustomerZip Postleitzahl (Lieferadresse)
deliveryCustomerCity Stadt (Lieferadresse)
deliveryCustomerCountryID Land ID (Lieferadresse), siehe auch https://developers.plentymarkets.com/en-gb/interface/stable7/Order.html#order_countries
deliveryCustomerEmail E-Mail Adresse (Lieferadresse)
deliveryCustomerTelephone Telefon (Lieferadresse)
deliveryCustomerFax Fax (Lieferadresse)
deliveryCustomerVatID Umsatzsteuer-Identifikationsnummer (Lieferadresse)
deliveryCustomerPostNumber Postnummer (Lieferadresse)


Auftragsnotiz

infoUserID Benutzer ID der Auftragsnotiz
info Notiz am Auftrag

Auftragsposition

SpaltenbezeichnungErläuterung
variantIdID der Variante in ihrem Plentymarkets Shop
quantityBestellmenge
pricePreis Brutto
priceNetPreis Netto
VATProzentsatz MwSt
vatCountryIdID des Landes für diesen MwSt Satz (Einstellungen » Mandant (Shop) » Standard » Umsatzsteuersätze)
currencyWährung, siehe https://developers.plentymarkets.com/rest-doc/introduction#currencies
itemTextArtikelname
itemRebateArtikel Rabatt

Anwendungsbeispiel:

In der Regel ist bereits in einem vorherigen Prozess ein Master-Child Datastore mit Bestellungen (Kopf- und Positionsdaten) gelaufen - siehe Vorbereitung.

Der “PlentyAddOrders” Step greift nun auf diesen Master-Child Datastore zu und sendet alle Datensätze im PROCESSING_STATUS = UNPROCESSED an Plentymarkets.

Alle erfolgreich an Plentymarkets übermittelten Aufträge werden im Auftragskopf Datastore als “PROCESSED_SUCCESS” markiert. Desweiteren erhalten die Aufträge die von Plenty angelegte Auftragsnummer (OrderID) und werden mit mit einem StatusCode (SUCCESS bei Erfolg, ERROR bei fehlerhafter Übertragung) gekennzeichnet.

Ein erfolgreich übermittelter Auftrag, sieht im Auftragksopf Datastore in etwa so aus:

Hinweis: Falls bei der Übermittlung an Plenty ein Fehler auftritt, prüfen Sie ob alle benötigten Spalten (siehe oben) gefüllt sind.


Inputs

Das sind die Optionen, mit denen man den Step konfigurieren kann.

Name Datentyp Beschreibung Pflichtfeld Werte
account ACCOUNT Ihre PlentyONE Verbindung Ja
datastore DATASTORE Der Datastore, der die Aufträge für PlentyONE enthält. Der Datastore muss mit dem plentymarkets-Bestellschema (PlentyRESTOrderPayloadProvider) kompatibel sein. Ja
Folgende Felder sind zu konfigurieren:

Feld Datentyp Beschreibung Pflichtfeld Standardwert
name SINGLE Datastore entity name, for internal use only Nein
orderID SINGLE The OrderID created by PlentyONE after import of order (automatically filled) Nein
customerID SINGLE ID of Customer. Leave empty to create a new contact or fill with existing CustomerID/ContactID. Use -1 to create an order without an assigned customer (guest order). Nein
customerAddressID SINGLE ID of Invoice Address. Leave empty to create a new address or fill with existing AddressID. Nein
deliveryAddressID SINGLE ID of Shipping Address. Leave empty to create a new address or fill with existing AddressID. Nein
paymentID SINGLE ID of Payment. Leave empty to create a new payment or fill with existing PaymentID. Nein
remoteStatusMessage SINGLE Internal API status field, leave empty Nein
remoteStatusCode SINGLE Internal API status field, leave empty Nein
remotePaymentStatus SINGLE Internal API status field, leave empty Nein
plentyID SINGLE The plenty ID of the client that the order belongs to Nein
ownerID SINGLE The user ID of the order's owner Nein
customerReference SINGLE The customer sign of the order (order property ID = 8) Nein
referrerID SINGLE The referrer ID of the order. Nein
orderStatus SINGLE The ID of the order status. Nein
externalOrderID SINGLE The external order ID of the order (order property ID = 7) Nein
externalCustomerID SINGLE The external ID of the contact. Nein
customerNumber SINGLE The number of the contact. Nein
externalCustomerNumber SINGLE This field is deprecated will be removed in future. Please use billingExternalAddressId instead Nein
warehouseID SINGLE Warehouse ID of item. Nein
shippingProfileID SINGLE The ID of the orders shipping profile (order property ID = 2). Nein
methodOfPaymentID SINGLE The ID of the orders payment method (order property ID = 3). Nein
tagIds MULTIPLEVALUE List of order tag IDs. Nein
orderType SINGLE The ID of the order type. It is possible to define individual order types. Nein 1
marking1ID SINGLE The order flag / marking id (order property ID = 15) Nein
shippingCosts SINGLE The order gross shipping costs amount. Nein
estimatedTimeOfShipment SINGLE The estimated shipping date of this order (alias of order date type ID = 8). Nein
createdOnDate SINGLE The date that the order was created on (alias of order date type ID = 2). Nein
additionalOrderDates MAP Map of additional order dates to set(e.g. dateTypeId1=2023-11-03T21:42:46+01:00;dateTypeId2=2023-11-07T09:02:28+01:00;...). See https://developers.plentymarkets.com/en-gb/interface/stable7/Order.html#order_date_models for available date types. Nein
referenceOrderID SINGLE The ID of the parent order relation reference Nein
externalDeliveryNumber SINGLE The external delivery id of the order (order property ID = 49) Nein
additionalOrderProperties MAP Map of additional order order properties as map (typeId=value). See https://developers.plentymarkets.com/en-gb/interface/stable7/Order.html#order_models_orderproperty for all available type ids Nein
paymentTransactionID SINGLE Transaction Id of payment (payment property type = 1). Nein
paymentReferenceID SINGLE Reference Id of payment (payment property type = 2). Nein
paymentBookingText SINGLE Payment booking text (payment property type = 3). Nein
paymentNameOfSender SINGLE Payment name of sender (payment property type = 11). Nein
paymentCreateContactLink SINGLE If 'true', a link to the contact will be created for the payment (PaymentContactRelation). Nein
billingCustomerFormOfAddress SINGLE The form of address of the billing address. Nein
billingCustomerGender SINGLE The gender of the billing address. Nein
billingCustomerCompany SINGLE The billing address company name (name1 field). Nein
billingCustomerFirstName SINGLE The billing address first name (name2 field). Nein
billingCustomerSurname SINGLE The billing address last name (name3 field). Nein
billingCustomerAdditionalName SINGLE The billing address additional name (name4 field). Nein
billingCustomerStreet SINGLE The billing address street (address1 field). Nein
billingCustomerHouseNumber SINGLE The billing address house number (address2 field). Nein
billingCustomerAdditionalAddress SINGLE The billing address additional (address3 field). Nein
billingCustomerAddress4 SINGLE The billing address 4 field (currently undefined and can be freely used). Nein
billingCustomerZip SINGLE The billing address postcode. Nein
billingCustomerCity SINGLE The billing address town. Nein
billingCustomerCountryID SINGLE The billing address country id. Nein
billingCustomerEmail SINGLE The billing address email (option typeId = 5). Nein
billingCustomerExternalAddressID SINGLE The billing address external ID (option typeId = 2). Nein
billingCustomerExternalCustomerID SINGLE The billing address contact external ID (option typeId = 13). Nein
billingCustomerTelephone SINGLE The billing address phone number (option typeId = 4). Nein
billingCustomerLanguage SINGLE The billing address contact language. Nein
billingDebitorAccount SINGLE The book account (debitor account) of the contact. An additional, separate number that generally corresponds to the customer number or the debtor number in your financial accounting. Nein
billingCustomerPostNumber SINGLE The billing address postnumber (option typeId = 6). Nein
billingCustomerPlentyID SINGLE The client (store ID) that is assigned to the contact. Nein
billingCustomerContactPerson SINGLE The billing address contact person (option typeId = 12). Nein
billingCustomerClass SINGLE The ID of the contact class. Nein
billingCustomerVatID SINGLE The VAT ID of the contact. Nein
billingCustomerPaymentDueWithin SINGLE The VAT ID of the contact. Nein
billingCustomerValuta SINGLE The allowed number of days for the payment. Nein
billingCustomerDiscountDays SINGLE The allowed number of days for the discount. Nein
billingCustomerDiscountPercent SINGLE The early payment discount in percent. Nein
deliveryCustomerGender SINGLE The gender of the shipping address. Nein
deliveryCustomerCompany SINGLE The shipping address company name (name1 field). Nein
deliveryCustomerFirstName SINGLE The shipping address first name (name2 field). Nein
deliveryCustomerSurname SINGLE The shipping address last name (name3 field). Nein
deliveryCustomerAdditionalName SINGLE The shipping address additional name (name4 field). Nein
deliveryCustomerStreet SINGLE The shipping address street (address1 field). Nein
deliveryCustomerHouseNumber SINGLE The shipping address house number (address2 field). Nein
deliveryCustomerAdditionalAddress SINGLE The shipping address additional (address3 field). Nein
deliveryCustomerAddress4 SINGLE The shipping address 4 field (currently undefined and can be freely used). Nein
deliveryCustomerZip SINGLE The shipping address postcode. Nein
deliveryCustomerCity SINGLE The shipping address town. Nein
deliveryCustomerCountryID SINGLE The shipping address country id. Nein
deliveryCustomerEmail SINGLE The shipping address email (option typeId = 5). Nein
deliveryCustomerTelephone SINGLE The shipping address telephone number (option typeId = 4). Nein
deliveryCustomerVatID SINGLE The VAT ID of the delivery address (option typeId = 1) Nein
deliveryCustomerPostNumber SINGLE The shipping address postnumber (option typeId = 6). Nein
infoUserID SINGLE User id of order comment. Nein
info SINGLE The order comment text. Nein
variantId SINGLE The ID of variation Ja
quantity SINGLE The quantity Ja
price SINGLE The original gross price without any surcharges or discounts. Nein
priceNet SINGLE The original net price without any surcharges or discounts. Leave price field empty to use priceNet. Nein
VAT SINGLE The vat amount, e.g. 19.0 Nein
vatCountryId SINGLE The ID of the country vat Nein
currency SINGLE The currency of the amounts. Nein
itemText SINGLE The name of the order item. Ja
itemRebate SINGLE The discount can be a percentage or a fixed value. Nein
itemType SINGLE The ID of the order item type. Nein 1
isRebatePercentage SINGLE Flag that indicates if a discount is given as a percentage or as a fixed value. Nein true
itemReturnStatus SINGLE Return Status of order item. Nein
parentOrderItemId SINGLE The ID of the parent order item that is referred to Nein
externalItemId SINGLE The external item id. Nein
folder STRING Der Ordner des Datenspeichers. Nein
limit STRING Beschränkt die Anzahl der verarbeiteten Aufträge pro Ausführung. Nein
sortByField STRING Optionales Feld zum Sortieren der Datensätze nach einem der indizierten Datastore Felder. Nein
  • Keine (Standard)
  • Identifier
  • Identifier2
  • Identifier3
  • Tags
  • Erstellungsdatum
  • Aktualisierungsdatum
  • Datum der letzten Inhaltsänderung
  • Datum der Verarbeitung
  • Folder
sortDir STRING Die Sortierreihenfolge (Aufsteigend oder Absteigend). Nein
  • Aufsteigend
  • Absteigend
addIncomingPayment STRING Option für die Zahlungn der Bestellung setzen. 'Keine Zahlungen erstellen' - Bestellung wird ohne Zahlung angelegt (Standard) | 'Vollständige Zahlung für alle Bestellungen' : Es wird eine vollständige Zahlung für alle Aufträge erstellt. | 'Nur wenn Spalte 'paymentTransactionID' gesetzt ist' : Es wird eine vollständige Zahlung angelegt, wenn paymentTransactionID in der Datenzeile des Auftragskopfs gesetzt ist. | 'Nur Zahlungs-ID mit Auftrag verknüpfen' : Es wird nur eine Verknüpfung zwischen einer Zahlung und einem Auftrag erstellt. Sie müssen eine gültige paymentID in der Kopfzeile setzen. Nein
  • Keine Zahlungen erstellen
  • Vollständige Zahlung für alle Bestellungen.
  • Nur wenn Spalte 'paymentTransactionID' gesetzt ist
  • Nur Zahlungs-ID mit Bestellung verknüpfen
identifierOrderId STRING Setzen Sie diese Option, um PlentyONE Order ID in das Feld identifier2 oder identifier3 des Datensatzes zu schreiben. Nein
  • Deaktiviert
  • identifier2
  • identifier3
  • Tags
enableExternalOrderIDCheck BOOLEAN Wenn die Option aktiviert ist, wird die Bestellung anhand der externalOrderID gesucht. Wenn die Bestellung bereits in PlentyONE vorhanden ist, wird sie nicht erneut angelegt. Nein
  • Einschalten
  • Deaktiviert
errorProcessingStatus STRING Der ausgewählte 'Processing Status' wird für fehlgeschlagene Aufträge (Datensätze im Master-Datastore) gesetzt. Ändern Sie diesen Wert nur, wenn Sie wissen, was Sie tun. Standard: PROCESSED_ERROR Nein
  • PROCESSED_ERROR
  • UNPROCESSED
  • INPROCESS
  • PROCESSED_MARK_DELETE
  • PROCESSED_SUCCESS

Outputs

Das sind die Ergebnisse des Steps, die von nachfolgenden Steps, nach der Ausführung verwendet werden können.

Name Datentyp Beschreibung Werte
result SPREADSHEET Ein SPREADSHEET, dass die Ergebnisse des Auftragsimports enthält.
Folgende Felder sind im Output enthalten:

Feld Datentyp Beschreibung Standardwert
identifier SINGLE The identifier column to import Spreadsheet into a Datastore.
orderID SINGLE
customerID SINGLE
customerAddressID SINGLE
deliveryAddressID SINGLE
paymentID SINGLE
remoteStatusMessage SINGLE
remoteStatusCode SINGLE