pixiCreateDirectInvoice · Pixi API documentation

Wrapper around the internal procedure Pixi_CreateDirectInvInvoices. It always uses CreationMode = 'Direct' and language 1. The 1SS, bin and best-before options of the internal procedure are not used.

Processing steps

Open lines check. If the order has no order line in one of the statuses RAS, OPA, NAO, ANG, BES, BOR, NAS, OPH, NAD (for example only MIN lines), the call stops without a result set.
Line selection. OrderlineRefs is split at commas into order line keys. An empty or NULL value means all eligible lines of the order.
Active picklist check. If OrderlineRefs is empty and any line of the order is on an active picklist (PLitem.Expired = 0), the call stops without a result set.
Customer and address check. Customer, billing address, shipping address, ship vendor and currency are read from OrderHeader. No invoice is created if the customer (SLocked) or the shipping address (ASlocked) is locked.
Picklist for stock release. If setting DoNotReleaseStockOnDirectInvoiceScanOut is '0' or AllInvoiceItemsInStock = 'Y', a picklist is created for the selected lines (partial orders and partial quantities allowed).
- With AllInvoiceItemsInStock = 'Y', the picklist is deleted and no invoice is created if it is empty or if the picked quantity differs from the sum of the ordered quantities.
- If the setting is '1', the picklist is deleted again after the check.
Invoice creation (in a transaction).
- The invoice header is created. VAT type is N if the billing address has a VAT ID (UsStID) or the customer has TaxOnInvoice = 'N', otherwise I.
- The exchange rate, return tracking ID and SEPA data are determined.
- Invoice lines are inserted for the selected lines in the statuses above plus MIN that are not yet invoiced.
- The next invoice number of the shop is assigned. The package weight is the setting DefaultShippingWeight, or the sum of item weights if CalculateWeightFromItems = 1, capped at 999999.999.
Order line update. Invoiced non-MIN lines get InvRef and status EIN. MIN lines get only InvRef.
Cancel remaining lines. If setting Invoice_CancelPartialDelivery = '1', remaining ANG/HAL/BOR lines of orders with ForceToPickListIfNotFULL = 1 and OHCancelAfterForcedShipOut = 1 are set to STO.
Automatic scan-out. If the ship vendor (DoScanOutOnInvoiceCreate) or the payment method (AutoScanOutInvoice) requests it:
- a box is created and scanned out;
- a stock release job is queued in ExecQueries;
- the box is deleted if setting 1SS_ForceAutoScanOut = 1, and ScanOutDone becomes 1.
Event. The MQ event InvoiceCreated is published and the transaction is committed.

The call finally returns one status row with Success, InvoiceKey, CreatedInv and InvoicePackageId.

Notes

No result set in some cases. The call returns no result set at all if the order has no open (non-MIN) lines, if OrderlineRefs is empty and part of the order is on an active picklist, or if AllInvoiceItemsInStock = 'Y' and the picked quantity does not match. Clients must handle a missing SqlRowSet1.
Success = 1 does not guarantee an invoice. In these cases InvoiceKey/CreatedInv stay 0:
- the customer or the shipping address is locked;
- no eligible lines were found;
- the picklist was empty with AllInvoiceItemsInStock = 'Y'. Always check CreatedInv > 0.
Errors are reported twice. If an error occurs during invoice creation:
- the transaction is rolled back and the error is logged via LOG.InsertError;
- the picklist is deleted;
- a row with Success = 0 is returned;
- the error is then re-raised (sp_Exception_ReRaise), so a SqlMessage is also returned.
OrderlineRefs format. The value must be comma-separated, e.g. ,1234,1235,. Only numeric elements greater than 0 are used.
LocID. Used for picklist creation and scan-out only. The invoice location comes from the order lines (LocationID).
Side effects:
- picklists may be created and deleted;
- a job Pixi_ReleaseStockFrominvoicePicklist is queued in ExecQueries on auto scan-out;
- the MQ event InvoiceCreated is published;
- Pixi_CA_AddPixiInvoice is executed;
- duration logging is written via LOG.EventDurationInsert.
Settings read at runtime: DoNotReleaseStockOnDirectInvoiceScanOut, DefaultShippingWeight, CalculateWeightFromItems, PutThisStatusesOnInvoice, Invoice_CancelPartialDelivery, 1SS_ForceAutoScanOut.
Not attached. The behaviour of the called procedures (e.g. Pixi_CreatePickList, GOS_Qi_InvoiceNOD, Pixi_ScanOutBox) is not attached and may raise further errors.
Locking. Most reads use NOLOCK.

Tables used

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

Parameter	Type	Default	Description
`OrderNr` Required	int	–	Order number (`OrderHeader.OrderNr`) to invoice. Example: `93867`
`OrderlineRefs` Required	varchar(2000) string	–	Comma-separated order line keys (`OrderlineKey`) to invoice, enclosed in commas, e.g. `,1234,1235,`. An empty string or NULL invoices all eligible lines of the order. Example: `,280671,280672,`
`AllInvoiceItemsInStock`	varchar(1) string	N	If `Y`, the invoice is only created when all selected lines can be fully picked from stock. NULL is treated as `N`. Allowed values `Y` – All selected lines must be in stock, otherwise no invoice is created. `N` – Invoice is created regardless of stock availability. Example: `Y`
`LocID`	varchar(3) string	001	Location ID used for picklist creation, box creation and scan-out. Example: `001`
`CreateEmp`	varchar(50) string	API	User name stored as creator of the invoice, invoice lines and order line updates. Example: `API`

Result set 1 · Only if an error occurs during invoice creation; followed by the re-raised SQL error.

Error row of the failed invoice creation.

Column	Type	Description
`ErrorMessage` Nullable	varchar(4000) string	Error message text.
`Success`	int	Always 0.
`InvoiceKey`	int	Always 0.
`ScanOutDone` Nullable	bit boolean	Whether the scan-out was completed (normally 0).

Result set 2 · When processing finishes normally or a picklist step fails; not when the call stops early without a result set.

Final status row of the direct invoice creation.

Column	Type	Description
`ErrorMessage` Nullable	varchar(4000) string	Error message of a failed picklist step; NULL on success.
`Success`	int	1 if no error message is set, otherwise 0. Does not guarantee that an invoice was created.
`InvoiceKey` Nullable	int	Key of the created invoice (`Invoices.InvoiceKey`), 0 if none.
`ScanOutDone` Nullable	bit boolean	1 if the box was scanned out and deleted automatically.
`CreatedInv` Nullable	int	Key of the created invoice, 0 if no invoice was created.
`InvoicePackageId` Nullable	int	ID of the invoice package (`pixi.InvoicePackage.Id`); NULL if no invoice was created.

Response example

<SqlRowSet1>
  <row>
    <Success>1</Success>
    <InvoiceKey>512345</InvoiceKey>
    <ScanOutDone>false</ScanOutDone>
    <CreatedInv>512345</CreatedInv>
    <InvoicePackageId>498761</InvoicePackageId>
  </row>
</SqlRowSet1>

Status	Message	Cause
RAISERROR	Invlines problem...	No invoice lines were inserted for the new invoice, e.g. all selected lines are already invoiced. The transaction is rolled back.
RAISERROR	Invoice Problem - ID and InvoiceNr do not match...	The assigned invoice number could not be stored on the invoice. The transaction is rolled back.
RAISERROR	ERROR: {Info}	Automatic scan-out of the box failed; `{Info}` is the message from `Pixi_ScanOutBox`. The transaction is rolled back.

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:pixiCreateDirectInvoice>
      <OrderNr>93867</OrderNr>
      <OrderlineRefs>,280671,280672,</OrderlineRefs>
      <!-- <AllInvoiceItemsInStock>Y</AllInvoiceItemsInStock> -->
      <!-- <LocID>001</LocID> -->
      <!-- <CreateEmp>API</CreateEmp> -->
    </ns1:pixiCreateDirectInvoice>
  </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:pixiCreateDirectInvoice>
      <OrderNr>93867</OrderNr>
      <OrderlineRefs>,280671,280672,</OrderlineRefs>
      <!-- <AllInvoiceItemsInStock>Y</AllInvoiceItemsInStock> -->
      <!-- <LocID>001</LocID> -->
      <!-- <CreateEmp>API</CreateEmp> -->
    </ns1:pixiCreateDirectInvoice>
  </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 = [
    'OrderNr' => '93867',
    'OrderlineRefs' => ',280671,280672,',
    // 'AllInvoiceItemsInStock' => 'Y',
    // 'LocID' => '001',
    // 'CreateEmp' => 'API',
];

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

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