Customers Schreiben

pixiCustomerInfoSet

Aktualisiert Rechnungszahlungsziel und Mahneinstellungen eines Kunden, identifiziert über CustKey oder externe Kundennummer/E-Mail plus Shop.

Ändert die Zahlungs- und Mahneinstellungen genau eines Kundendatensatzes in Customers.

Identifikation des Kunden

Entweder CustKey übergeben oder ShopId zusammen mit CustomerNrExternal und/oder CustomerEmail.
CustomerNrExternal, CustomerEmail und ReminderAction werden getrimmt; leere Zeichenketten gelten als nicht angegeben.
Gesucht werden Kunden, bei denen (CustomerNrExternal übereinstimmt oder CeMail mit CustomerEmail übereinstimmt) und CustomerOf = ShopId ist, oder bei denen CustKey übereinstimmt.
Wird kein Kunde oder mehr als ein Kunde gefunden, schlägt der Aufruf fehl.

Prüfungen

ReminderAction muss einer der Werte NONE, PRINT, MAIL, PRINT&MAIL oder 0 sein.
InvoiceDueDays, DaysForFirstReminder, DaysForNextReminder, ReminderDueDays und ReminderCost dürfen nicht negativ sein.

Übernahme der Werte

Ein weggelassener Parameter (NULL) behält den aktuell gespeicherten Wert des Kunden.
Der Wert 0 (bzw. '0' bei ReminderAction) löscht die Einstellung, d. h. sie wird als NULL gespeichert (Option deaktiviert).
Jeder andere Wert überschreibt den gespeicherten Wert.

Zusätzlich werden UpdateDate auf das aktuelle Datum/Uhrzeit und UpdateEmp auf API-CustomerInfoSet gesetzt.

Der Aufruf liefert immer eine Statuszeile mit Status (OK oder ERROR) und StatusMessage.

Hinweise

Alle Prüffehler werden innerhalb eines TRY-Blocks ausgelöst und abgefangen; sie werden als Statuszeile mit Status = ERROR zurückgegeben, nicht als SqlMessage. Gemeldet wird nur die erste fehlgeschlagene Prüfung.
Der Rückgabewert der Prozedur ist 0 bei Erfolg und 1 bei Fehler; SOAP-Clients sollten die Spalte Status auswerten.
Die Kandidatensuche liest Customers mit NOLOCK. Suche und Update laufen nicht in einer expliziten Transaktion.
Stolperfalle: Die Suchbedingungen sind mit OR verknüpft. Wird CustKey zusammen mit ShopId und CustomerNrExternal/CustomerEmail übergeben oder verweisen CustomerNrExternal und CustomerEmail auf verschiedene Kunden, können mehrere Datensätze gefunden werden und der Aufruf scheitert mit "More than one customer found". Für ein eindeutiges Ergebnis nur ein Identifikationsmerkmal übergeben.
ShopId wird im Gegensatz zu den anderen Identifikationsmerkmalen nicht getrimmt.
Bei ReminderAction unterscheiden sich NONE und 0: NONE speichert den Wert NONE, 0 speichert NULL. Ob die Werteprüfung Groß-/Kleinschreibung beachtet, hängt von der Datenbank-Collation ab.
Ein ReminderCost von 0 wird als NULL gespeichert; Mahnkosten von genau null lassen sich daher nicht explizit hinterlegen.

Parameter

Parameter	Typ	Standardwert	Beschreibung
`CustKey`	int	NULL	Interner Pixi-Kundenschlüssel. Identifiziert den Kunden allein; alternativ `ShopId` mit `CustomerNrExternal`/`CustomerEmail` verwenden. Beispiel: `10452`
`CustomerNrExternal`	varchar(60) string	NULL	Externe (Shop-)Kundennummer, abgeglichen mit `CustomerNrExternal` der Kunden von `ShopId`. Wird getrimmt; leer gilt als nicht angegeben. Beispiel: `K-2023-00871`
`CustomerEmail`	varchar(256) string	NULL	E-Mail-Adresse des Kunden, abgeglichen mit `CeMail` der Kunden von `ShopId`. Wird getrimmt; leer gilt als nicht angegeben. Beispiel: `max.mustermann@example.com`
`ShopId`	varchar(3) string	NULL	Shop, zu dem der Kunde gehört (`CustomerOf`). Erforderlich, wenn der Kunde über `CustomerNrExternal` oder `CustomerEmail` identifiziert wird. Beispiel: `SH1`
`InvoiceDueDays`	smallint int	NULL	Zahlungsziel von Rechnungen in Tagen. NULL behält den aktuellen Wert, 0 löscht ihn, negative Werte werden abgelehnt. Beispiel: `14`
`ReminderAction`	varchar(20) string	NULL	Art des Mahnversands an den Kunden. NULL oder leer behält den aktuellen Wert. Erlaubte Werte `NONE` – Es werden keine Mahnungen versendet (Wert NONE wird gespeichert). `PRINT` – Mahnungen werden gedruckt. `MAIL` – Mahnungen werden per E-Mail versendet. `PRINT&MAIL` – Mahnungen werden gedruckt und per E-Mail versendet. `0` – Löscht die Einstellung; NULL wird gespeichert. Beispiel: `MAIL`
`DaysForFirstReminder`	smallint int	NULL	Tage bis zur ersten Mahnung. NULL behält den aktuellen Wert, 0 löscht ihn, negative Werte werden abgelehnt. Beispiel: `7`
`DaysForNextReminder`	smallint int	NULL	Tage bis zur nächsten Mahnung. NULL behält den aktuellen Wert, 0 löscht ihn, negative Werte werden abgelehnt. Beispiel: `10`
`ReminderDueDays`	smallint int	NULL	Zahlungsfrist auf Mahnungen in Tagen. NULL behält den aktuellen Wert, 0 löscht ihn, negative Werte werden abgelehnt. Beispiel: `7`
`ReminderCost`	money decimal	NULL	Mahngebühr pro Mahnung. NULL behält den aktuellen Wert, 0 löscht ihn (als NULL gespeichert), negative Werte werden abgelehnt. Beispiel: `5.00`

Antwort

Result-Set 1 · Immer

Statuszeile mit Erfolg oder dem aufgetretenen Fehler.

Spalte	Typ	Beschreibung
`Status`	varchar(50) string	`OK` bei Erfolg, `ERROR` bei Fehler.
`StatusMessage`	varchar(2000) string	`Record successfully updated` bei Erfolg, sonst die Fehlermeldung.

Beispielantwort

<SqlRowSet1>
  <row>
    <Status>OK</Status>
    <StatusMessage>Record successfully updated</StatusMessage>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
ERROR	To identify a customer record, parameter "CustKey" or one of parameters "CustomerNrExternal"/"CustomerEmail with "ShopId" parameter needs to be provided	Weder `CustKey` noch `ShopId` wurde übergeben, oder `ShopId` ohne `CustKey`, `CustomerNrExternal` oder `CustomerEmail`. `CustKey` oder `ShopId` mit externer Nummer/E-Mail angeben.
ERROR	Allowed reminder actions are: "NONE", "PRINT", "MAIL", "PRINT&MAIL", 0	`ReminderAction` enthält einen nicht zulässigen Wert. Einen der aufgeführten Werte verwenden.
ERROR	Only positive values are allowed for InvoiceDueDays, DaysForFirstReminder, DaysForNextReminder, ReminderDueDays and ReminderCost.	Eine der numerischen Einstellungen ist negativ. Werte von 0 oder größer übergeben.
ERROR	No customer found with provided parameters	Kein Kunde passt zu `CustKey` oder zur Kombination aus `ShopId` und `CustomerNrExternal`/`CustomerEmail`. Identifikationsmerkmale prüfen.
ERROR	More than one customer found with given parameters	Die Identifikationsmerkmale passen auf mehrere Kunden, z. B. doppelte E-Mail-Adressen im Shop oder widersprüchliche, mit OR verknüpfte Merkmale. `CustKey` oder eine eindeutige externe Nummer verwenden.
ERROR	Unexpected error when executing the call	Ersatztext, wenn ein Fehler ohne Fehlermeldung auftritt.

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:pixiCustomerInfoSet>
      <!-- <CustKey>10452</CustKey> -->
      <!-- <CustomerNrExternal>K-2023-00871</CustomerNrExternal> -->
      <!-- <CustomerEmail>max.mustermann@example.com</CustomerEmail> -->
      <!-- <ShopId>SH1</ShopId> -->
      <!-- <InvoiceDueDays>14</InvoiceDueDays> -->
      <!-- <ReminderAction>MAIL</ReminderAction> -->
      <!-- <DaysForFirstReminder>7</DaysForFirstReminder> -->
      <!-- <DaysForNextReminder>10</DaysForNextReminder> -->
      <!-- <ReminderDueDays>7</ReminderDueDays> -->
      <!-- <ReminderCost>5.00</ReminderCost> -->
    </ns1:pixiCustomerInfoSet>
  </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:pixiCustomerInfoSet>
      <!-- <CustKey>10452</CustKey> -->
      <!-- <CustomerNrExternal>K-2023-00871</CustomerNrExternal> -->
      <!-- <CustomerEmail>max.mustermann@example.com</CustomerEmail> -->
      <!-- <ShopId>SH1</ShopId> -->
      <!-- <InvoiceDueDays>14</InvoiceDueDays> -->
      <!-- <ReminderAction>MAIL</ReminderAction> -->
      <!-- <DaysForFirstReminder>7</DaysForFirstReminder> -->
      <!-- <DaysForNextReminder>10</DaysForNextReminder> -->
      <!-- <ReminderDueDays>7</ReminderDueDays> -->
      <!-- <ReminderCost>5.00</ReminderCost> -->
    </ns1:pixiCustomerInfoSet>
  </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' => '10452',
    // 'CustomerNrExternal' => 'K-2023-00871',
    // 'CustomerEmail' => 'max.mustermann@example.com',
    // 'ShopId' => 'SH1',
    // 'InvoiceDueDays' => '14',
    // 'ReminderAction' => 'MAIL',
    // 'DaysForFirstReminder' => '7',
    // 'DaysForNextReminder' => '10',
    // 'ReminderDueDays' => '7',
    // 'ReminderCost' => '5.00',
];

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

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

Verwendete Tabellen

Customers · Schreiben

SQL-Objekt:: dbo.pipiCustomerInfoSet