Orders Write

pixiChangeAddress

Changes the billing or shipping address of an order, as long as the order has not been invoiced yet.

Updates the address record that is linked to an order and returns a status text.

The order is identified either by OrderNr or by OrderNrExternal. OrderNr = 0 and an empty OrderNrExternal are treated as not set.
The function pipiCanChangeAddress checks whether the address may be changed. It returns 0 if no order is given or if any order line of the order already has an invoice line (InvLines). Otherwise it returns 1.
The address key is read from the order lines (Orderlines):
- If AddrType contains B (not case-sensitive), the billing address (AddrRef) is used.
- Otherwise the shipping address (ShipAdrRef) is used. This also applies to S, other values and an empty value.
If changing is allowed and an address was found, the address is updated:
- Empty strings are treated as "not passed". Every parameter that is not passed keeps the current value of the address. Only the fields that are passed are changed.
- ASlocked sets the shipping lock: 1 sets ASlocked = 'Y', any other numeric value sets 'N'. If it is omitted, the current value is kept.
- For shipping addresses (AddrType = 'S' in Addresses), a row is written to pixi.AddressesShippingLockHistory when the lock state changes.
- UpdateDate is set to the current date and UpdateEmp to api.
The status is returned in the output parameter FunctionResult and as a single row with the column Result.

Notes

Pass only one order identifier. If both OrderNr and OrderNrExternal are passed, no order line matches. The result is then 402 Address not found.
Fields cannot be cleared. Empty values are ignored and the existing value is kept. The exception is CareOf: an empty string is written as an empty string.
ASlocked must be numeric. The code compares it with the number 1. A value such as Y therefore causes an SQL conversion error, which is returned as SqlMessage. Use 1 or 0.
Lock history. The history row is only written if the stored ASlocked value differs from the new value. If the stored value is NULL, no history row is written. The user ID for the history is the user api, or pixiAdministration as a fallback.
Orders with several lines. The address key is taken from one of the order lines; the code does not determine which one. Orders whose lines reference different addresses are not handled specifically.
Reads and transactions. Order lines and addresses are read with NOLOCK. There is no explicit transaction.
Status codes. The codes 200–403 are plain text codes and not HTTP statuses. If neither changing is allowed nor an address is found, 402 overrides 401.

pixiCanChangeAddress

Tables used

Orderlines · Read InvLines · Read Addresses · Write AddressesShippingLockHistory · Write UCS_USERS · Read

Parameter	Type	Default	Description
`OrderNr`	int	NULL	Pixi order number. 0 is treated as NULL. Pass either this or `OrderNrExternal`, not both. Example: `123456`
`OrderNrExternal`	varchar(50) string	NULL	External (shop) order number. An empty string is treated as NULL. Used only if `OrderNr` is not set. Example: `SHOP-100234`
`AddrType` Required	char(2) string	–	Selects which address of the order is changed. A value containing `B` selects the billing address; all other values select the shipping address. Allowed values `B` – Billing address (`AddrRef` of the order) `S` – Shipping address (`ShipAdrRef` of the order); also used for any other value Example: `S`
`Anrede`	varchar(60) string	NULL	Salutation. If empty or omitted, the current value is kept. Example: `Herr`
`FirstName`	varchar(60) string	NULL	First name. If empty or omitted, the current value is kept. Example: `Max`
`LastName`	varchar(60) string	NULL	Last name. If empty or omitted, the current value is kept. Example: `Mustermann`
`CareOf`	varchar(60) string	NULL	Address addition (c/o). If omitted, the current value is kept. Unlike the other fields, an empty string is stored as an empty string. Example: `c/o Firma Beispiel GmbH`
`Street`	varchar(100) string	NULL	Street. If empty or omitted, the current value is kept. Example: `Hauptstraße`
`HouseNr`	varchar(12) string	NULL	House number. If empty or omitted, the current value is kept. Example: `12a`
`City`	varchar(50) string	NULL	City. If empty or omitted, the current value is kept. Example: `München`
`State`	varchar(3) string	NULL	State or region code. If empty or omitted, the current value is kept. Example: `BY`
`ZIP`	varchar(10) string	NULL	Postal code. If empty or omitted, the current value is kept. Example: `80331`
`Country`	varchar(3) string	NULL	Country code. If empty or omitted, the current value is kept. Example: `DE`
`Phone`	varchar(60) string	NULL	Phone number. If empty or omitted, the current value is kept. Example: `+49 89 1234567`
`Phone2`	varchar(60) string	NULL	Second phone number. If empty or omitted, the current value is kept. Example: `+49 170 1234567`
`Fax`	varchar(60) string	NULL	Fax number. If empty or omitted, the current value is kept. Example: `+49 89 1234568`
`Fax2`	varchar(60) string	NULL	Second fax number. If empty or omitted, the current value is kept.
`eMail`	varchar(60) string	NULL	E-mail address. If empty or omitted, the current value is kept. Example: `max.mustermann@example.com`
`Account`	varchar(10) string	NULL	Bank account number (column `AAccount`). If empty or omitted, the current value is kept. Example: `1234567890`
`BLZ`	varchar(8) string	NULL	German bank code (column `ABLZ`). If empty or omitted, the current value is kept. Example: `70050000`
`BankName`	varchar(50) string	NULL	Bank name (column `ABankName`). If empty or omitted, the current value is kept. Example: `Beispielbank`
`AccName`	varchar(27) string	NULL	Account holder (column `AAccName`). If empty or omitted, the current value is kept. Example: `Max Mustermann`
`BIC`	varchar(11) string	NULL	BIC. If empty or omitted, the current value is kept. Example: `BYLADEM1001`
`IBAN`	varchar(35) string	NULL	IBAN. If empty or omitted, the current value is kept. Example: `DE02120300000000202051`
`ASlocked`	varchar(1) string	NULL	Shipping lock. `1` stores `Y`, any other numeric value stores `N`. If empty or omitted, the current value is kept. Non-numeric values cause a conversion error. Allowed values `1` – Set the shipping lock (`ASlocked = 'Y'`) `0` – Remove the shipping lock (`ASlocked = 'N'`) Example: `0`
`FunctionResult` OUTPUT	varchar(128) string	NULL	Output: status text, for example `200 OK`. The same text is returned in the column `Result`.
`CardHolderName`	varchar(60) string	NULL	Card holder name (column `ACardName`). If empty or omitted, the current value is kept. Example: `MAX MUSTERMANN`
`Note`	varchar(8000) string	NULL	Note on the address. If empty or omitted, the current value is kept. Example: `Bitte beim Nachbarn abgeben`
`VatId`	varchar(20) string	NULL	VAT ID (column `UsStId`). If empty or omitted, the current value is kept. Example: `DE123456789`

Result set 1 · Always

A single row with the status text of the operation.

Column	Type	Description
`Result` Nullable	varchar(128) string	Status text: `200 OK`, `401 …`, `402 …` or `403 …`

Response example

<SqlRowSet1>
  <row>
    <Result>200 OK</Result>
  </row>
</SqlRowSet1>

Status	Message	Cause
401	401 Cannot change address according to pixiCanChangeAddress	The order has already been (partly) invoiced, or no order identifier was passed. Addresses of invoiced orders cannot be changed with this call.
402	402 Address not found	No order line matches the order number, both `OrderNr` and `OrderNrExternal` were passed, or the order has no address reference of the requested type. This status overrides `401`.
403	403 Unknown error	The update affected no row, for example because the referenced address record does not exist in `Addresses`.

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:pixiChangeAddress>
      <!-- <OrderNr>123456</OrderNr> -->
      <!-- <OrderNrExternal>SHOP-100234</OrderNrExternal> -->
      <AddrType>S</AddrType>
      <!-- <Anrede>Herr</Anrede> -->
      <!-- <FirstName>Max</FirstName> -->
      <!-- <LastName>Mustermann</LastName> -->
      <!-- <CareOf>c/o Firma Beispiel GmbH</CareOf> -->
      <!-- <Street>Hauptstraße</Street> -->
      <!-- <HouseNr>12a</HouseNr> -->
      <!-- <City>München</City> -->
      <!-- <State>BY</State> -->
      <!-- <ZIP>80331</ZIP> -->
      <!-- <Country>DE</Country> -->
      <!-- <Phone>+49 89 1234567</Phone> -->
      <!-- <Phone2>+49 170 1234567</Phone2> -->
      <!-- <Fax>+49 89 1234568</Fax> -->
      <!-- <Fax2>?</Fax2> -->
      <!-- <eMail>max.mustermann@example.com</eMail> -->
      <!-- <Account>1234567890</Account> -->
      <!-- <BLZ>70050000</BLZ> -->
      <!-- <BankName>Beispielbank</BankName> -->
      <!-- <AccName>Max Mustermann</AccName> -->
      <!-- <BIC>BYLADEM1001</BIC> -->
      <!-- <IBAN>DE02120300000000202051</IBAN> -->
      <!-- <ASlocked>0</ASlocked> -->
      <!-- <FunctionResult>?</FunctionResult> -->
      <!-- <CardHolderName>MAX MUSTERMANN</CardHolderName> -->
      <!-- <Note>Bitte beim Nachbarn abgeben</Note> -->
      <!-- <VatId>DE123456789</VatId> -->
    </ns1:pixiChangeAddress>
  </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:pixiChangeAddress>
      <!-- <OrderNr>123456</OrderNr> -->
      <!-- <OrderNrExternal>SHOP-100234</OrderNrExternal> -->
      <AddrType>S</AddrType>
      <!-- <Anrede>Herr</Anrede> -->
      <!-- <FirstName>Max</FirstName> -->
      <!-- <LastName>Mustermann</LastName> -->
      <!-- <CareOf>c/o Firma Beispiel GmbH</CareOf> -->
      <!-- <Street>Hauptstraße</Street> -->
      <!-- <HouseNr>12a</HouseNr> -->
      <!-- <City>München</City> -->
      <!-- <State>BY</State> -->
      <!-- <ZIP>80331</ZIP> -->
      <!-- <Country>DE</Country> -->
      <!-- <Phone>+49 89 1234567</Phone> -->
      <!-- <Phone2>+49 170 1234567</Phone2> -->
      <!-- <Fax>+49 89 1234568</Fax> -->
      <!-- <Fax2>?</Fax2> -->
      <!-- <eMail>max.mustermann@example.com</eMail> -->
      <!-- <Account>1234567890</Account> -->
      <!-- <BLZ>70050000</BLZ> -->
      <!-- <BankName>Beispielbank</BankName> -->
      <!-- <AccName>Max Mustermann</AccName> -->
      <!-- <BIC>BYLADEM1001</BIC> -->
      <!-- <IBAN>DE02120300000000202051</IBAN> -->
      <!-- <ASlocked>0</ASlocked> -->
      <!-- <FunctionResult>?</FunctionResult> -->
      <!-- <CardHolderName>MAX MUSTERMANN</CardHolderName> -->
      <!-- <Note>Bitte beim Nachbarn abgeben</Note> -->
      <!-- <VatId>DE123456789</VatId> -->
    </ns1:pixiChangeAddress>
  </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 = [
    // 'OrderNr' => '123456',
    // 'OrderNrExternal' => 'SHOP-100234',
    'AddrType' => 'S',
    // 'Anrede' => 'Herr',
    // 'FirstName' => 'Max',
    // 'LastName' => 'Mustermann',
    // 'CareOf' => 'c/o Firma Beispiel GmbH',
    // 'Street' => 'Hauptstraße',
    // 'HouseNr' => '12a',
    // 'City' => 'München',
    // 'State' => 'BY',
    // 'ZIP' => '80331',
    // 'Country' => 'DE',
    // 'Phone' => '+49 89 1234567',
    // 'Phone2' => '+49 170 1234567',
    // 'Fax' => '+49 89 1234568',
    // 'Fax2' => '?',
    // 'eMail' => 'max.mustermann@example.com',
    // 'Account' => '1234567890',
    // 'BLZ' => '70050000',
    // 'BankName' => 'Beispielbank',
    // 'AccName' => 'Max Mustermann',
    // 'BIC' => 'BYLADEM1001',
    // 'IBAN' => 'DE02120300000000202051',
    // 'ASlocked' => '0',
    // 'FunctionResult' => '?',
    // 'CardHolderName' => 'MAX MUSTERMANN',
    // 'Note' => 'Bitte beim Nachbarn abgeben',
    // 'VatId' => 'DE123456789',
];

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

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

SQL object:: dbo.pipiChangeAddress

pixiChangeAddress

Notes

Related calls

Tables used

Result set 1 · Always

Response example