Returns Schreiben

pixiAddReturnCaseLine

Fügt einem bestehenden Retourenfall eine Zeile für eine Rechnungsposition hinzu oder legt einen neuen leeren Retourenfall an, wenn keine Retourenfall-ID übergeben wird.

Das Verhalten hängt von RET_ID ab.

RET_ID ist NULL oder 0

pixiCreateReturnCase wird mit ReturnDate, ReceiversComment und Employee ausgeführt. Dabei wird ein neuer Retourenfall-Kopf in RET_CASES mit Status NEW angelegt, und dessen RET_ID und RET_NUMBER werden zurückgegeben.
Es wird in diesem Fall keine Retourenzeile angelegt. Die neue ID wird intern nicht übernommen. Für die Zeile muss der Aufruf mit der zurückgegebenen RET_ID wiederholt werden.

RET_ID ist gesetzt (nicht 0)

Eine Zeile wird nur dann in RET_CASE_LINES eingefügt, wenn alle folgenden Bedingungen erfüllt sind:

die Rechnungsposition InvLineKey existiert und hat ItemQty > 0;
ItemQty >= QuantityToReturn;
die zugehörige Auftragsposition hat den Status AUS;
es gibt keine Gutschrift, die sich auf dieselbe Rechnung bezieht (RefToInvoiceKey) und eine Position zur selben Auftragsposition enthält.

Die neue Zeile erhält folgende Werte:

Status AOK bei ItemOk = 1, sonst DAM;
Kundenkommentar, Empfängerkommentar und Retourengrund, wobei NULL als Leerstring gespeichert wird;
die Menge QuantityToReturn und den Verweis auf die Rechnungsposition;
Anlagedatum GETDATE() und Anlage-Mitarbeiter <Employee> (API) bzw. API, wenn kein Mitarbeiter angegeben ist.

Anschließend wird immer eine Zeile mit der Retourenfall-ID und der ID der neuen Zeile geliefert. Wurde wegen einer nicht erfüllten Bedingung keine Zeile eingefügt, ist RET_LINE_ID NULL.

Hinweise

Stolperfalle: Ohne RET_ID wird nur ein leerer Retourenfall angelegt. InvLineKey, QuantityToReturn, ItemOk, ReturnReason und CustomersComment werden dann ignoriert. Die zurückgegebene RET_ID muss in einem zweiten Aufruf verwendet werden.
Bei nicht erfüllten Bedingungen wird kein Fehler gemeldet. Ob keine Zeile eingefügt wurde, lässt sich daran erkennen, dass RET_LINE_ID NULL ist.
Es wird nicht geprüft, ob die Rechnungsposition bereits in einer anderen Retourenzeile enthalten ist. Wiederholte Aufrufe können mehrere Retourenzeilen zur selben Rechnungsposition anlegen, solange die jeweilige Menge ItemQty nicht übersteigt.
Es wird nicht geprüft, ob die angegebene RET_ID existiert, und negative Mengen werden nicht abgewiesen.
ReturnDate wird nur beim Anlegen eines neuen Retourenfalls verwendet.
ReceiversComment wird beim Anlegen eines Retourenfalls im Kopf gespeichert und beim Hinzufügen einer Zeile in der Zeile.
Ist ItemOk NULL, erhält die Zeile den Status DAM.
Rechnungs- und Auftragspositionen werden mit NOLOCK gelesen.
Es wird keine explizite Transaktion verwendet.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`InvLineKey` Pflicht	int	–	Schlüssel der Rechnungsposition (`Invlines.InvLineKey`), die retourniert wird. Beispiel: `123456`
`QuantityToReturn` Pflicht	int	–	Retournierte Menge. Sie darf die berechnete Menge `ItemQty` nicht übersteigen. Beispiel: `1`
`ItemOk`	bit boolean	1	Zustand des retournierten Artikels. Bestimmt den Status der Zeile. Erlaubte Werte `1` – Artikel in Ordnung, Zeilenstatus `AOK`. `0` – Artikel beschädigt, Zeilenstatus `DAM`. Beispiel: `1`
`RET_ID`	int	NULL	ID des bestehenden Retourenfalls, dem die Zeile hinzugefügt wird. Bei `NULL` oder `0` wird stattdessen ein neuer leerer Retourenfall angelegt, ohne Zeile. Beispiel: `4711`
`ReturnReason`	varchar(2048) string	–	Retourengrund, der in der Zeile gespeichert wird. Beispiel: `Wrong size`
`CustomersComment`	varchar(2048) string	–	Kommentar des Kunden, wird in der Zeile gespeichert. Beispiel: `Too small`
`ReceiversComment`	varchar(2048) string	–	Kommentar des annehmenden Mitarbeiters. Wird im neuen Retourenfall-Kopf bzw. beim Hinzufügen einer Zeile in der Zeile gespeichert. Beispiel: `Packaging opened`
`Employee`	varchar(50) string	NULL	Mitarbeiterkürzel. Wird als `<Employee> (API)` gespeichert bzw. als `API`, wenn leer. Beispiel: `JD`
`ReturnDate`	datetime dateTime	NULL	Retourendatum eines neu angelegten Retourenfalls, Standard ist das aktuelle Datum. Wird ignoriert, wenn `RET_ID` angegeben ist. Beispiel: `2024-05-14T10:30:00`

Antwort

Result-Set 1 · Wenn `RET_ID` `NULL` oder `0` ist (geliefert von `pipiCreateReturnCase`)

Der neu angelegte Retourenfall.

Spalte	Typ	Beschreibung
`RET_ID`	int	ID des neuen Retourenfalls.
`RET_NUMBER` Kann leer sein	string	Nummer des neuen Retourenfalls.

Result-Set 2 · Wenn `RET_ID` angegeben und nicht `0` ist

Ergebnis des Hinzufügens der Zeile.

Spalte	Typ	Beschreibung
`UPDATED_RETURN_ID`	int	ID des Retourenfalls (die übergebene `RET_ID`).
`RET_LINE_ID` Kann leer sein	numeric(38,0) decimal	ID der neuen Retourenzeile. `NULL`, wenn keine Zeile eingefügt wurde.

Beispielantwort

<SqlRowSet1>
  <row>
    <UPDATED_RETURN_ID>4711</UPDATED_RETURN_ID>
    <RET_LINE_ID>98231</RET_LINE_ID>
  </row>
</SqlRowSet1>

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:pixiAddReturnCaseLine>
      <InvLineKey>123456</InvLineKey>
      <QuantityToReturn>1</QuantityToReturn>
      <!-- <ItemOk>1</ItemOk> -->
      <!-- <RET_ID>4711</RET_ID> -->
      <!-- <ReturnReason>Wrong size</ReturnReason> -->
      <!-- <CustomersComment>Too small</CustomersComment> -->
      <!-- <ReceiversComment>Packaging opened</ReceiversComment> -->
      <!-- <Employee>JD</Employee> -->
      <!-- <ReturnDate>2024-05-14T10:30:00</ReturnDate> -->
    </ns1:pixiAddReturnCaseLine>
  </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:pixiAddReturnCaseLine>
      <InvLineKey>123456</InvLineKey>
      <QuantityToReturn>1</QuantityToReturn>
      <!-- <ItemOk>1</ItemOk> -->
      <!-- <RET_ID>4711</RET_ID> -->
      <!-- <ReturnReason>Wrong size</ReturnReason> -->
      <!-- <CustomersComment>Too small</CustomersComment> -->
      <!-- <ReceiversComment>Packaging opened</ReceiversComment> -->
      <!-- <Employee>JD</Employee> -->
      <!-- <ReturnDate>2024-05-14T10:30:00</ReturnDate> -->
    </ns1:pixiAddReturnCaseLine>
  </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 = [
    'InvLineKey' => '123456',
    'QuantityToReturn' => '1',
    // 'ItemOk' => '1',
    // 'RET_ID' => '4711',
    // 'ReturnReason' => 'Wrong size',
    // 'CustomersComment' => 'Too small',
    // 'ReceiversComment' => 'Packaging opened',
    // 'Employee' => 'JD',
    // 'ReturnDate' => '2024-05-14T10:30:00',
];

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

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

pixiCreateReturnCase

Verwendete Tabellen

RET_CASE_LINES · Schreiben RET_CASES · Schreiben Invlines · Lesen Orderlines · Lesen Invoices · Lesen

SQL-Objekt:: dbo.pipiAddReturnCaseLine