pixiImportAddXML

Hands an import document over to Pixi's new import mechanism by writing it into the XML log.

If ParameterXML is not empty, its content replaces XML. An empty OperationType or XML is treated as NULL.
OperationType is compared case-insensitively:
- order resolves to the operation type OrderImport
- item resolves to the operation type ItemImport
- any other value, including NULL, is rejected. The operation type key is read from C_OperationTypes.
ChannelRef is looked up in C_Channels.
The input is then checked in this order: channel is NULL, operation type unknown, XML missing. The first failed check returns a single row with ErrorNr = 500 and ErrorMsg.
If all checks pass, the XML is written to C_XMLLog with Source = API, Status = XIM, user API, the resolved operation type and the channel. The text is cleaned up and converted to the XML data type. If the conversion fails, the raw text is stored together with the conversion error number and message. The call does not report this as an error.
The call returns the key of the new log entry. It does not import the order or item itself. That happens later in the import processing, which is not part of this call.

Notes

Two result sets on success: the internal procedure Pixi_C_InsertXML already returns the new key as XMLLogKey (SqlRowSet1). The call then returns the same value again as XMLKey (SqlRowSet2). On error only one row (ErrorNr/ErrorMsg) is returned, in SqlRowSet1.
Channel check is weak: if ChannelRef does not exist in C_Channels, the variable keeps the value that was passed. The error Channel not defined therefore only occurs when ChannelRef is explicitly NULL. A non-existent channel, including the default 0, is stored without an error.
If order or item is passed but the matching row (OrderImport/ItemImport) is missing in C_OperationTypes, the operation type stays NULL. The entry is then stored with an empty operation type instead of being rejected.
Invalid XML is not rejected. A failed XML conversion is only recorded in the log columns XmlResponseCastErrorNr/XmlResponseCastErrorMessage. Check the XML before sending it.
The XML is cleaned by fPixi_CleanupXmlText, whose definition is not attached.
No explicit transaction is used. The lookups in C_OperationTypes and C_Channels use NOLOCK.
Send the XML document escaped (or as CDATA) inside the SOAP element, because the parameter is a varchar(max) string.

Tables used

C_OperationTypes · Read C_Channels · Read C_XMLLog · Write

Parameter	Type	Default	Description
`ChannelRef`	int	0	Key of the channel (`C_Channels.ChannelKey`) the import belongs to. Only an explicit `NULL` is rejected; unknown keys are stored as passed. Example: `1`
`OperationType`	varchar(20) string	NULL	Kind of import, compared case-insensitively. Any value other than `ORDER` or `ITEM` returns an error. Allowed values `ORDER` – Order import (operation type `OrderImport`). `ITEM` – Item import (operation type `ItemImport`). Example: `ORDER`
`XML`	varchar(max) xml	NULL	The import document as text, for example an order or a BMEcat item document. It is ignored if `ParameterXML` is filled. If it is empty or missing, the call returns an error. Example: `<ORDER version="1.0" type="standard"> <ORDER_HEADER> <ORDER_INFO> <ORDER_ID>100045</ORDER_ID> <ORDER_DATE>2024-03-15T10:22:00</ORDER_DATE> </ORDER_INFO> </ORDER_HEADER> <ORDER_ITEM_LIST> <ORDER_ITEM> <LINE_ITEM_ID>1</LINE_ITEM_ID> <ARTICLE_ID> <SUPPLIER_AID>4711</SUPPLIER_AID> </ARTICLE_ID> <QUANTITY>2</QUANTITY> </ORDER_ITEM> </ORDER_ITEM_LIST> </ORDER>`
`ParameterXML`	varchar(max) xml	NULL	Alternative to `XML`. If not empty, it replaces the content of `XML`. Example: `<BMECAT version="2005"> <HEADER> <CATALOG> <LANGUAGE>deu</LANGUAGE> <CATALOG_ID>SHOP1</CATALOG_ID> <CATALOG_VERSION>1.0</CATALOG_VERSION> </CATALOG> </HEADER> <T_NEW_CATALOG> <PRODUCT> <SUPPLIER_PID>4711</SUPPLIER_PID> <PRODUCT_DETAILS> <DESCRIPTION_SHORT>Beispielartikel</DESCRIPTION_SHORT> </PRODUCT_DETAILS> </PRODUCT> </T_NEW_CATALOG> </BMECAT>`

Result set 1 · On success (first result set, returned by the internal procedure `Pixi_C_InsertXML`)

Key of the new entry in C_XMLLog.

Column	Type	Description
`XMLLogKey` Nullable	int	Identity value of the new XML log entry.

Result set 2 · On success (second result set)

Same key again, returned by the call itself.

Column	Type	Description
`XMLKey` Nullable	int	Key of the new XML log entry (return value of `Pixi_C_InsertXML`).

Result set 3 · Instead of the success result sets, if a validation check fails or an exception occurs while storing

Single error row.

Column	Type	Description
`ErrorNr` Nullable	int	500 for validation errors, otherwise the SQL error number.
`ErrorMsg` Nullable	nvarchar(4000) string	Error text.

Response example

<SqlRowSet1>
  <row>
    <XMLLogKey>58231</XMLLogKey>
  </row>
</SqlRowSet1>

Status	Message	Cause
500	Channel not defined	`ChannelRef` was passed as `NULL`. Pass a valid channel key.
500	Operation type not found. Please use either ITEM or ORDER	`OperationType` is missing, empty or not `ITEM`/`ORDER`.
500	XML was not set	Both `XML` and `ParameterXML` are empty or missing.
{ERROR_NUMBER}	{ERROR_MESSAGE}	An unexpected SQL error occurred while writing the XML log entry. A failed XML conversion does not cause this error.

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:pixiImportAddXML>
      <!-- <ChannelRef>1</ChannelRef> -->
      <!-- <OperationType>ORDER</OperationType> -->
      <!-- <XML><![CDATA[<?xml version="1.0" encoding="UTF-8"?><ORDER version="1.0" type="standard"><ORDER_HEADER><ORDER_INFO><ORDER_ID>100045</ORDER_ID><ORDER_DATE>2024-03-15T10:22:00</ORDER_DATE></ORDER_INFO></ORDER_HEADER><ORDER_ITEM_LIST><ORDER_ITEM><LINE_ITEM_ID>1</LINE_ITEM_ID><ARTICLE_ID><SUPPLIER_AID>4711</SUPPLIER_AID></ARTICLE_ID><QUANTITY>2</QUANTITY></ORDER_ITEM></ORDER_ITEM_LIST></ORDER>]]></XML> -->
      <!-- <ParameterXML><![CDATA[<?xml version="1.0" encoding="UTF-8"?><BMECAT version="2005"><HEADER><CATALOG><LANGUAGE>deu</LANGUAGE><CATALOG_ID>SHOP1</CATALOG_ID><CATALOG_VERSION>1.0</CATALOG_VERSION></CATALOG></HEADER><T_NEW_CATALOG><PRODUCT><SUPPLIER_PID>4711</SUPPLIER_PID><PRODUCT_DETAILS><DESCRIPTION_SHORT>Beispielartikel</DESCRIPTION_SHORT></PRODUCT_DETAILS></PRODUCT></T_NEW_CATALOG></BMECAT>]]></ParameterXML> -->
    </ns1:pixiImportAddXML>
  </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:pixiImportAddXML>
      <!-- <ChannelRef>1</ChannelRef> -->
      <!-- <OperationType>ORDER</OperationType> -->
      <!-- <XML><![CDATA[<?xml version="1.0" encoding="UTF-8"?><ORDER version="1.0" type="standard"><ORDER_HEADER><ORDER_INFO><ORDER_ID>100045</ORDER_ID><ORDER_DATE>2024-03-15T10:22:00</ORDER_DATE></ORDER_INFO></ORDER_HEADER><ORDER_ITEM_LIST><ORDER_ITEM><LINE_ITEM_ID>1</LINE_ITEM_ID><ARTICLE_ID><SUPPLIER_AID>4711</SUPPLIER_AID></ARTICLE_ID><QUANTITY>2</QUANTITY></ORDER_ITEM></ORDER_ITEM_LIST></ORDER>]]></XML> -->
      <!-- <ParameterXML><![CDATA[<?xml version="1.0" encoding="UTF-8"?><BMECAT version="2005"><HEADER><CATALOG><LANGUAGE>deu</LANGUAGE><CATALOG_ID>SHOP1</CATALOG_ID><CATALOG_VERSION>1.0</CATALOG_VERSION></CATALOG></HEADER><T_NEW_CATALOG><PRODUCT><SUPPLIER_PID>4711</SUPPLIER_PID><PRODUCT_DETAILS><DESCRIPTION_SHORT>Beispielartikel</DESCRIPTION_SHORT></PRODUCT_DETAILS></PRODUCT></T_NEW_CATALOG></BMECAT>]]></ParameterXML> -->
    </ns1:pixiImportAddXML>
  </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 = [
    // 'ChannelRef' => '1',
    // 'OperationType' => 'ORDER',
    // 'XML' => '<?xml version="1.0" encoding="UTF-8"?><ORDER version="1.0" type="standard"><ORDER_HEADER><ORDER_INFO><ORDER_ID>100045</ORDER_ID><ORDER_DATE>2024-03-15T10:22:00</ORDER_DATE></ORDER_INFO></ORDER_HEADER><ORDER_ITEM_LIST><ORDER_ITEM><LINE_ITEM_ID>1</LINE_ITEM_ID><ARTICLE_ID><SUPPLIER_AID>4711</SUPPLIER_AID></ARTICLE_ID><QUANTITY>2</QUANTITY></ORDER_ITEM></ORDER_ITEM_LIST></ORDER>',
    // 'ParameterXML' => '<?xml version="1.0" encoding="UTF-8"?><BMECAT version="2005"><HEADER><CATALOG><LANGUAGE>deu</LANGUAGE><CATALOG_ID>SHOP1</CATALOG_ID><CATALOG_VERSION>1.0</CATALOG_VERSION></CATALOG></HEADER><T_NEW_CATALOG><PRODUCT><SUPPLIER_PID>4711</SUPPLIER_PID><PRODUCT_DETAILS><DESCRIPTION_SHORT>Beispielartikel</DESCRIPTION_SHORT></PRODUCT_DETAILS></PRODUCT></T_NEW_CATALOG></BMECAT>',
];

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

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