Pixi-API-Dokumentation

Inoffiziell · von koempf24.de

Postman-Collection
Orderlines Schreiben

pixiAddOrderLine

Legt eine neue Auftragsposition für einen Artikel in einem bestehenden Auftrag an, berechnet Preise und Rabatte und liefert die neue Positions-ID oder Validierungsfehler.

Legt eine Auftragsposition (Zeile in Orderlines) im Auftrag PixiOrderNr an.

1. Normalisierung

  • ItemKey = 0 gilt als NULL, ItemNrInt = '' gilt als NULL.
  • Ein leeres Date wird zum aktuellen Zeitpunkt.
  • Ein leerer Status wird zu NEW.
  • Ein NULL-Wert bei UsePaymentStatus wird zu 0, ein NULL-Wert bei LocationID wird zu 001.

2. Prüfungen Alle fehlgeschlagenen Prüfungen werden gesammelt, jede erzeugt eine Fehlerzeile:

  • UsePaymentStatus = 1 zusammen mit einem Status ungleich NEW wird abgelehnt.
  • Status muss einer der Werte NEW, ANG, HAL, FUT, STO, NLB sein.
  • Ist ItemNrInt angegeben, wird der Artikel über ItemNrInt gesucht. Der gefundene Schlüssel ersetzt ItemKey. Wird kein Artikel gefunden, entsteht ein Fehler.
  • Ist bis dahin kein Fehler aufgetreten, muss der Artikel einen Eintrag in pixi.ItemCode haben.
  • Ein Discount (Gutscheinbetrag) ungleich 0 erfordert eine VoucherID.
  • Enthält der Auftrag bereits eine Position mit Gutschein, wird eine abweichende VoucherID abgelehnt. Pro Auftrag ist nur ein Gutschein erlaubt.

Schlägt eine Prüfung fehl, werden die Fehlerzeilen zurückgegeben und es wird nichts geschrieben.

3. Status aus der Zahlungsart Bei UsePaymentStatus = 1 wird der Positionsstatus aus Payments.IniOrderStatus der Zahlungsart der Rechnungsadresse des Auftrags übernommen.

4. Dürfen Positionen ergänzt werden? pipiCanAddOrderlines prüft, ob der Auftrag noch neue Positionen annimmt:

  • Bei den Zahlungsarten K/C müssen alle vorhandenen Positionen in NEW, ANG, HAL, MIN, OPH, BES, STO oder NLB stehen.
  • Bei anderen Zahlungsarten darf keine Position in EIN oder AUS stehen.

Nur bei Ergebnis 1 wird die Position angelegt.

5. Kopfdaten

  • Kunde, Adressen, Auftragstyp, Währung und die bestehenden Kopfwerte werden aus dem Auftrag gelesen.
  • OrderNrExternal stammt aus dem Auftragskopf. Fehlt dort ein Wert, wird der Parameter verwendet. Fehlt auch dieser, wird eine Zeitstempel-Zeichenkette erzeugt.
  • Employee wird als <Employee> (API) gespeichert, ohne Angabe als API.

6. Währung Ist die Einstellung MultiCurrencyEnabled aus oder hat der Auftrag keinen Wechselkurs, wird die Datenbankwährung mit Kurs 1 verwendet. Andernfalls:

  • Die tagesaktuellen Kurse werden aus pixi.ExchRate gelesen.
  • Für die Datenbankwährung wird deren Kursquelle verwendet.
  • Für die Basiswährung des Wechselkurs-Eintrags des Auftrags dient die ExchRateSourceID des Shops als Quelle.

7. Preise

  • FullPrice (brutto) und das Netto-Gegenstück stammen aus dem Parameter, sofern er ungleich 0 ist.
  • Andernfalls wird der Artikelpreis verwendet: zuerst der Preis in Auftragswährung, dann der Basiswährungspreis × Kurs, dann der Datenbankwährungspreis × Kurs, sonst 0.
  • Bei B2B-Aufträgen gilt der Parameter FullPrice als Nettopreis, und der Bruttopreis wird immer aus den Artikelpreisen ermittelt.
  • ItemName überschreibt die Artikelbezeichnung.

8. Positionsrabatt

  • Ist FullPriceDiscountValue angegeben, wird dieser Wert verwendet.
  • Sonst wird DiscountPercent % vom Bruttopreis (B2C) bzw. vom Nettopreis (andere Auftragstypen) verwendet.
  • Sonst wird der volle Preis minus DiscountedPrice verwendet.
  • Sonst ist der Rabatt 0.

Derselbe Rabattwert wird vom Brutto- und vom Nettopreis abgezogen und ergibt Price und Price_Net.

9. Kopfwerte des Auftrags

  • ShipCost, Discount, AddressRemarks, Verfahren, Product und Extras werden aus den Parametern übernommen, wenn sie nicht leer bzw. ungleich 0 sind. Andernfalls bleiben die bestehenden Kopfwerte erhalten.
  • Ein bereits vorhandener Gutschein des Auftrags hat immer Vorrang vor VoucherID.

10. Anlage Die Position wird über Pixi_InsertOrderline mit diesen festen Werten angelegt:

  • Quelle I
  • Positionstyp ORD
  • 15 Wartetage
  • LocationID als Lager und als letztes Bestelllager

Anschließend wird eine Zeile mit CanAdd = 1 und der neuen OrderlineId zurückgegeben.

Hinweise

  • Kein Ergebnis, wenn keine Positionen ergänzt werden dürfen: Liefert pipiCanAddOrderlines 0 oder NULL, gibt der Aufruf überhaupt keine Zeilen zurück. Das ist der Fall, wenn der Auftrag nicht existiert oder eine Position bereits in einem sperrenden Status steht. Eine leere Antwort ist daher als „nicht angelegt“ zu werten.
  • Doppelte Fehlerzeile: Die Prüfung UsePaymentStatus = 1 mit Status ≠ NEW läuft zweimal, der Fehler erscheint daher doppelt im Ergebnis.
  • Status wird nicht erneut geprüft: Ein aus der Zahlungsart übernommener Status (UsePaymentStatus = 1) wird nicht gegen die erlaubte Liste geprüft.
  • Artikelpreis erforderlich: Der Artikel benötigt eine Preiszeile in der Datenbankwährung (Inner Join auf pixi.ItemPrice). Andernfalls werden Artikeldaten und Preise nicht gefüllt, und die Position kann ohne EAN oder Preis entstehen.
  • Auftragskopf wird überschrieben: Pixi_InsertOrderline aktualisiert die Kopffelder GiftMessage, ShipInstruct, Discount, Address_Remarks, Verfahren, Product, Extras, Shipdate und die Steuersätze.
    • GiftMessage hat den Standardwert '' und überschreibt damit eine vorhandene Geschenknachricht.
    • ShipInstruct wird auf '' und Shipdate auf NULL gesetzt.
  • Gutscheinanlage: Ist der resultierende Discount > 0 und existiert noch kein Voucher-Eintrag mit dieser ID, wird ein Gutschein mit Shop GRM und der Auftragswährung angelegt. Das Ablaufdatum wird mit DATEADD(y, 1, …) berechnet; der Datumsteil y steht für den Tag des Jahres, das Datum liegt also einen Tag nach dem Bestelldatum.
  • Protokollierung: Weicht OrderNrExternal vom Kopfwert ab, wird ein Eintrag in LogTable geschrieben.
  • Transaktion: Die Anlage erfolgt in einer Transaktion innerhalb von Pixi_InsertOrderline.
  • Positions-ID: Die neue ID wird aus einer temporären Tabelle gelesen, die ein INSTEAD OF-Trigger auf Orderlines füllt. Der Trigger liegt nicht vor. Wird keine ID geliefert, ist OrderlineId NULL, obwohl CanAdd = 1 ist.
  • Lesezugriffe: Alle Lesezugriffe verwenden NOLOCK.
  • Wechselkurse: Kurse werden nur für das aktuelle Datum gesucht. Fehlt ein Kurs für heute, werden umgerechnete Preise NULL.

Parameter

Parameter Typ Standardwert Beschreibung
PixiOrderNr
Pflicht
int –

Pixi-Auftragsnummer des bestehenden Auftrags.

Beispiel: 104532
ItemKey
int NULL

Interner Artikelschlüssel. 0 gilt als NULL. Wird durch den über ItemNrInt gefundenen Schlüssel ersetzt, falls dieser Parameter angegeben ist.

Beispiel: 5821
ItemNrInt
varchar(50)
string		 NULL

Shop-Artikelnummer zur Suche des Artikels. Eine leere Zeichenkette gilt als NULL.

Beispiel: ART-10045
Quantity
int 1

Menge der Auftragsposition.

Beispiel: 2
ShipCost
money
decimal		 0.0

Versandkosten der Position. Bei 0 werden die Versandkosten des Auftragskopfs verwendet.

Beispiel: 4.90
LocationID
varchar(3)
string		 001

Lager-ID der Position. NULL wird zu 001.

Beispiel: 001
GiftMessage
varchar(8000)
string		 –

Geschenknachricht. Wird in den Auftragskopf geschrieben und überschreibt den vorhandenen Wert, auch mit der leeren Zeichenkette als Standardwert.

Beispiel: Happy Birthday!
DiscountPercent
numeric(6, 2)
decimal		 NULL

Positionsrabatt in Prozent des vollen Preises (brutto bei B2C, sonst netto). Wird nur verwendet, wenn FullPriceDiscountValue NULL ist.

Beispiel: 10.00
VoucherID
varchar(50)
string		 NULL

Gutscheincode. Pflicht, wenn Discount ungleich 0 ist. Ein bereits im Auftrag vorhandener Gutschein hat Vorrang; ein abweichender Code wird abgelehnt.

Beispiel: SUMMER2024
Discount
money
decimal		 NULL

Gutscheinbetrag für den Auftragskopf. Bei NULL oder 0 bleibt der vorhandene Kopfwert erhalten. Ist der resultierende Wert > 0, wird ein Gutscheindatensatz angelegt, falls noch keiner existiert.

Beispiel: 5.00
AddressRemarks
varchar(255)
string		 NULL

Adressbemerkung für den Auftragskopf. Bei leerem Wert bleibt der vorhandene Wert erhalten.

Beispiel: Please ring twice
Verfahren
varchar(50)
string		 NULL

Wert für das Kopffeld Verfahren. Bei leerem Wert bleibt der vorhandene Wert erhalten.
Product
varchar(50)
string		 NULL

Wert für das Kopffeld Product. Bei leerem Wert bleibt der vorhandene Wert erhalten.
Extras
varchar(50)
string		 NULL

Wert für das Kopffeld Extras. Bei leerem Wert bleibt der vorhandene Wert erhalten.
Employee
varchar(50)
string		 NULL

Anlegender Mitarbeiter. Wird mit dem Zusatz (API) gespeichert; bei NULL wird API gespeichert.

Beispiel: jdoe
Date
datetime
dateTime		 NULL

Anlagedatum der Position (CreateDate/UpdateDate). Bei leerem Wert wird der aktuelle Zeitpunkt verwendet. OrderDate der Position ist immer der aktuelle Zeitpunkt.

Beispiel: 2024-05-14T10:30:00
Status
varchar(3)
string		 NULL

Status der neuen Position. Bei leerem Wert wird NEW verwendet.

Erlaubte Werte

  • NEW – Neu
  • ANG – Angebot
  • HAL – Angehalten
  • FUT – Direct-Fulfillment-Status
  • STO – Status STO
  • NLB – Status NLB

Beispiel: NEW
UsePaymentStatus
bit
boolean		 0

Bei 1 wird der Positionsstatus aus dem initialen Auftragsstatus der Zahlungsart des Auftrags übernommen. Nicht kombinierbar mit einem Status ungleich NEW.

Erlaubte Werte

  • 0 – `Status` verwenden
  • 1 – Initialstatus der Zahlungsart verwenden

Beispiel: 0
ItemNrExternal
varchar(50)
string		 N

Externe Artikelnummer, die in der Position gespeichert wird.

Beispiel: SHOP-4711
FullPrice
money
decimal		 NULL

Voller Bruttopreis vor Rabatt. Bei B2B-Aufträgen wird der Wert als Nettopreis verwendet. Bei NULL oder 0 wird der Artikelpreis verwendet.

Beispiel: 29.90
FullPriceDiscountValue
money
decimal		 NULL

Absoluter Rabatt je Einheit. Hat Vorrang vor DiscountPercent und DiscountedPrice.

Beispiel: 3.00
DiscountedPrice
money
decimal		 NULL

Preis nach Rabatt. Der Rabatt ergibt sich aus vollem Preis minus diesem Wert; wird nur verwendet, wenn kein anderer Rabattparameter angegeben ist.

Beispiel: 26.90
ItemName
varchar(120)
string		 NULL

Artikelbezeichnung der Position. Bei NULL wird die Bezeichnung aus dem Artikelstamm verwendet.

Beispiel: T-Shirt blue, size M
ItemSpecialNote
varchar(8000)
string		 NULL

Sonderhinweis zur Position (oItemSpecialNote).

Beispiel: Engraving: Anna
OrderNrExternal
varchar(50)
string		 NULL

Externe Auftragsnummer. Wird nur verwendet, wenn der Auftragskopf keine hat; sonst gilt der Kopfwert. Ohne beides wird eine Zeitstempel-Zeichenkette erzeugt.

Beispiel: WEB-2024-000123
DF_Type
varchar(1)
string		 NULL

Direct-Fulfillment-Typ, wird in DF_type der Position gespeichert.
SerialNumber
varchar(50)
string		 NULL

Seriennummer, wird in SerialNr der Position gespeichert.

Beispiel: SN-000981

Antwort

Result-Set 1 · Wenn mindestens eine Prüfung fehlschlägt (anstelle des Erfolgsergebnisses).

Eine Zeile je fehlgeschlagener Prüfung.

Spalte Typ Beschreibung
CanAdd bit
boolean

Immer 0.
OrderNr int

Angefragte Auftragsnummer.
ErrorMessage
Kann leer sein
 varchar(8000)
string

Fehlertext.
OrderlineId
Kann leer sein
 int

Immer NULL.
OrderNrExternal
Kann leer sein
 string

Immer NULL.

Result-Set 2 · Wenn alle Prüfungen bestehen und pipiCanAddOrderlines 1 liefert. Bei 0 oder NULL wird keine Ergebnismenge geliefert.

Eine Zeile mit der angelegten Auftragsposition.

Spalte Typ Beschreibung
CanAdd bit
boolean

Immer 1.
OrderNr int

Pixi-Auftragsnummer.
ErrorMessage
Kann leer sein
 varchar(8000)
string

Leere Zeichenkette.
OrderlineId
Kann leer sein
 int

Schlüssel (OrderlineKey) der neuen Auftragsposition; NULL, wenn die Anlage keine ID geliefert hat.
OrderNrExternal
Kann leer sein
 varchar(50)
string

In der neuen Position gespeicherte externe Auftragsnummer.

Beispielantwort

<SqlRowSet1>
  <row>
    <CanAdd>true</CanAdd>
    <OrderNr>104532</OrderNr>
    <ErrorMessage/>
    <OrderlineId>887321</OrderlineId>
    <OrderNrExternal>WEB-2024-000123</OrderNrExternal>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status Meldung Ursache
CanAdd = 0 Error: Use either @Status or @UsePaymentStatus parameter. `UsePaymentStatus` = 1 wurde mit einem `Status` ungleich `NEW` kombiniert. Nur einen der beiden angeben. Die Zeile erscheint doppelt.
CanAdd = 0 Error: Status {Status} is not allowed. `Status` ist keiner der Werte `NEW`, `ANG`, `HAL`, `FUT`, `STO`, `NLB`.
CanAdd = 0 Error: Item with shop item number ({ItemNrInt}) not found. Es existiert kein Artikel mit der angegebenen `ItemNrInt`.
CanAdd = 0 Error: No item found. Kein `ItemKey` angegeben, oder der Artikel hat keinen Eintrag in `pixi.ItemCode`.
CanAdd = 0 Error: Parameter @VoucherId not provided for the parameter @Discount (Voucher Amount):{Discount} `Discount` ist ungleich 0, aber `VoucherID` fehlt.
CanAdd = 0 Error: A voucher with VoucherId: ("{ExistingVoucherID}") is already present on the order. Only one voucher per order is allowed. Der Auftrag enthält bereits eine Position mit einem anderen Gutschein. Die vorhandene Gutschein-ID oder keine angeben.

Beispiele

POST https://apigateway.descartes.com/tms/pixi/
Content-Type: text/xml; charset=utf-8
Authorization: Basic BASE64(USERNAME:PASSWORD)

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiAddOrderLine>
      <PixiOrderNr>104532</PixiOrderNr>
      <!-- <ItemKey>5821</ItemKey> -->
      <!-- <ItemNrInt>ART-10045</ItemNrInt> -->
      <!-- <Quantity>2</Quantity> -->
      <!-- <ShipCost>4.90</ShipCost> -->
      <!-- <LocationID>001</LocationID> -->
      <!-- <GiftMessage>Happy Birthday!</GiftMessage> -->
      <!-- <DiscountPercent>10.00</DiscountPercent> -->
      <!-- <VoucherID>SUMMER2024</VoucherID> -->
      <!-- <Discount>5.00</Discount> -->
      <!-- <AddressRemarks>Please ring twice</AddressRemarks> -->
      <!-- <Verfahren>?</Verfahren> -->
      <!-- <Product>?</Product> -->
      <!-- <Extras>?</Extras> -->
      <!-- <Employee>jdoe</Employee> -->
      <!-- <Date>2024-05-14T10:30:00</Date> -->
      <!-- <Status>NEW</Status> -->
      <!-- <UsePaymentStatus>0</UsePaymentStatus> -->
      <!-- <ItemNrExternal>SHOP-4711</ItemNrExternal> -->
      <!-- <FullPrice>29.90</FullPrice> -->
      <!-- <FullPriceDiscountValue>3.00</FullPriceDiscountValue> -->
      <!-- <DiscountedPrice>26.90</DiscountedPrice> -->
      <!-- <ItemName>T-Shirt blue, size M</ItemName> -->
      <!-- <ItemSpecialNote>Engraving: Anna</ItemSpecialNote> -->
      <!-- <OrderNrExternal>WEB-2024-000123</OrderNrExternal> -->
      <!-- <DF_Type>?</DF_Type> -->
      <!-- <SerialNumber>SN-000981</SerialNumber> -->
    </ns1:pixiAddOrderLine>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
pixiCanAddOrderlines

Verwendete Tabellen

Orderlines · Schreiben OrderHeader · Schreiben Voucher · Schreiben LogTable · Schreiben Items · Lesen ItemCode · Lesen ItemPrice · Lesen OrderStates · Lesen Addresses · Lesen Payments · Lesen Customers · Lesen Shops · Lesen ExchRate · Lesen Currency · Lesen Settings · Lesen
SQL-Objekt:
dbo.pipiAddOrderLine
Prozedur zuletzt geändert am 2026-10-05
Dokumentation von claude-opus-5-5 am 2026-10-30 geschrieben