Returns Schreiben

pixiReturnCaseUpdate

Setzt die Rücksendekosten eines eingegangenen Retourenfalls, netto bei B2B und brutto bei B2C, nach Prüfung gegen den erstattungsfähigen Betrag.

Aktualisiert die Rücksendekosten eines Retourenfalls in pixi.Return.

Ablauf:

UserName wird getrimmt. Ein leerer Wert wird zu API.
ReturnId und ReturnCost müssen beide angegeben sein.
Der Retourenfall muss existieren.
Der Retourenfall muss im Status StatusId = 2 (Eingegangen) sein.
ReturnCost darf nicht negativ sein. Der Wert 0 wird akzeptiert.
Die Obergrenze wird aus dem Retourenfall und der zugehörigen Rechnung berechnet (Invoices.InvoiceKey = Return.InvoiceId). Sie ergibt sich aus dem Betrag der retournierten Artikel plus der Versandkostenerstattung abzüglich des Gutscheinbetrags:
- bei B2B-Aufträgen: TotalToRefundNet + ShippingCostRefundNet - VoucherAmountNet
- bei B2C-Aufträgen: TotalToRefundGross + ShippingCostRefundGross - VoucherAmountGross
Liegt ReturnCost über dieser Grenze, wird eine Fehlerzeile geliefert.
Die Kosten werden in den Retourenfall geschrieben:
- B2C: der Wert wird in ReturnCostGross gespeichert.
- jeder andere Auftragstyp: der Wert wird in ReturnCostNet gespeichert.
Zusätzlich werden RecordModifiedByUserId und RecordModifiedOn gesetzt.

Die Benutzer-ID wird über UserName ermittelt. Existiert dieser Benutzer nicht, wird der Benutzer pixiAdministration verwendet.

Der Aufruf liefert genau eine Zeile mit Status und Message, sowohl bei Erfolg als auch bei Fehlern.

Hinweise

Die Prüfabfragen verwenden NOLOCK, das Update verwendet ROWLOCK. Es wird keine explizite Transaktion verwendet.
Fallstrick: Die Prüfung der Obergrenze entfällt in drei Fällen:
- es wird keine passende Rechnung in Invoices gefunden, der Auftragstyp bleibt daher NULL;
- der Auftragstyp ist weder B2B noch B2C;
- eine der Betragsspalten ist NULL.
In den ersten beiden Fällen wird der Wert ohne Grenzprüfung in ReturnCostNet geschrieben.
Der Fehlertext 'must be greater than 0' ist irreführend: Abgelehnt werden nur negative Werte, 0 wird akzeptiert.
Bei Fehlern liefert die Prozedur zusätzlich den Rückgabewert 1. Für SOAP-Clients ist die Statuszeile maßgeblich.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`ReturnId`	int	NULL	ID des Retourenfalls (`pixi.Return.id`). Faktisch erforderlich. Beispiel: `1542`
`ReturnCost`	money decimal	NULL	Zu speichernde Rücksendekosten. Sie werden bei B2B als Netto- und bei B2C als Bruttowert gespeichert. Der Wert darf weder negativ sein noch den erstattungsfähigen Betrag überschreiten. Faktisch erforderlich. Beispiel: `5.95`
`UserName`	varchar(50) string	API	Name des Benutzers, der als Bearbeiter gespeichert wird. Ein leerer Wert wird zu `API`. Bei unbekanntem Benutzer wird `pixiAdministration` verwendet. Beispiel: `API`

Antwort

Result-Set 1 · Immer (eine Zeile, bei Erfolg oder Fehler)

Statuszeile der Aktualisierung.

Spalte	Typ	Beschreibung
`Status`	varchar(7) string	`Success` oder `Error`.
`Message`	varchar string	Erfolgs- oder Fehlermeldung.

Beispielantwort

<SqlRowSet1>
  <row>
    <Status>Success</Status>
    <Message>Return Case updated successfully.</Message>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
Error	Return id and return costs needs to be provided	`ReturnId` oder `ReturnCost` fehlt. Beide Parameter übergeben.
Error	No return found for return Id: {ReturnId}	Es existiert kein Retourenfall mit dieser ID. ID prüfen.
Error	Return id {ReturnId} is not in received status.	Der Retourenfall hat nicht `StatusId = 2` (Eingegangen). Die Kosten lassen sich nur bei eingegangenen Retouren setzen.
Error	Return cost must be greater than 0.	`ReturnCost` ist negativ. Der Wert 0 wird akzeptiert.
Error	Return cost must be less then Returned items amount + Shipping costs - Discount voucher.	`ReturnCost` übersteigt den erstattungsfähigen Betrag: netto bei B2B, brutto bei B2C.

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:pixiReturnCaseUpdate>
      <!-- <ReturnId>1542</ReturnId> -->
      <!-- <ReturnCost>5.95</ReturnCost> -->
      <!-- <UserName>API</UserName> -->
    </ns1:pixiReturnCaseUpdate>
  </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:pixiReturnCaseUpdate>
      <!-- <ReturnId>1542</ReturnId> -->
      <!-- <ReturnCost>5.95</ReturnCost> -->
      <!-- <UserName>API</UserName> -->
    </ns1:pixiReturnCaseUpdate>
  </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 = [
    // 'ReturnId' => '1542',
    // 'ReturnCost' => '5.95',
    // 'UserName' => 'API',
];

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

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

Verwendete Tabellen

Return · Schreiben Invoices · Lesen UCS_USERS · Lesen

SQL-Objekt:: dbo.pipiReturnCaseUpdate