Customers Schreiben

pixiUpdateCustomer

Aktualisiert E-Mail, Name und Postanschrift eines bestehenden Kunden und seiner verknüpften Adresse und sichert die bisherige Adresse in der Adresshistorie.

Aktualisiert einen über CustKey identifizierten Kunden zusammen mit der über Customers.AddrRef verknüpften Adresse.

Alle Textparameter werden getrimmt. Leere Zeichenketten werden als NULL behandelt.
Der Kunde wird über CustKey gesucht und mit seiner Adresse verknüpft. Der Kunde muss eine verknüpfte Adresse haben.
- Kein Treffer: Status 404.
- Mehr als ein Treffer: Status 409.
Wird genau ein Kunde gefunden, laufen die folgenden Schritte in einer Transaktion:
- Die aktuelle Adresse wird in die Adresshistorie kopiert. HUpdateEmp wird auf API und HNoteHist auf Duplicate Check App gesetzt.
- Die E-Mail des Kunden (Customers.CeMail) wird auf eMail gesetzt. Das geschieht immer, auch wenn eMail NULL ist.
- Die Adresse wird aktualisiert. Nur Parameter ungleich NULL ändern den gespeicherten Wert:
  - FirstName, LastName, Street, HouseNr, City, ZIP und eMail werden einzeln aktualisiert.
  - Name wird aus Vorname + Leerzeichen + Nachname neu gebildet.
  - Address wird aus Straße + Leerzeichen + Hausnummer neu gebildet.
- Der Aufruf liefert Status 200.
Bei einem SQL-Fehler wird die Transaktion zurückgerollt. Der Aufruf liefert dann Status 500 mit dem SQL-Fehlertext.

Der Aufruf liefert immer genau eine Statuszeile mit StatusCode und ErrorMsg. ErrorMsg enthält auch die Erfolgsmeldung.

Hinweise

Stolperfalle – Kunden-E-Mail wird geleert: Customers.CeMail wird ohne NULL-Prüfung mit eMail überschrieben. Wird eMail weggelassen oder leer übergeben, wird die E-Mail des Kunden geleert. Nur die Adress-E-Mail (Addresses.eMail) behält ihren alten Wert. Soll die E-Mail unverändert bleiben, muss immer die aktuelle E-Mail übergeben werden.
Stolperfalle – neu gebildete Felder: Name und Address werden immer aus Vor-/Nachname bzw. Straße/Hausnummer neu gebildet. Dabei werden die Parameter verwendet, oder die gespeicherten Spaltenwerte, wenn ein Parameter NULL ist. Ist einer der beiden Teile sowohl im Parameter als auch in der gespeicherten Spalte NULL, ergibt sich in der Regel NULL (Standardverhalten von CONCAT_NULL_YIELDS_NULL). Manuell gepflegte Werte in Name oder Address werden überschrieben.
Nicht in der Historie: Der Historieneintrag speichert nur die klassischen Adressfelder (z. B. Name, Address, City, ZIP). FirstName, LastName, Street, HouseNr und eMail werden dort nicht gesichert.
Context-Info: Während der Adressaktualisierung wird CONTEXT_INFO der Sitzung auf 0x33999 gesetzt und danach auf 0x00000 zurückgesetzt. Der Zweck ist im Code nicht ersichtlich; vermutlich wird der Wert von Triggern auf Addresses ausgewertet.
Sperren: Die Suche liest mit NOLOCK. Die Updates verwenden ROWLOCK innerhalb der benannten Transaktion UpdateCustomer.
Fehlerbehandlung: Der CATCH-Block führt immer ROLLBACK TRANSACTION aus. Tritt ein Fehler auf, bevor die Transaktion gestartet wurde, kann dieser Rollback einen zusätzlichen SQL-Fehler auslösen. Dieser kommt als SqlMessage neben der Statuszeile 500 zurück.
Aufräumen: Die temporäre Tabelle wird über util.TempTableDrop gelöscht. Die Definition dieses Objekts liegt nicht vor.
NULL-Schlüssel: Ist CustKey NULL, wird Status 404 geliefert und ErrorMsg ist NULL.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`CustKey` Pflicht	int	–	Schlüssel des zu aktualisierenden Kunden. Beispiel: `12345`
`Street`	varchar(255) string	NULL	Neue Straße. Wird getrimmt; leer oder `NULL` behält die gespeicherte Straße. Wird auch zum Neubilden von `Address` verwendet. Beispiel: `Hauptstraße`
`HouseNr`	varchar(10) string	NULL	Neue Hausnummer. Wird getrimmt; leer oder `NULL` behält den gespeicherten Wert. Wird auch zum Neubilden von `Address` verwendet. Beispiel: `12a`
`City`	varchar(60) string	NULL	Neuer Ort. Wird getrimmt; leer oder `NULL` behält den gespeicherten Ort. Beispiel: `München`
`Zip`	varchar(10) string	NULL	Neue Postleitzahl. Wird getrimmt; leer oder `NULL` behält den gespeicherten Wert. Beispiel: `80331`
`eMail`	varchar(256) string	NULL	Neue E-Mail-Adresse. Wird getrimmt. Wird immer in `Customers.CeMail` geschrieben, `NULL` oder leer leert den Wert dort. In `Addresses.eMail` nur, wenn nicht `NULL`. Beispiel: `max.mustermann@example.com`
`FirstName`	varchar(60) string	NULL	Neuer Vorname. Wird getrimmt; leer oder `NULL` behält den gespeicherten Wert. Wird auch zum Neubilden von `Name` verwendet. Beispiel: `Max`
`LastName`	varchar(60) string	NULL	Neuer Nachname. Wird getrimmt; leer oder `NULL` behält den gespeicherten Wert. Wird auch zum Neubilden von `Name` verwendet. Beispiel: `Mustermann`

Antwort

Result-Set 1 · Immer

Statuszeile mit HTTP-ähnlichem Statuscode und Meldung (Erfolgs- oder Fehlertext).

Spalte	Typ	Beschreibung
`StatusCode`	varchar(10) string	`200` = aktualisiert, `404` = Kunde nicht gefunden, `409` = Kunde nicht eindeutig, `500` = SQL-Fehler.
`ErrorMsg` Kann leer sein	varchar(4000) string	Meldungstext; enthält bei Status `200` auch die Erfolgsmeldung.

Beispielantwort

<SqlRowSet1>
  <row>
    <StatusCode>200</StatusCode>
    <ErrorMsg>Customer with CustKey: 12345 was updated.</ErrorMsg>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
404	Customer with CustKey: {CustKey} does not exist.	Kein Kunde mit diesem `CustKey` vorhanden oder der Kunde hat keine verknüpfte Adresse (`AddrRef`). Schlüssel prüfen.
409	Customer with CustKey: {CustKey} could not be uniquely identified. {RowCount} customers found.	Die Suche nach Kunde und Adresse lieferte mehr als eine Zeile. Es wird nichts aktualisiert.
500	{ERROR_MESSAGE()}	Ein SQL-Fehler ist aufgetreten, z. B. ein Constraint- oder Triggerfehler. Die Transaktion wird zurückgerollt und der SQL-Fehlertext geliefert.

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:pixiUpdateCustomer>
      <CustKey>12345</CustKey>
      <!-- <Street>Hauptstraße</Street> -->
      <!-- <HouseNr>12a</HouseNr> -->
      <!-- <City>München</City> -->
      <!-- <Zip>80331</Zip> -->
      <!-- <eMail>max.mustermann@example.com</eMail> -->
      <!-- <FirstName>Max</FirstName> -->
      <!-- <LastName>Mustermann</LastName> -->
    </ns1:pixiUpdateCustomer>
  </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:pixiUpdateCustomer>
      <CustKey>12345</CustKey>
      <!-- <Street>Hauptstraße</Street> -->
      <!-- <HouseNr>12a</HouseNr> -->
      <!-- <City>München</City> -->
      <!-- <Zip>80331</Zip> -->
      <!-- <eMail>max.mustermann@example.com</eMail> -->
      <!-- <FirstName>Max</FirstName> -->
      <!-- <LastName>Mustermann</LastName> -->
    </ns1:pixiUpdateCustomer>
  </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 = [
    'CustKey' => '12345',
    // 'Street' => 'Hauptstraße',
    // 'HouseNr' => '12a',
    // 'City' => 'München',
    // 'Zip' => '80331',
    // 'eMail' => 'max.mustermann@example.com',
    // 'FirstName' => 'Max',
    // 'LastName' => 'Mustermann',
];

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

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

Verwendete Tabellen

Customers · Schreiben Addresses · Schreiben AddressesHist · Schreiben

SQL-Objekt:: dbo.pipiUpdateCustomer