Orders Schreiben

pixiTagMatchAddForOrders

Ordnet Aufträgen ein oder mehrere Tags zu, die als XML übergeben werden, und liefert je Tag/Auftrag-Paar eine Statuszeile.

Legt Tag-Zuordnungen (TagMatch-Einträge) zwischen Tags und Aufträgen an.

Das XML in TagsXML wird elementbasiert entlang /Tags/Order/TagList/Tag ausgelesen. Jedes Tag-Element ergibt einen Kandidaten. Dessen TagId wird mit OrderId und OrderNrExternal aus dem umgebenden Order-Element kombiniert. Die Werte 0 und leere Zeichenketten gelten als nicht angegeben.
Der Auftrag wird über OrderHeader ermittelt:
- OrderId wird mit OrderHeader.OrderNr abgeglichen.
- OrderNrExternal wird mit OrderHeader.OrderNrExternal abgeglichen.
- Sind beide angegeben, hat die Auftragsnummer (OrderId) Vorrang.
Jeder Kandidat wird geprüft:
- Keine TagId oder weder Auftragsnummer noch externe Auftragsnummer: Mandatory parameter is missing.
- Der Auftrag wird nicht gefunden, oder der Tag existiert nicht als Auftrags-Tag (Tag.TypeId = 2): One of the provided values is not valid.
- Der Tag ist dem Auftrag bereits zugeordnet: Warnung Tag is already assigned to that order.
Alle übrigen Kandidaten werden in TagMatch (TagId, OrderHeaderId) eingefügt. Doppelte Paare im XML werden nur einmal geschrieben.

Der Aufruf liefert je verarbeitetem Kandidaten eine Zeile, in der Reihenfolge der Tag-Elemente im XML. Jede Zeile enthält Status und Meldung.

Hinweise

Der Aufruf läuft in einer eigenen Transaktion. Wird er innerhalb einer bestehenden Transaktion aufgerufen, verwendet er stattdessen einen Savepoint.
Die Abfragen auf OrderHeader, Tag und TagMatch verwenden NOLOCK.
Bei einem unerwarteten Fehler (z. B. ungültiges XML) setzt der CATCH-Block die Transaktion zurück und protokolliert den Fehler über log.InsertError. In diesem Fall wird keine Ergebnismenge geliefert. Die interne Meldung Unexpected error: ... wird zwar erzeugt, aber nie ausgegeben.
Es werden nur Tags mit TypeId = 2 (Auftrags-Tags) akzeptiert.
Passt eine OrderNrExternal auf mehrere Aufträge, kann ein Kandidat mehrere Ergebniszeilen erzeugen.
Wird TagsXML weggelassen (NULL) oder enthält es keine Tag-Elemente, wird nichts zugeordnet.

Parameter

Parameter Typ Standardwert Beschreibung

Parameter	Typ	Standardwert	Beschreibung
`TagsXML`	varchar(max) xml	NULL	XML mit Aufträgen und den zuzuordnenden Tags. Jedes `Order`-Element bestimmt den Auftrag über `OrderId` (Pixi-Auftragsnummer) oder `OrderNrExternal`. Seine `TagList` enthält `Tag`-Elemente mit je einer `TagId`. Beispiel: `<Tags> <Order> <OrderId>123456</OrderId> <OrderNrExternal/> <TagList> <Tag> <TagId>12</TagId> </Tag> <Tag> <TagId>15</TagId> </Tag> </TagList> </Order> <Order> <OrderId>0</OrderId> <OrderNrExternal>SHOP-100045</OrderNrExternal> <TagList> <Tag> <TagId>12</TagId> </Tag> </TagList> </Order> </Tags>`

TagsXML

varchar(max)
xml

NULL

XML mit Aufträgen und den zuzuordnenden Tags. Jedes Order-Element bestimmt den Auftrag über OrderId (Pixi-Auftragsnummer) oder OrderNrExternal. Seine TagList enthält Tag-Elemente mit je einer TagId.

Beispiel:

<Tags>
  <Order>
    <OrderId>123456</OrderId>
    <OrderNrExternal/>
    <TagList>
      <Tag>
        <TagId>12</TagId>
      </Tag>
      <Tag>
        <TagId>15</TagId>
      </Tag>
    </TagList>
  </Order>
  <Order>
    <OrderId>0</OrderId>
    <OrderNrExternal>SHOP-100045</OrderNrExternal>
    <TagList>
      <Tag>
        <TagId>12</TagId>
      </Tag>
    </TagList>
  </Order>
</Tags>

Antwort

Result-Set 1 · Bei erfolgreicher Ausführung (bei unerwartetem Fehler nicht geliefert)

Eine Statuszeile je Tag/Auftrag-Kandidat, sortiert nach der Position des Tag-Elements im XML.

Spalte	Typ	Beschreibung
`TagId` Kann leer sein	int	Tag-ID aus dem XML.
`OrderId` Kann leer sein	int	Pixi-Auftragsnummer (`OrderNr`), aus dem XML übernommen oder über `OrderNrExternal` ermittelt.
`OrderNrExternal` Kann leer sein	varchar(50) string	Externe Auftragsnummer aus dem XML.
`OrderHeaderKey` Kann leer sein	int	Interner Schlüssel des ermittelten Auftrags; leer, wenn der Auftrag nicht gefunden wurde.
`Status`	varchar(254) string	`Success`, `Warning` oder `Error`.
`Message`	varchar(2000) string	Ergebnismeldung für diesen Kandidaten.

Beispielantwort

<SqlRowSet1>
  <row>
    <TagId>12</TagId>
    <OrderId>123456</OrderId>
    <OrderHeaderKey>98765</OrderHeaderKey>
    <Status>Success</Status>
    <Message>Tag was successfully assigned to order</Message>
  </row>
  <row>
    <TagId>12</TagId>
    <OrderNrExternal>SHOP-100045</OrderNrExternal>
    <Status>Error</Status>
    <Message>One of the provided values is not valid</Message>
  </row>
</SqlRowSet1>

Fehlermeldungen

Status	Meldung	Ursache
Error	Mandatory parameter is missing	Das `Tag`-Element hat keine `TagId` (oder `0`), oder der Auftrag hat weder `OrderId` noch `OrderNrExternal`. Sowohl Tag als auch Auftragsreferenz angeben.
Error	One of the provided values is not valid	Der Auftrag wird über `OrderId` bzw. `OrderNrExternal` nicht gefunden, oder die `TagId` existiert nicht als Auftrags-Tag (`TypeId = 2`).
Warning	Tag is already assigned to that order	Für diesen Tag und Auftrag existiert bereits ein `TagMatch`-Eintrag; es wird nichts eingefügt.
Error	Something went wrong, an undefined error occurred	Ersatzmeldung für ein unbestimmtes Prüfergebnis; praktisch nicht erreicht.

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:pixiTagMatchAddForOrders>
      <!-- <TagsXML><![CDATA[<Tags><Order><OrderId>123456</OrderId><OrderNrExternal></OrderNrExternal><TagList><Tag><TagId>12</TagId></Tag><Tag><TagId>15</TagId></Tag></TagList></Order><Order><OrderId>0</OrderId><OrderNrExternal>SHOP-100045</OrderNrExternal><TagList><Tag><TagId>12</TagId></Tag></TagList></Order></Tags>]]></TagsXML> -->
    </ns1:pixiTagMatchAddForOrders>
  </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:pixiTagMatchAddForOrders>
      <!-- <TagsXML><![CDATA[<Tags><Order><OrderId>123456</OrderId><OrderNrExternal></OrderNrExternal><TagList><Tag><TagId>12</TagId></Tag><Tag><TagId>15</TagId></Tag></TagList></Order><Order><OrderId>0</OrderId><OrderNrExternal>SHOP-100045</OrderNrExternal><TagList><Tag><TagId>12</TagId></Tag></TagList></Order></Tags>]]></TagsXML> -->
    </ns1:pixiTagMatchAddForOrders>
  </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 = [
    // 'TagsXML' => '<Tags><Order><OrderId>123456</OrderId><OrderNrExternal></OrderNrExternal><TagList><Tag><TagId>12</TagId></Tag><Tag><TagId>15</TagId></Tag></TagList></Order><Order><OrderId>0</OrderId><OrderNrExternal>SHOP-100045</OrderNrExternal><TagList><Tag><TagId>12</TagId></Tag></TagList></Order></Tags>',
];

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

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

Verwendete Tabellen

OrderHeader · Lesen Tag · Lesen TagMatch · Schreiben

SQL-Objekt:: dbo.pipiTagMatchAddForOrders