Customers Schreiben

pixiSetCustomerDiscount

Setzt den Rabatt in Prozent (`Rabat`) eines Kunden, der über E-Mail-Adresse und/oder externe Kundennummer ermittelt wird.

Aktualisiert das Feld Rabat genau eines Kunden in Customers und liefert eine Statuszeile.

Prüfungen

Discount ist Pflicht und muss zwischen 0 und 100 liegen (einschließlich).
Leere Zeichenketten in CustMail und CustNr werden als NULL behandelt. Mindestens einer der beiden Parameter muss angegeben werden.

Kundensuche

Gezählt werden Kunden mit CeMail = CustMail, Kunden mit CustomerNrExternal = CustNr sowie Kunden, auf die beides zutrifft. Ohne CustNr verlangt die letzte Prüfung nur eine passende E-Mail-Adresse und eine nicht leere (nicht NULL) Kundennummer. Die Auswahl erfolgt so:

Hat genau ein Kunde die E-Mail-Adresse, wird dieser Kunde verwendet. CustNr wird dann ignoriert.
Hat kein Kunde die E-Mail-Adresse, aber genau ein Kunde die Kundennummer, wird dieser verwendet.
Haben mehrere Kunden die E-Mail-Adresse und passt genau einer davon zur Kundennummer, wird dieser verwendet.
Andernfalls wird eine Fehlerzeile geliefert, entweder More then one customer found… oder No customer found….

Aktualisierung und Ergebnis

Für den gefundenen Kunden wird Rabat auf Discount gesetzt. Anschließend wird eine Zeile mit Status = Success geliefert. Die Meldung enthält den neuen Rabatt, die E-Mail-Adresse und die externe Kundennummer des Kunden. Alle Fehler, auch Prüfungsfehler, werden als einzelne Zeile mit Status = Error und dem Fehlertext in Message zurückgegeben.

Hinweise

Fehler kommen nie als SqlMessage zurück. Sie werden abgefangen und als Zeile mit Status = Error geliefert; daher immer die Spalte Status prüfen.
Stolperfalle: Passt die E-Mail-Adresse zu genau einem Kunden, wird dieser Kunde aktualisiert, auch wenn die angegebene CustNr zu einem anderen oder zu keinem Kunden gehört.
Die Erfolgsmeldung wird per Zeichenkettenverkettung erzeugt. Ist CeMail oder CustomerNrExternal des Kunden NULL, ist Message voraussichtlich NULL (übliches SQL-Server-Verhalten bei CONCAT_NULL_YIELDS_NULL), obwohl die Aktualisierung erfolgt ist.
Die Suchabfragen verwenden NOLOCK, das Update verwendet ROWLOCK. Eine explizite Transaktion gibt es nicht.
E-Mail-Adresse und Kundennummer werden mit = verglichen. Ob dabei Groß-/Kleinschreibung zählt, hängt von der Datenbank-Collation ab.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`CustMail`	varchar(256) string	NULL	E-Mail-Adresse des Kunden (`CeMail`). Eine leere Zeichenkette gilt als NULL. Dieser Parameter oder `CustNr` muss angegeben werden. Beispiel: `max.mustermann@example.com`
`CustNr`	varchar(60) string	NULL	Externe Kundennummer (`CustomerNrExternal`). Eine leere Zeichenkette gilt als NULL. Wird verwendet, wenn kein Kunde die E-Mail-Adresse hat, oder um zwischen mehreren Kunden mit derselben E-Mail-Adresse zu unterscheiden. Beispiel: `K100234`
`Discount`	numeric(6, 2) decimal	NULL	Rabatt in Prozent, der in `Rabat` gespeichert wird. Faktisch Pflicht: Der Wert muss angegeben werden und zwischen 0 und 100 liegen. Beispiel: `7.50`

Antwort

Result-Set 1 · Immer; genau eine Zeile, entweder `Success` oder `Error`

Statuszeile des Aufrufs.

Spalte	Typ	Beschreibung
`Status`	varchar(7) string	`Success`, wenn der Rabatt gesetzt wurde, sonst `Error`.
`Message` Kann leer sein	nvarchar(4000) string	Bei Erfolg eine Bestätigung mit gespeichertem Rabatt, E-Mail-Adresse und Kundennummer. Bei Fehler der Fehlertext. Kann bei Erfolg NULL sein, wenn E-Mail-Adresse oder Kundennummer des Kunden NULL ist.

Beispielantwort

<SqlRowSet1>
  <row>
    <Status>Success</Status>
    <Message>Discount of 7.50% was set for customer: (e-mail: "max.mustermann@example.com" customer number: "K100234")</Message>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
Error	API call pixiSetCustomerDiscount expects parameter @Discount, which was not supplied.	`Discount` wurde nicht angegeben oder ist NULL. Immer einen Rabattwert übergeben.
Error	Parameter @Discount can only have value from 0 to 100.	`Discount` ist kleiner als 0 oder größer als 100. Einen Wert von 0 bis 100 übergeben.
Error	Parameters @CustMail and @CustNr are empty.	Weder E-Mail-Adresse noch Kundennummer wurde angegeben. Mindestens einen der beiden Werte übergeben.
Error	More then one customer found with given parameters	Der Kunde ist nicht eindeutig. Entweder passen mehrere Kunden zu E-Mail-Adresse und Kundennummer, oder kein Kunde hat die E-Mail-Adresse und mehrere teilen sich die Kundennummer. Eindeutigere Werte angeben.
Error	No customer found with given e-mail or customer number	Kein Kunde passt zu den angegebenen Werten. Tritt auch auf, wenn mehrere Kunden die E-Mail-Adresse teilen und keiner zur Kundennummer passt.

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:pixiSetCustomerDiscount>
      <!-- <CustMail>max.mustermann@example.com</CustMail> -->
      <!-- <CustNr>K100234</CustNr> -->
      <!-- <Discount>7.50</Discount> -->
    </ns1:pixiSetCustomerDiscount>
  </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:pixiSetCustomerDiscount>
      <!-- <CustMail>max.mustermann@example.com</CustMail> -->
      <!-- <CustNr>K100234</CustNr> -->
      <!-- <Discount>7.50</Discount> -->
    </ns1:pixiSetCustomerDiscount>
  </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 = [
    // 'CustMail' => 'max.mustermann@example.com',
    // 'CustNr' => 'K100234',
    // 'Discount' => '7.50',
];

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

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

Verwendete Tabellen

Customers · Schreiben

SQL-Objekt:: dbo.pipiSetCustomerDiscount