Invoices Write

pixiCreateDirectInv

Creates a direct invoice for an order, either for all open orderlines or for a comma-separated list of orderline keys.

The call is a thin wrapper around the internal procedure Pixi_CreateDirectInvInvoices. It passes LocID, CreateEmp, OrderNr and OrderlineRefs and uses fixed values for everything else: no "all items in stock" check, no bin restriction, no 1SS (one-step-shipping) mode, result row enabled, own transaction, creation mode Manual, language 1.

Pre-checks (no result set, no invoice):

If the order has no orderline in one of the open statuses RAS, OPA, NAO, ANG, BES, BOR, NAS, OPH, NAD, the call ends silently.
If OrderlineRefs is empty and any orderline of the order is on an active (not expired) picklist, the call ends silently.

Selection of orderlines:

OrderlineRefs is split at commas; only numeric keys > 0 are used. If it is empty, all orderlines of the order are used.
Only orderlines of OrderNr in the open statuses listed above plus MIN are invoiced, and only if they are not already on an invoice line.
The customer must not be locked (SLocked) and the shipping address must not be locked (ASlocked); otherwise nothing is created.

Invoice creation:

Depending on the setting DoNotReleaseStockOnDirectInvoiceScanOut (value 0), a picklist for the selected orderlines is created internally (partial orders and partial quantities allowed) and marked with the comment DirectInvStockRelease.
Within a transaction the invoice header is created (VAT type I, or N if the billing address has a VAT ID or the customer has TaxOnInvoice = 'N'), the exchange rate and a return tracking ID are determined and SEPA data is added.
Invoice lines are copied from the orderlines (quantity, price, discount, VAT, shipping cost, currency, serial number).
The invoice gets the next invoice number of the shop and a package gross weight (setting DefaultShippingWeight, or calculated from item weights if CalculateWeightFromItems = 1).
Invoiced open orderlines get status EIN and the invoice reference; MIN lines only get the invoice reference.
If Invoice_CancelPartialDelivery = 1, remaining ANG/HAL/BOR lines of orders flagged for forced partial shipping with cancellation are set to STO.
If the shipping vendor (DoScanOutOnInvoiceCreate) or the payment method (AutoScanOutInvoice) requires it, a box is created and scanned out, and a stock release job is queued.
The event InvoiceCreated is published.

One status row is returned at the end (see result sets).

Notes

OrderlineRefs has no default and must be sent; an empty string (or NULL) means "all eligible orderlines". The documented format is ,1234,1235,.
Silent exits: in the two pre-check cases the call returns no row at all. If the customer or shipping address is locked, the final row reports Success = 1 but InvoiceKey = 0 and CreatedInv = 0; check CreatedInv/InvoiceKey rather than only Success.
On an error inside the invoice transaction, everything is rolled back, the internal picklist is deleted, the error is logged (LOG.InsertError), a row with four columns is returned and the error is re-raised via sp_Exception_ReRaise (not attached), so the client also receives a SqlMessage.
An error while creating the internal picklist is not re-raised; it is returned in ErrorMessage of the final row with Success = 0.
LocID is used for picklist and box handling; the invoice location is taken from the orderlines.
Behaviour depends on the settings DoNotReleaseStockOnDirectInvoiceScanOut, DefaultShippingWeight, CalculateWeightFromItems, PutThisStatusesOnInvoice, Invoice_CancelPartialDelivery and 1SS_ForceAutoScanOut.
Side effects: MQ event InvoiceCreated, a queued Pixi_ReleaseStockFrominvoicePicklist entry in ExecQueries when scan-out runs, duration logging via LOG.EventDurationInsert. Many reads use NOLOCK.

Parameters

Parameter	Type	Default	Description
`LocID`	varchar(3) string	001	Location ID used for the internal picklist and box/scan-out handling. Example: `001`
`CreateEmp`	varchar(50) string	API	User name stored as creator of the invoice and as updater of the orderlines. Example: `API`
`OrderNr` Required	int	–	Number of the order to invoice. Example: `100245`
`OrderlineRefs` Required	varchar(2000) string	–	Comma-separated orderline keys to invoice, e.g. `,1234,1235,`. Empty string means all eligible orderlines of the order. Keys not belonging to the order are ignored. Example: `,1234,1235,`

Response

Result set 1 · At the end of processing, unless a pre-check stopped the call or an error occurred inside the invoice transaction.

Final status row of the direct invoice creation.

Column	Type	Description
`ErrorMessage` Nullable	varchar(4000) string	Error text from picklist creation; NULL on success.
`Success`	int	1 if `ErrorMessage` is NULL, otherwise 0. Also 1 if no invoice was created because nothing qualified.
`InvoiceKey` Nullable	int	Key of the created invoice; 0 if none was created.
`ScanOutDone` Nullable	bit boolean	1 if the box was scanned out and deleted automatically.
`CreatedInv` Nullable	int	Key of the created invoice; 0 if none was created.
`InvoicePackageId` Nullable	int	ID of the invoice package of the new invoice; NULL if no invoice was created.

Result set 2 · If an error occurs inside the invoice transaction; followed by the re-raised SQL error.

Error row returned before the error is re-raised.

Column	Type	Description
`ErrorMessage` Nullable	varchar(4000) string	Error message of the failed step.
`Success`	int	Always 0.
`InvoiceKey`	int	Always 0.
`ScanOutDone` Nullable	bit boolean	Scan-out flag at the time of the error.

Response example

<SqlRowSet1>
  <row>
    <Success>1</Success>
    <InvoiceKey>48213</InvoiceKey>
    <ScanOutDone>0</ScanOutDone>
    <CreatedInv>48213</CreatedInv>
    <InvoicePackageId>51007</InvoicePackageId>
  </row>
</SqlRowSet1>

Error messages

Status	Message	Cause
RAISERROR	Invlines problem...	No invoice lines were created for the new invoice (e.g. all selected orderlines are already invoiced). The transaction is rolled back; returned as error row and re-raised.
RAISERROR	Invoice Problem - ID and InvoiceNr do not match...	The assigned invoice number could not be verified on the invoice record. The transaction is rolled back.
RAISERROR	ERROR: {Info}	Automatic scan-out of the box failed; `{Info}` is the message from the scan-out routine. The transaction is rolled back.

Examples

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:pixiCreateDirectInv>
      <!-- <LocID>001</LocID> -->
      <!-- <CreateEmp>API</CreateEmp> -->
      <OrderNr>100245</OrderNr>
      <OrderlineRefs>,1234,1235,</OrderlineRefs>
    </ns1:pixiCreateDirectInv>
  </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:pixiCreateDirectInv>
      <!-- <LocID>001</LocID> -->
      <!-- <CreateEmp>API</CreateEmp> -->
      <OrderNr>100245</OrderNr>
      <OrderlineRefs>,1234,1235,</OrderlineRefs>
    </ns1:pixiCreateDirectInv>
  </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 = [
    // 'LocID' => '001',
    // 'CreateEmp' => 'API',
    'OrderNr' => '100245',
    'OrderlineRefs' => ',1234,1235,',
];

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

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

Tables used

Orderlines · Write OrderHeader · Read ShipVendor · Read Addresses · Read Customers · Read PLitem · Write PLheader · Write InvLines · Write Invoices · Write Currency · Read items · Read InvoicePackage · Write Payments · Read ExecQueries · Write boxes · Write

SQL object:: dbo.pipiCreateDirectInv