pixiSetCustomerDiscount

Updates the field Rabat of exactly one customer in Customers and returns a status row.

Validation

Discount is mandatory and must be between 0 and 100, inclusive.
Empty strings in CustMail and CustNr are treated as NULL. At least one of them must be supplied.

Customer lookup

The procedure counts customers matching CeMail = CustMail, customers matching CustomerNrExternal = CustNr, and customers matching both. If CustNr is not supplied, the last check only requires a matching e-mail and a non-NULL customer number. The customer is then chosen as follows:

If exactly one customer has the e-mail address, that customer is used. CustNr is ignored in this case.
If no customer has the e-mail address and exactly one customer has the customer number, that customer is used.
If several customers share the e-mail address and exactly one of them matches the customer number, that one is used.
Otherwise an error row is returned. The message is either More then one customer found… or No customer found….

Update and result

The procedure sets Rabat to Discount for the chosen customer. It then returns one row with Status = Success and a message containing the new discount, the customer's e-mail address and the external customer number. Every error, including validation errors, is returned as a single row with Status = Error and the error text in Message.

Notes

Errors never arrive as SqlMessage. They are caught and returned as a row with Status = Error, so always check the Status column.
Pitfall: if the e-mail address matches exactly one customer, that customer is updated even when the supplied CustNr belongs to a different customer or matches no customer.
The success message is built by string concatenation. If the customer's CeMail or CustomerNrExternal is NULL, Message is likely to be NULL (the usual SQL Server behaviour with CONCAT_NULL_YIELDS_NULL), although the update has been done.
Lookups use NOLOCK and the update uses ROWLOCK. No explicit transaction is used.
E-mail and customer number are compared with =. Whether the comparison is case-sensitive depends on the database collation.

Tables used

Customers · Write

Parameter	Type	Default	Description
`CustMail`	varchar(256) string	NULL	E-mail address of the customer (`CeMail`). An empty string is treated as NULL. Either this parameter or `CustNr` must be supplied. Example: `max.mustermann@example.com`
`CustNr`	varchar(60) string	NULL	External customer number (`CustomerNrExternal`). An empty string is treated as NULL. Used when no customer has the e-mail address, or to choose between several customers with the same e-mail address. Example: `K100234`
`Discount`	numeric(6, 2) decimal	NULL	Discount in percent to store in `Rabat`. Mandatory in practice: it must be supplied and must be between 0 and 100. Example: `7.50`

Result set 1 · Always; exactly one row, either `Success` or `Error`

Status row of the call.

Column	Type	Description
`Status`	varchar(7) string	`Success` if the discount was set, `Error` otherwise.
`Message` Nullable	nvarchar(4000) string	On success, a confirmation with the stored discount, e-mail address and customer number. On error, the error text. It can be NULL on success if the customer's e-mail or customer number is NULL.

Response example

<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>

Status	Message	Cause
Error	API call pixiSetCustomerDiscount expects parameter @Discount, which was not supplied.	`Discount` was not supplied or is NULL. Always pass a discount value.
Error	Parameter @Discount can only have value from 0 to 100.	`Discount` is below 0 or above 100. Pass a value from 0 to 100.
Error	Parameters @CustMail and @CustNr are empty.	Neither an e-mail address nor a customer number was supplied. Pass at least one of them.
Error	More then one customer found with given parameters	The customer is ambiguous. Either several customers match both e-mail and customer number, or no customer has the e-mail address and several share the customer number. Supply more specific values.
Error	No customer found with given e-mail or customer number	No customer matches the supplied values. This also occurs if several customers share the e-mail address and none of them matches the customer number.

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);

Notes

Tables used

Result set 1 · Always; exactly one row, either Success or Error

Response example

Result set 1 · Always; exactly one row, either `Success` or `Error`