pixiTagCreate · Pixi API documentation

Creates a tag record in Pixi. Tags are used to label items or orders. The call returns one status row with Status and Message.

Steps:

Validation. TypeID must refer to an existing tag type and Name must not be empty. If validation fails, no tag is created and Status is Error. The checks are evaluated in this order:
- both TypeID and Name missing
- TypeID missing
- no tag type with this TypeID exists
- Name empty
Duplicate check. The call counts the existing tags with the same TypeID and Name. If at least one exists, nothing is inserted and Status is Information.
Insert. Otherwise a new tag is inserted with:
- the given type and name
- Description; NULL is stored as an empty string
- IsSystemTag = 0
Status is then Success.

The ID of the new tag is not returned.

Notes

Transactions: the call runs inside its own transaction. If it is called within an existing transaction, it uses a savepoint instead. XACT_ABORT is on.
Error handling: on an unexpected error the transaction is rolled back and the error is logged via log.InsertError (definition not attached). A status row with Status = Error is still returned; no SQL error is raised.
Duplicates: the tag type and duplicate checks read with NOLOCK. Concurrent calls with the same type and name may therefore both insert a tag, unless a unique constraint on Tag prevents this; such a constraint is not visible in the code.
Name matching: whether names are compared case-sensitively depends on the database collation.
Message text: in the 'already exists' message the name is cut to 20 characters.
Tag ID: the call does not return the ID of the new tag. It has to be read separately.

Tables used

TagType · Read Tag · Write

Parameter	Type	Default	Description
`TypeID`	int	NULL	ID of the tag type (`TagType.Id`). Effectively mandatory; it must refer to an existing tag type. Example: `1`
`Name`	varchar(50) string	NULL	Name of the new tag. Effectively mandatory; must not be empty. Together with `TypeID` it must be unique, otherwise no tag is created. Example: `Express`
`Description`	varchar(4000) string	–	Optional description of the tag. `NULL` is stored as an empty string. Example: `Orders to be shipped with express delivery`

Result set 1 · Always

One status row with the outcome of the call.

Column	Type	Description
`Status`	varchar(254) string	Outcome of the call: `Success` (tag created), `Information` (tag already exists) or `Error` (validation or unexpected error).
`Message` Nullable	varchar(2000) string	Text describing the outcome or the error.

Response example

<SqlRowSet1>
  <row>
    <Status>Success</Status>
    <Message>New tag was successfully created</Message>
  </row>
</SqlRowSet1>

Status	Message	Cause
Error	Mandatory parameters TypeID and Name are missing	Neither `TypeID` nor `Name` was passed. Pass both parameters.
Error	Mandatory parameter TypeID is missing	`TypeID` was not passed. Pass the ID of an existing tag type.
Error	Tag type with TypeID: {TypeID} does not exist	No tag type with the given `TypeID` exists. Use a valid tag type ID.
Error	Mandatory parameter Name is missing	`Name` is missing or empty. Pass a non-empty tag name.
Information	Tag with TypeID({TypeID}) and TagName({Name}) already exists	A tag with the same type and name already exists; nothing was inserted. The name in the message is cut to 20 characters.
Error	Unexpected error: "{error message}"	An unexpected SQL error occurred, for example a constraint violation. The transaction is rolled back and the error is logged. The error text is cut to 80 characters.

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:pixiTagCreate>
      <!-- <TypeID>1</TypeID> -->
      <!-- <Name>Express</Name> -->
      <!-- <Description>Orders to be shipped with express delivery</Description> -->
    </ns1:pixiTagCreate>
  </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:pixiTagCreate>
      <!-- <TypeID>1</TypeID> -->
      <!-- <Name>Express</Name> -->
      <!-- <Description>Orders to be shipped with express delivery</Description> -->
    </ns1:pixiTagCreate>
  </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 = [
    // 'TypeID' => '1',
    // 'Name' => 'Express',
    // 'Description' => 'Orders to be shipped with express delivery',
];

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

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