pixiOrderGetByTags · Pixi API documentation

Searches orders by their assigned tags. The filter is passed as XML in TagFilter.

Parsing and validation

The XML is read from /TagFilter/AND, /TagFilter/OR and /TagFilter/NOT. Each block can contain any number of TagId and TagName elements. Tag names are trimmed, and empty names are ignored.
Each entry is resolved against the tags of type 2 (order tags):
- by Id when TagId is given;
- by exact Name when PartialTagNameMatch = 0;
- by Name LIKE '%…%' when PartialTagNameMatch = 1.
A partial name match can resolve one entry to several tags.
An entry that resolves to no tag gets the status ERROR.
A tag that appears more than once in the resolved list also gets ERROR. This applies across operations and also within the same operation, for example when it is referenced both by Id and by name.
If any entry has an error, the call returns the complete validation list (one row per resolved entry) and no orders.
If the XML cannot be parsed (or a TagId is not numeric), a single error row is returned.

Order search (only if validation passed)

DateFrom defaults to 6 months before now, DateTo to now, and RowCount to 1000.
The date range is turned into a key range. It starts at the smallest OrderHeaderKey with OrderDate >= DateFrom and ends at the largest OrderHeaderKey with OrderDate < DateTo. All orders whose key lies in this range are considered.
NOT: the order must not carry any of the NOT tags.
OR: the order must carry at least one of the OR tags.
AND: the order must carry all of the AND tags.
Blocks that are left empty are not applied. If the filter contains no tags at all (or TagFilter is empty), all orders in the range are returned.
The result is limited to TOP (RowCount) and sorted by OrderHeaderKey ascending.

Notes

All reads use NOLOCK, so uncommitted data may be returned.
StrictANDCondition is marked obsolete and is not used.
The date filter works on the key range, not on OrderDate itself. Orders whose key lies inside the range but whose date is outside it are still returned.
DateTo is exclusive.
If no order matches a date bound, the key range is empty and no rows are returned.
The AND check compares the number of matching tag assignments with the number of AND tags. Duplicate assignments of the same tag to an order could distort it.
With PartialTagNameMatch = 1, every tag matched by the name pattern counts as a separate tag. In AND, this means all matched tags are required.
A code comment notes that the OR condition may not work properly.
The message Tag used in another operation is also set when the same tag is referenced twice within one operation.
Both possible first result sets arrive as SqlRowSet1. Check for the Status column to distinguish the validation list from the order list.
A negative RowCount raises a SQL error outside the error handling.

Tables used

Tag · Read TagMatch · Read OrderHeader · Read

Parameter	Type	Default	Description
`TagFilter` Required	varchar(max) xml	–	XML filter with `AND`, `OR` and `NOT` blocks under `TagFilter`, each containing `TagId` and/or `TagName` elements. Empty value means no tag filter. Example: `<TagFilter> <AND> <TagId>12</TagId> <TagName>Express</TagName> </AND> <OR> <TagId>15</TagId> <TagName>Marketplace</TagName> </OR> <NOT> <TagId>7</TagId> <TagName>Blocked</TagName> </NOT> </TagFilter>`
`PartialTagNameMatch`	bit boolean	0	Controls how `TagName` entries are matched. Allowed values `0` – Tag name must match exactly `1` – Tag name is matched as substring (`LIKE '%name%'`) Example: `0`
`StrictANDCondition`	bit boolean	0	Obsolete, not used. Example: `0`
`RowCount`	int	1000	Maximum number of orders returned. NULL is treated as 1000. Example: `500`
`DateFrom`	datetime dateTime	NULL	Start of the order date range (inclusive). NULL means 6 months before now. Example: `2024-01-01T00:00:00`
`DateTo`	datetime dateTime	NULL	End of the order date range (exclusive). NULL means now. Example: `2024-07-01T00:00:00`

Result set 1 · If at least one filter entry fails validation or the XML cannot be parsed; no order list follows

Validation list of all resolved filter entries. On a parse error, a single row with NULL values and an error message is returned.

Column	Type	Description
`Operation` Nullable	varchar(3) string	Filter operation: `AND`, `OR` or `NOT`
`XMLTagId` Nullable	nvarchar(1024) string	TagId as given in the XML
`XMLTagName` Nullable	nvarchar(1024) string	TagName as given in the XML (trimmed)
`TagId` Nullable	int	Id of the resolved tag, NULL if not found
`TagName` Nullable	varchar(50) string	Name of the resolved tag
`Status`	varchar(10) string	`OK` or `ERROR`
`StatusMessage`	varchar(100) string	Match or error description, e.g. `Complete match on TagId`, `Complete match on TagName`, `Partial match on TagName` or an error message

Result set 2 · If validation succeeded

Matching orders, at most RowCount rows, sorted by order key ascending.

Column	Type	Description
`OrderHeaderId`	int	Internal order key (`OrderHeaderKey`)
`OrderNr` Nullable	string	Pixi order number
`OrderNrExternal` Nullable	string	External order number (e.g. from the shop)

Response example

<SqlRowSet1>
  <row>
    <Operation>AND</Operation>
    <XMLTagId>12</XMLTagId>
    <TagId>12</TagId>
    <TagName>Priority</TagName>
    <Status>ERROR</Status>
    <StatusMessage>Tag used in another operation</StatusMessage>
  </row>
  <row>
    <Operation>NOT</Operation>
    <XMLTagName>Blocked</XMLTagName>
    <Status>ERROR</Status>
    <StatusMessage>TagId or TagName not found</StatusMessage>
  </row>
</SqlRowSet1>

Status	Message	Cause
ERROR	TagId or TagName not found	A `TagId` or `TagName` in the filter does not match any tag of type 2. Check the tag id or name, or use `PartialTagNameMatch` = 1.
ERROR	Tag used in another operation	The same tag is resolved more than once, e.g. in two operations, by Id and by name, or through overlapping partial name matches. Reference each tag only once.
ERROR	Unexpected error occured while parsing the @TagFilter parameter	`TagFilter` is not valid XML or a `TagId` value cannot be converted to a number. Send well-formed XML with numeric tag ids.

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:pixiOrderGetByTags>
      <TagFilter><![CDATA[<TagFilter><AND><TagId>12</TagId><TagName>Express</TagName></AND><OR><TagId>15</TagId><TagName>Marketplace</TagName></OR><NOT><TagId>7</TagId><TagName>Blocked</TagName></NOT></TagFilter>]]></TagFilter>
      <!-- <PartialTagNameMatch>0</PartialTagNameMatch> -->
      <!-- <StrictANDCondition>0</StrictANDCondition> -->
      <!-- <RowCount>500</RowCount> -->
      <!-- <DateFrom>2024-01-01T00:00:00</DateFrom> -->
      <!-- <DateTo>2024-07-01T00:00:00</DateTo> -->
    </ns1:pixiOrderGetByTags>
  </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:pixiOrderGetByTags>
      <TagFilter><![CDATA[<TagFilter><AND><TagId>12</TagId><TagName>Express</TagName></AND><OR><TagId>15</TagId><TagName>Marketplace</TagName></OR><NOT><TagId>7</TagId><TagName>Blocked</TagName></NOT></TagFilter>]]></TagFilter>
      <!-- <PartialTagNameMatch>0</PartialTagNameMatch> -->
      <!-- <StrictANDCondition>0</StrictANDCondition> -->
      <!-- <RowCount>500</RowCount> -->
      <!-- <DateFrom>2024-01-01T00:00:00</DateFrom> -->
      <!-- <DateTo>2024-07-01T00:00:00</DateTo> -->
    </ns1:pixiOrderGetByTags>
  </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 = [
    'TagFilter' => '<TagFilter><AND><TagId>12</TagId><TagName>Express</TagName></AND><OR><TagId>15</TagId><TagName>Marketplace</TagName></OR><NOT><TagId>7</TagId><TagName>Blocked</TagName></NOT></TagFilter>',
    // 'PartialTagNameMatch' => '0',
    // 'StrictANDCondition' => '0',
    // 'RowCount' => '500',
    // 'DateFrom' => '2024-01-01T00:00:00',
    // 'DateTo' => '2024-07-01T00:00:00',
];

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

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