pixiTagMatchAddForOrders · Pixi API documentation

Creates tag assignments (TagMatch entries) between tags and orders.

The XML in TagsXML is parsed element-centric along /Tags/Order/TagList/Tag. Every Tag element becomes one candidate. Its TagId is combined with OrderId and OrderNrExternal from the enclosing Order element. The values 0 and empty strings are treated as missing.
The order is resolved via OrderHeader:
- OrderId is matched against OrderHeader.OrderNr.
- OrderNrExternal is matched against OrderHeader.OrderNrExternal.
- If both are given, the order number (OrderId) takes precedence.
Each candidate is validated:
- No TagId, or neither an order number nor an external order number: Mandatory parameter is missing.
- The order cannot be found, or the tag does not exist as an order tag (Tag.TypeId = 2): One of the provided values is not valid.
- The tag is already assigned to the order: warning Tag is already assigned to that order.
All remaining candidates are inserted into TagMatch (TagId, OrderHeaderId). Duplicate pairs in the XML are written only once.

The call returns one row per processed candidate, in the order of the Tag elements in the XML. Each row carries the status and the message.

Notes

The call runs in its own transaction. If it is called inside an existing transaction, it uses a savepoint instead.
Lookups on OrderHeader, Tag and TagMatch use NOLOCK.
If an unexpected error occurs (for example invalid XML), the CATCH block rolls the transaction back and logs the error via log.InsertError. No result set is returned in that case. The internal message Unexpected error: ... is built but never selected.
Only tags with TypeId = 2 (order tags) are accepted.
If an OrderNrExternal matches several orders, one candidate can produce several result rows.
If TagsXML is omitted (NULL) or contains no Tag elements, nothing is assigned.

Tables used

OrderHeader · Read Tag · Read TagMatch · Write

Parameter Type Default Description

Parameter	Type	Default	Description
`TagsXML`	varchar(max) xml	NULL	XML with orders and the tags to assign. Each `Order` element identifies the order by `OrderId` (Pixi order number) or `OrderNrExternal`. Its `TagList` holds `Tag` elements, each with a `TagId`. Example: `<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 with orders and the tags to assign. Each Order element identifies the order by OrderId (Pixi order number) or OrderNrExternal. Its TagList holds Tag elements, each with a TagId.

Example:

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

Result set 1 · On successful execution (not returned if an unexpected error occurs)

One status row per tag/order candidate, ordered by the position of the Tag element in the XML.

Column	Type	Description
`TagId` Nullable	int	Tag ID from the XML.
`OrderId` Nullable	int	Pixi order number (`OrderNr`), taken from the XML or resolved via `OrderNrExternal`.
`OrderNrExternal` Nullable	varchar(50) string	External order number from the XML.
`OrderHeaderKey` Nullable	int	Internal key of the resolved order; empty if the order was not found.
`Status`	varchar(254) string	`Success`, `Warning` or `Error`.
`Message`	varchar(2000) string	Result message for this candidate.

Response example

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

Status	Message	Cause
Error	Mandatory parameter is missing	The `Tag` element has no `TagId` (or `0`), or the order has neither `OrderId` nor `OrderNrExternal`. Provide both a tag and an order reference.
Error	One of the provided values is not valid	The order cannot be found by `OrderId` or `OrderNrExternal`, or the `TagId` does not exist as an order tag (`TypeId = 2`).
Warning	Tag is already assigned to that order	A `TagMatch` entry for this tag and order already exists; nothing is inserted.
Error	Something went wrong, an undefined error occurred	Fallback message for an undetermined validation result; practically not reached.

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