pixiSetItemSupplier · Pixi API documentation

Maintains the supplier data of an item in AddItems for the supplier given in SupplNr.

Validation

ItemKey = 0 and empty strings in EAN, ItemNrSuppl and ItemNrInt are treated as NULL.
If both ItemKey and ItemNrInt are passed, they must belong to the same item in items.
The supplier SupplNr must exist in Suppliers.
At least one of ItemKey, EAN, ItemNrSuppl or ItemNrInt must be passed.

Identifying the item The item is searched in the existing AddItems rows (joined with items). A row matches if any of these is true:

ItemRef = ItemKey
EANUPC = EAN
ItemNrInt = ItemNrInt
ItemNrSuppl = ItemNrSuppl and SupplNr = SupplNr

Exactly one distinct item must be found; otherwise an error row is returned.

With AddEAN = 0, it is an error if more than one matching AddItems row exists for the given supplier.
With AddEAN = 1, a warning is returned if a row with the same EAN and supplier already exists.

Writing

If PreferredSupplier = 1, PreferredSupplier is first reset to 0 on all AddItems rows of the item, so only one row stays preferred.
If AddEAN = 0 and a matching AddItems row of that supplier exists, the oldest one (lowest UpdateDate) is updated. Parameters that are not passed keep the existing values; for price, supplier item number and EAN the item master values are used as fallback. The call returns Record updated.
Otherwise (no row for this supplier yet, or AddEAN = 1), a new AddItems row is inserted. Values come from the parameters, with fallback to the item master (EANUPC, ItemNrSuppl, SupplPrice). ItemNrInt, IntLinkNR1, IntLinkNR and Price are copied from the item, and AutoPrice is set to 0. The call returns New record inserted.

The call always returns exactly one status row with Status and Message.

Notes

The item must already have at least one AddItems row. The lookup only searches AddItems, so an item without any supplier row returns No items found with given parameters., even if ItemKey is valid.
With AddEAN = 1 and a new EAN, the item can only be identified through an existing value. Pass ItemKey or ItemNrInt, because the new EAN cannot be found in AddItems yet.
The search conditions are combined with OR. Passing several identifiers that point to different items leads to More then one item was identified ....
When a new row is inserted, MinOrderQty and SupplDeliveryTime take only the passed values (NULL if omitted). OrderOnlyPackageUnits and PreferredSupplier default to 0.
In the success message, NULL values are not handled. If the resulting ItemNrSuppl or EANUPC is NULL, Message is NULL.
Writes run in a transaction. If the caller already has an open transaction, a savepoint is used instead. On error the changes are rolled back, the error is logged via log.InsertError (definition not attached) and an Error row with the SQL error text is returned.
Reads use NOLOCK; updates use ROWLOCK.

Tables used

items · Read Suppliers · Read AddItems · Write

Parameter	Type	Default	Description
`ItemKey`	int	NULL	Internal key of the item (`items.ItemKey`). 0 is treated as NULL. Example: `10452`
`ItemNrInt`	varchar(50) string	NULL	Internal item number. If `ItemKey` is also passed, both must belong to the same item. Empty string is treated as NULL. Example: `ART-100245`
`SupplNr` Required	varchar(4) string	–	Supplier number. It must exist in `Suppliers` and determines which `AddItems` row is updated or created. Example: `L001`
`SupplPrice`	money decimal	NULL	Purchase price at the supplier. If omitted, the existing value is kept; for a new row the item master price is used. Example: `12.50`
`EAN`	varchar(13) string	NULL	EAN/UPC. It is used to find the item and is stored in `AddItems.EANUPC`. Empty string is treated as NULL. Example: `4006381333931`
`ItemNrSuppl`	varchar(50) string	NULL	Supplier's item number. It is used for the lookup only together with `SupplNr` and is stored in `AddItems.ItemNrSuppl`. Empty string is treated as NULL. Example: `LF-4711`
`AddEAN`	bit boolean	0	If 1, a new `AddItems` row is always inserted (e.g. for an additional EAN) instead of updating an existing one. Allowed values `0` – Update the existing row of the supplier, or insert one if none exists. `1` – Insert a new row. Returns a warning if the same EAN already exists for this supplier. Example: `0`
`PreferredSupplier`	smallint int	NULL	Preferred supplier flag. With 1, all other `AddItems` rows of the item are reset to 0. If omitted, the existing value is kept on update; a new row gets 0. Allowed values `1` – Mark as preferred supplier and reset the flag on all other rows of the item. `0` – Not preferred; other rows are not changed. Example: `1`
`MinOrderQty`	int	NULL	Minimum order quantity at the supplier. If omitted, the existing value is kept; a new row gets NULL. Example: `10`
`OnlyPU`	bit boolean	NULL	Order only in package units (`OrderOnlyPackageUnits`). If omitted, the existing value is kept; a new row gets 0. Example: `0`
`ItemDeliveryTime`	int	NULL	Supplier delivery time (`SupplDeliveryTime`). If omitted, the existing value is kept; a new row gets NULL. Example: `5`

Result set 1 · Always; exactly one status row (error, warning, update or insert result).

Status row describing the outcome of the call.

Column	Type	Description
`Status`	varchar(19) string	`Error`, `Warning`, `Record updated` or `New record inserted`.
`Message` Nullable	varchar string	Error text, or on success the stored values in the format `SupplPrice:… ItemNrSuppl:… EANUPC:…`. It is NULL if one of the concatenated values is NULL.

Response example

<SqlRowSet1>
  <row>
    <Status>Record updated</Status>
    <Message>SupplPrice:12.50 ItemNrSuppl:LF-4711 EANUPC:4006381333931</Message>
  </row>
</SqlRowSet1>

Status	Message	Cause
Error	ItemNrInt {ItemNrInt} not match to ItemKey {ItemKey}	`ItemKey` and `ItemNrInt` were both passed but do not belong to the same item. Pass only one of them or correct the values.
Error	Supplier with SupplNr:{SupplNr} does not exist.	No supplier with the given `SupplNr` exists in `Suppliers`.
Error	Please specify at least one parameter.	None of `ItemKey`, `EAN`, `ItemNrSuppl`, `ItemNrInt` was passed.
Error	More then one item was identified with the given parameters.	The identifiers match several items, or (with `AddEAN = 0`) several `AddItems` rows of the same supplier. Use a more specific identifier such as `ItemKey`.
Warning	Item with EANUPC: {EAN} and Supplier number "{SupplNr}" already exists.	With `AddEAN = 1`, an `AddItems` row with this EAN and supplier already exists, so nothing is inserted.
Error	No items found with given parameters.	No `AddItems` row matches the identifiers. This also happens if the item exists but has no `AddItems` row yet.
Error	{ERROR_MESSAGE()}	A SQL error occurred while updating or inserting. The transaction is rolled back and the error is logged.

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:pixiSetItemSupplier>
      <!-- <ItemKey>10452</ItemKey> -->
      <!-- <ItemNrInt>ART-100245</ItemNrInt> -->
      <SupplNr>L001</SupplNr>
      <!-- <SupplPrice>12.50</SupplPrice> -->
      <!-- <EAN>4006381333931</EAN> -->
      <!-- <ItemNrSuppl>LF-4711</ItemNrSuppl> -->
      <!-- <AddEAN>0</AddEAN> -->
      <!-- <PreferredSupplier>1</PreferredSupplier> -->
      <!-- <MinOrderQty>10</MinOrderQty> -->
      <!-- <OnlyPU>0</OnlyPU> -->
      <!-- <ItemDeliveryTime>5</ItemDeliveryTime> -->
    </ns1:pixiSetItemSupplier>
  </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:pixiSetItemSupplier>
      <!-- <ItemKey>10452</ItemKey> -->
      <!-- <ItemNrInt>ART-100245</ItemNrInt> -->
      <SupplNr>L001</SupplNr>
      <!-- <SupplPrice>12.50</SupplPrice> -->
      <!-- <EAN>4006381333931</EAN> -->
      <!-- <ItemNrSuppl>LF-4711</ItemNrSuppl> -->
      <!-- <AddEAN>0</AddEAN> -->
      <!-- <PreferredSupplier>1</PreferredSupplier> -->
      <!-- <MinOrderQty>10</MinOrderQty> -->
      <!-- <OnlyPU>0</OnlyPU> -->
      <!-- <ItemDeliveryTime>5</ItemDeliveryTime> -->
    </ns1:pixiSetItemSupplier>
  </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 = [
    // 'ItemKey' => '10452',
    // 'ItemNrInt' => 'ART-100245',
    'SupplNr' => 'L001',
    // 'SupplPrice' => '12.50',
    // 'EAN' => '4006381333931',
    // 'ItemNrSuppl' => 'LF-4711',
    // 'AddEAN' => '0',
    // 'PreferredSupplier' => '1',
    // 'MinOrderQty' => '10',
    // 'OnlyPU' => '0',
    // 'ItemDeliveryTime' => '5',
];

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

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