Shipping Schreiben

pixiCreateInvoicePackage

Legt ein Paket (pixi.InvoicePackage) zu einer Rechnung an, optional mit Paketpositionen, Tracking-IDs und Label-URLs, und liefert die neue PackageId.

Legt ein neues Versandpaket zu einer bestehenden Rechnung an und ordnet optional Rechnungspositionen mit Mengen zu.

Ablauf:

Prüft die Einstellung Premium_API. Ist sie nicht aktiviert, wird eine Fehlerzeile geliefert.
Leere Zeichenketten in den Textparametern werden als NULL behandelt; ShipVendorCode wird getrimmt.
Die Rechnung wird über InvoiceNr und/oder InvoiceKey bestimmt. Mindestens einer der Werte ist erforderlich. Werden beide übergeben, müssen sie auf dieselbe Rechnung zeigen.
Der Versanddienstleister wird aus ShipVendorCode über ShipVendor.ShipVendorCode ermittelt. Ohne Code wird der ShipVendor der Rechnung verwendet. Ein explizit übergebener, unbekannter Code wird abgelehnt; kann der Rückfallwert nicht aufgelöst werden, bleibt ShipVendorId einfach NULL.
Ist Lines gesetzt, wird es als XML gelesen (/Lines/Line mit InvlineId und Quantity). Jede Position wird geprüft:
- InvlineId und Quantity müssen ganze Zahlen sein,
- keine doppelten InvlineId,
- jede Position muss zur Rechnung gehören (Invlines.InvoiceRef),
- Quantity muss größer als 0 sein,
- Quantity plus die bereits anderen Paketen zugeordnete Menge (pixi.InvoicePackageLines) darf Invlines.ItemQty nicht überschreiten.
In einer Transaktion wird das Paket in pixi.InvoicePackage eingefügt (TimesLabelPrinted = 0, Audit-Spalten mit dem Benutzer aus CreateEmp), die Positionen in pixi.InvoicePackageLines eingefügt und Invoices.Packages um 1 erhöht.
Ist TrackingID oder ReturnTrackingId gesetzt, wird pixiUpdateInvoicePackageTrackingIds für das neue Paket ausgeführt, um die Tracking-IDs in die Rechnung zu übernehmen (ShipmentTrackingID, retTrackID, retTrackIDhist), gesteuert durch Overwrite und ResetClientNotifiedFlag.
MQ-Events werden veröffentlicht: PackageLabelSaved (nur bei übergebener Label-URL) und InvoiceChanged mit Parameter CreatePackage.

Der Aufruf liefert immer genau eine Zeile mit Status, Message und PackageId.

Hinweise

Erfordert die Einstellung Premium_API = 1.
Die Prüfabfragen verwenden NOLOCK. Zwei gleichzeitige Aufrufe für dieselben Rechnungspositionen können daher beide die Mengenprüfung bestehen und eine Position überbuchen.
Die Prozedur startet eine eigene Transaktion bzw. setzt einen Savepoint, wenn der Aufrufer bereits eine Transaktion geöffnet hat. Die Erfolgszeile wird vor dem Commit ausgegeben.
Unerwartete SQL-Fehler werden abgefangen, die Transaktion (bzw. der Savepoint) wird zurückgerollt, der Fehler über log.InsertError protokolliert und als ERROR-Zeile mit dem SQL-Fehlertext geliefert.
Das Ergebnis von pixiUpdateInvoicePackageTrackingIds wird intern abgefangen und nicht ausgewertet. Meldet diese Prozedur ein Problem (z. B. Status 411, weil die zusammengesetzte Tracking-Zeichenkette der Rechnung 512 Zeichen überschreiten würde), wird das Paket trotzdem angelegt und SUCCESS geliefert, die Tracking-Felder der Rechnung werden aber ggf. nicht aktualisiert.
Ein Code-Kommentar besagt, dass der Tracking-Abgleich nach dem Commit läuft; tatsächlich läuft er innerhalb derselben Transaktion.
Enthält eine Tracking-ID mehrere durch ; getrennte Werte, erhält das Paket selbst nur den letzten Wert (durch den Tracking-Abgleich gesetzt), die Rechnung dagegen den vollständigen Wert.
ResetClientNotifiedFlag = 1 wirkt nur zusammen mit einer Tracking-ID: In OrderHistory wird für den jeweils letzten AUS-Status der Auftragspositionen der Rechnung ClientNotified = N gesetzt, sodass der Versand erneut exportiert wird.
CreateEmp wird in UCS_USERS gesucht; unbekannte Namen werden auf den Benutzer pixiAdministration abgebildet.
PackageDimensionId, GrossWeight und ExternalShipmentId werden ohne Prüfung gespeichert.
MQ-Events werden nur gesendet, wenn pixiMQ_Enabled aktiv ist und die Events in EventConfiguration konfiguriert sind; Fehler dort ändern das Ergebnis nicht.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`InvoiceNr`	varchar(20) string	NULL	Rechnungsnummer. Dieser Wert oder `InvoiceKey` ist erforderlich; werden beide übergeben, müssen sie übereinstimmen. Beispiel: `RE2024001234`
`InvoiceKey`	int	NULL	Interner Schlüssel der Rechnung (`Invoices.InvoiceKey`). Dieser Wert oder `InvoiceNr` ist erforderlich. Beispiel: `98765`
`TrackingID`	varchar(512) string	NULL	Sendungsverfolgungsnummer des Pakets. Wenn gesetzt, wird sie zusätzlich in `ShipmentTrackingID` der Rechnung übernommen. Beispiel: `00340434161094042557`
`ReturnTrackingId`	varchar(512) string	NULL	Retouren-Trackingnummer des Pakets. Wenn gesetzt, wird sie in `retTrackID` und `retTrackIDhist` der Rechnung übernommen. Beispiel: `00340434161094099999`
`ShippingLabelUrl`	varchar(8000) string	NULL	URL des Versandlabels. Wenn gesetzt, wird das MQ-Event `PackageLabelSaved` veröffentlicht. Beispiel: `https://labels.example.com/ship/4711.pdf`
`ReturnLabelUrl`	varchar(8000) string	NULL	URL des Retourenlabels. Wenn gesetzt, wird das MQ-Event `PackageLabelSaved` veröffentlicht. Beispiel: `https://labels.example.com/return/4711.pdf`
`ExternalShipmentId`	varchar(512) string	NULL	Sendungs-ID in einem externen Versandsystem; wird unverändert gespeichert. Beispiel: `SHP-2024-000815`
`GrossWeight`	decimal(9, 3) decimal	NULL	Bruttogewicht des Pakets; wird unverändert gespeichert. Beispiel: `2.350`
`ShipVendorCode`	varchar(3) string	NULL	Code des Versanddienstleisters (`ShipVendor.ShipVendorCode`). Ohne Angabe wird der Versanddienstleister der Rechnung verwendet. Ein unbekannter Code führt zu einem Fehler. Beispiel: `DHL`
`PackageDimensionId`	int	NULL	ID einer Paketabmessung; wird ohne Prüfung gespeichert. Beispiel: `3`
`Lines`	varchar(max) xml	NULL	Optionales XML mit den im Paket enthaltenen Rechnungspositionen und Mengen. Jede `Line` benötigt eine ganzzahlige `InvlineId` (`Invlines.InvLineKey` dieser Rechnung) und eine positive ganzzahlige `Quantity`. Beispiel: `<Lines> <Line> <InvlineId>554433</InvlineId> <Quantity>2</Quantity> </Line> <Line> <InvlineId>554434</InvlineId> <Quantity>1</Quantity> </Line> </Lines>`
`ResetClientNotifiedFlag`	bit boolean	0	Wird an den Tracking-Abgleich übergeben; wirkt nur, wenn eine Tracking-ID übergeben wird. Erlaubte Werte `0` – `OrderHistory.ClientNotified` nicht ändern. `1` – `ClientNotified` = `N` für den letzten `AUS`-Status der Auftragspositionen der Rechnung setzen, damit der Versand erneut exportiert wird. Beispiel: `0`
`Overwrite`	bit boolean	0	Wird an den Tracking-Abgleich übergeben; steuert, wie `TrackingID` in `ShipmentTrackingID` der Rechnung geschrieben wird. Erlaubte Werte `0` – Tracking-ID an die bestehende `ShipmentTrackingID` anhängen (getrennt durch `;`), sofern noch nicht enthalten. `1` – `ShipmentTrackingID` aus den Tracking-IDs der übrigen Pakete der Rechnung plus der neuen Tracking-ID neu aufbauen. Beispiel: `0`
`CreateEmp`	varchar(50) string	API	Benutzername für die Audit-Spalten; wird in `UCS_USERS` gesucht, unbekannte Namen werden auf `pixiAdministration` abgebildet. Beispiel: `API`

Antwort

Result-Set 1 · Immer; genau eine Zeile (Erfolg oder Fehler).

Statuszeile des Aufrufs mit der ID des angelegten Pakets bei Erfolg.

Spalte	Typ	Beschreibung
`Status`	varchar(7) string	`SUCCESS` oder `ERROR`.
`Message`	varchar string	Erfolgstext oder Fehlerbeschreibung.
`PackageId` Kann leer sein	int	`Id` der neuen Zeile in `pixi.InvoicePackage`; bei Fehler `NULL`.

Beispielantwort

<SqlRowSet1>
  <row>
    <Status>SUCCESS</Status>
    <Message>Package created successfully.</Message>
    <PackageId>4711</PackageId>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
ERROR	Setting "Premium_API" is not enabled.	Die Einstellung `Premium_API` ist nicht auf 1 gesetzt. Premium API in Pixi aktivieren.
ERROR	At least one of @InvoiceNr or @InvoiceKey must be provided.	Weder `InvoiceNr` noch `InvoiceKey` wurde übergeben (oder beide leer).
ERROR	Invoice not found for the given @InvoiceNr.	Zur übergebenen `InvoiceNr` existiert keine Rechnung.
ERROR	@InvoiceNr and @InvoiceKey do not match.	Beide Kennungen wurden übergeben, verweisen aber auf unterschiedliche Rechnungen.
ERROR	Invoice not found.	Zum übergebenen `InvoiceKey` existiert keine Rechnung.
ERROR	ShipVendorCode '{ShipVendorCode}' is not a valid shipping vendor.	Der übergebene `ShipVendorCode` existiert nicht in `ShipVendor`. Gültigen Code verwenden oder Parameter weglassen.
ERROR	Cannot parse XML	`Lines` ist kein wohlgeformtes XML.
ERROR	XML contains invalid or missing InvlineId/Quantity values.	Einem `Line`-Element fehlt `InvlineId` oder `Quantity`, oder ein Wert ist keine ganze Zahl.
ERROR	XML contains duplicate InvlineId entries.	Dieselbe `InvlineId` kommt mehrfach in `Lines` vor.
ERROR	InvlineId(s) {list} do not belong to the given invoice.	Die aufgeführten Rechnungspositions-IDs existieren nicht oder gehören zu einer anderen Rechnung.
ERROR	Quantity for InvlineId(s) {list} must be greater than 0.	Für die aufgeführten Positionen wurde eine `Quantity` von 0 oder kleiner übergeben.
ERROR	Quantity for InvlineId(s) {list} exceeds the available quantity on the invoice line.	Angeforderte Menge plus bereits anderen Paketen zugeordnete Menge überschreitet `Invlines.ItemQty`.
ERROR	{SQL error message}	Beim Schreiben ist ein unerwarteter SQL-Fehler aufgetreten; die Transaktion wird zurückgerollt und der Fehler protokolliert.

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:pixiCreateInvoicePackage>
      <!-- <InvoiceNr>RE2024001234</InvoiceNr> -->
      <!-- <InvoiceKey>98765</InvoiceKey> -->
      <!-- <TrackingID>00340434161094042557</TrackingID> -->
      <!-- <ReturnTrackingId>00340434161094099999</ReturnTrackingId> -->
      <!-- <ShippingLabelUrl>https://labels.example.com/ship/4711.pdf</ShippingLabelUrl> -->
      <!-- <ReturnLabelUrl>https://labels.example.com/return/4711.pdf</ReturnLabelUrl> -->
      <!-- <ExternalShipmentId>SHP-2024-000815</ExternalShipmentId> -->
      <!-- <GrossWeight>2.350</GrossWeight> -->
      <!-- <ShipVendorCode>DHL</ShipVendorCode> -->
      <!-- <PackageDimensionId>3</PackageDimensionId> -->
      <!-- <Lines><![CDATA[<Lines><Line><InvlineId>554433</InvlineId><Quantity>2</Quantity></Line><Line><InvlineId>554434</InvlineId><Quantity>1</Quantity></Line></Lines>]]></Lines> -->
      <!-- <ResetClientNotifiedFlag>0</ResetClientNotifiedFlag> -->
      <!-- <Overwrite>0</Overwrite> -->
      <!-- <CreateEmp>API</CreateEmp> -->
    </ns1:pixiCreateInvoicePackage>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

curl -X POST 'https://apigateway.descartes.com/tms/pixi/' \
  --user 'USERNAME:PASSWORD' \
  --header 'Content-Type: text/xml; charset=utf-8' \
  --data-binary @- <<'XML'
<?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:pixiCreateInvoicePackage>
      <!-- <InvoiceNr>RE2024001234</InvoiceNr> -->
      <!-- <InvoiceKey>98765</InvoiceKey> -->
      <!-- <TrackingID>00340434161094042557</TrackingID> -->
      <!-- <ReturnTrackingId>00340434161094099999</ReturnTrackingId> -->
      <!-- <ShippingLabelUrl>https://labels.example.com/ship/4711.pdf</ShippingLabelUrl> -->
      <!-- <ReturnLabelUrl>https://labels.example.com/return/4711.pdf</ReturnLabelUrl> -->
      <!-- <ExternalShipmentId>SHP-2024-000815</ExternalShipmentId> -->
      <!-- <GrossWeight>2.350</GrossWeight> -->
      <!-- <ShipVendorCode>DHL</ShipVendorCode> -->
      <!-- <PackageDimensionId>3</PackageDimensionId> -->
      <!-- <Lines><![CDATA[<Lines><Line><InvlineId>554433</InvlineId><Quantity>2</Quantity></Line><Line><InvlineId>554434</InvlineId><Quantity>1</Quantity></Line></Lines>]]></Lines> -->
      <!-- <ResetClientNotifiedFlag>0</ResetClientNotifiedFlag> -->
      <!-- <Overwrite>0</Overwrite> -->
      <!-- <CreateEmp>API</CreateEmp> -->
    </ns1:pixiCreateInvoicePackage>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML

<?php

$soapClient = new SoapClient(null, [
    'login' => 'USERNAME',
    'password' => 'PASSWORD',
    'location' => 'https://apigateway.descartes.com/tms/pixi/',
    'uri' => 'https://apigateway.descartes.com/tms/pixi/',
]);

$arguments = [
    // 'InvoiceNr' => 'RE2024001234',
    // 'InvoiceKey' => '98765',
    // 'TrackingID' => '00340434161094042557',
    // 'ReturnTrackingId' => '00340434161094099999',
    // 'ShippingLabelUrl' => 'https://labels.example.com/ship/4711.pdf',
    // 'ReturnLabelUrl' => 'https://labels.example.com/return/4711.pdf',
    // 'ExternalShipmentId' => 'SHP-2024-000815',
    // 'GrossWeight' => '2.350',
    // 'ShipVendorCode' => 'DHL',
    // 'PackageDimensionId' => '3',
    // 'Lines' => '<Lines><Line><InvlineId>554433</InvlineId><Quantity>2</Quantity></Line><Line><InvlineId>554434</InvlineId><Quantity>1</Quantity></Line></Lines>',
    // 'ResetClientNotifiedFlag' => '0',
    // 'Overwrite' => '0',
    // 'CreateEmp' => 'API',
];

$soapArguments = [];
foreach ($arguments as $name => $value) {
    $soapArguments[] = new SoapVar($value, XSD_STRING, '', '', $name);
}

$response = $soapClient->__soapCall('pixiCreateInvoicePackage', $soapArguments);

pixiUpdateInvoicePackageTrackingIds

Verwendete Tabellen

Settings · Lesen Invoices · Schreiben ShipVendor · Lesen Invlines · Lesen InvoicePackage · Schreiben InvoicePackageLines · Schreiben UCS_USERS · Lesen OrderHistory · Schreiben

SQL-Objekt:: dbo.pipiCreateInvoicePackage