Replacements Schreiben

pixiCreateReplacementOrder

Legt einen Ersatzauftrag für eine oder mehrere Retourenfall-Positionen an, protokolliert die Anforderung in der Retourenhistorie und liefert die neue Auftragsnummer.

Legt einen Ersatzauftrag für retournierte Artikel an, basierend auf den in ReturnLines übergebenen Retourenfall-Positionen.

Eingabeformat: ReturnLines ist eine Liste von RET_LINE_ID-Werten, getrennt durch , oder ; (z. B. 1024,1025). Semikolons werden in Kommas umgewandelt, die Zeichenkette wird getrimmt und bei Bedarf um ein abschließendes Komma ergänzt.

Ablauf

MwSt.-Prüfung: Nur für die erste Retourenposition werden das Lieferland der zugehörigen Rechnung (Invoices.ShipAdrRef → Addresses.Country) und das Länderkennzeichen ForceCountryVAT ermittelt. Existiert in VATs kein heute gültiger MwSt.-Satz für dieses Land:
- bei ForceCountryVAT = 1 wird ein Fehler ausgelöst und nichts geändert;
- andernfalls wird Pixi_InsertDefaultVATRateForCountry ausgeführt, um einen Standard-MwSt.-Satz aus dem Standardland abzuleiten.
Historie und Status: Für jede Retourenposition wird ein Eintrag in RET_CASES_HISTORY angelegt (ACTION_TYPE = 8, Text aus dem Übersetzungsschlüssel ReplacementRequestAPI in der Sprache Language_Id, wobei %ItemName% durch den Artikelnamen ersetzt wird). Der Status der Position in RET_CASE_LINES wird auf RPL (Ersatz in Bearbeitung) gesetzt. Als Bearbeiter wird Employee + ' (API)' gespeichert, bzw. API, wenn Employee leer ist.
Ersatzauftrag: Pixi_CreateReplacementForReturnLines wird mit allen Positionen aufgerufen. In einer eigenen Transaktion werden dort
- die ursprünglichen Auftragspositionen (nur Positionen mit Status AUS, nur Retourenpositionen mit Status RPL) mit der retournierten Menge gesammelt,
- die Retourenpositionen auf Status SHI (wartet auf Versand) gesetzt,
- Adressen für Kunde und Shop angelegt und der Ersatzauftrag über Pixi_CreateReplacementOrder erzeugt,
- die RET_LINE_ID in Orderlines.BackorderRef der neuen Auftragspositionen mit demselben Artikel geschrieben, damit der Retourenfall beim Versand abgeschlossen werden kann.
Die neue Auftragsnummer wird als einzelne Zeile (NewOrderNr), im Ausgabeparameter NewOrderNr und als Rückgabewert der Prozedur geliefert.

Hinweise

Keine Gesamttransaktion: Die Historieneinträge und die Statusänderung auf RPL werden vor und außerhalb der Transaktion von Pixi_CreateReplacementForReturnLines geschrieben. Schlägt die Anlage des Ersatzauftrags fehl, bleiben diese Änderungen bestehen.
Die MwSt.-Prüfung verwendet nur die erste Retourenposition. Kunde, Shop und Lager des neuen Auftrags stammen aus der zuletzt verarbeiteten Position; alle Positionen sollten daher zum selben Kunden bzw. zur selben Rechnung gehören.
Existiert die erste Retourenposition nicht, kann das Land nicht ermittelt werden, und der Aufruf scheitert mit einem Fehler aus Pixi_InsertDefaultVATRateForCountry (unbekannter Ländercode).
Retourenpositionen, deren ursprüngliche Auftragsposition nicht im Status AUS ist, werden übersprungen; trifft dies auf alle zu, löst die innere Prozedur Wrong Data aus. Fehler der inneren Prozedur werden über log.InsertError protokolliert und über sp_Exception_ReRaise erneut ausgelöst (nicht beigefügt; genaues Meldungsformat unbekannt).
Fallstricke beim Parsen der Liste: IDs werden per Textersetzung von ID, aus der Liste entfernt. IDs ohne Leerzeichen und ohne führende Nullen übergeben. Ein leerer Wert für ReturnLines oder IDs, die Endstücke anderer IDs der Liste sind (z. B. 12,112), können zu Parse-Fehlern oder einer Endlosschleife führen.
Lesezugriffe erfolgen mit NOLOCK.
Der Kopfkommentar der Prozedur („Checks pixi* user credentials“) passt nicht zu ihrer Funktion.
Die MwSt.-Fehlermeldung enthält die wörtlichen Platzhalter [Order/Invoice/...] und {shipping country}; sie werden nicht ersetzt.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`ReturnLines` Pflicht	varchar(max) string	–	Liste von Retourenfall-Positions-IDs (`RET_LINE_ID`), getrennt durch `,` oder `;`, für die ein Ersatzauftrag angelegt wird. Beispiel: `1024,1025`
`Employee`	varchar(50) string	NULL	Name des Mitarbeiters; wird als `<Employee> (API)` als Bearbeiter/Ersteller gespeichert. Bei NULL wird `API` verwendet. Beispiel: `JSmith`
`NewOrderNr` OUTPUT	int	NULL	Ausgabe: Auftragsnummer des angelegten Ersatzauftrags.
`Language_Id` Pflicht	int	–	Sprach-ID für die Übersetzung des Historientextes (Übersetzungsschlüssel `ReplacementRequestAPI`). Beispiel: `1`

Antwort

Result-Set 1 · Bei Erfolg, nach Anlage des Ersatzauftrags

Eine Zeile mit der Nummer des neuen Ersatzauftrags.

Spalte	Typ	Beschreibung
`NewOrderNr` Kann leer sein	int	Auftragsnummer des angelegten Ersatzauftrags.

Beispielantwort

<SqlRowSet1>
  <row>
    <NewOrderNr>584213</NewOrderNr>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
RAISERROR	The VAT rate for selected shipping country was not entered in pixi* Control Center. Since setting "Force Country VAT" is enabled for this country, creation of [Order/Invoice/...] is not possible. Please add VAT rates for country {shipping country} in pixi* Control Center and try again.	Für das Lieferland der ersten Retourenposition existiert kein heute gültiger MwSt.-Satz, und für das Land ist `ForceCountryVAT` aktiviert. MwSt.-Satz für das Land im pixi* Control Center anlegen.
RAISERROR	Error in [Pixi_InsertDefaultVATRateForCountry]: Unknown country code supplied on line {line}	Das Lieferland konnte nicht ermittelt werden, meist weil die erste ID in `ReturnLines` nicht existiert oder nicht mit einer Rechnungsposition mit Lieferadresse verknüpft ist. Gültige Retourenpositions-IDs übergeben.
RAISERROR	Wrong Data	Wird von `Pixi_CreateReplacementForReturnLines` ausgelöst, wenn keine Auftragspositionen ermittelt werden konnten (ursprüngliche Auftragspositionen nicht im Status `AUS`, Retourenpositionen nicht im Status `RPL`) oder kein Shop ermittelt werden konnte. Wird über `sp_Exception_ReRaise` erneut ausgelöst, der endgültige Text kann daher erweitert sein.

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:pixiCreateReplacementOrder>
      <ReturnLines>1024,1025</ReturnLines>
      <!-- <Employee>JSmith</Employee> -->
      <!-- <NewOrderNr>?</NewOrderNr> -->
      <Language_Id>1</Language_Id>
    </ns1:pixiCreateReplacementOrder>
  </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:pixiCreateReplacementOrder>
      <ReturnLines>1024,1025</ReturnLines>
      <!-- <Employee>JSmith</Employee> -->
      <!-- <NewOrderNr>?</NewOrderNr> -->
      <Language_Id>1</Language_Id>
    </ns1:pixiCreateReplacementOrder>
  </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 = [
    'ReturnLines' => '1024,1025',
    // 'Employee' => 'JSmith',
    // 'NewOrderNr' => '?',
    'Language_Id' => '1',
];

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

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

Verwendete Tabellen

RET_CASE_LINES · Schreiben RET_CASES_HISTORY · Schreiben InvLines · Lesen Invoices · Lesen Addresses · Lesen Countries · Lesen VATs · Lesen Items · Lesen

SQL-Objekt:: dbo.pipiCreateReplacementOrder