API - MES Shipment


Overview

This is an API to create a shipment transaction in the MES transaction queue.

A shipment transaction can do one or more of the following:

  • Palletize trade items: put them on a pallet (the pallet can be created at the same time).

  • Reserve trade items to a Delivery Agreement (Wisefish).

  • Ship standard items on a BC Sales Order (and post the shipment, if set up).

  • Finish the shipment on a Delivery Agreement (a transaction without lines).

Working with a shipment has two steps (details in How it works):

  1. Endpoint: the MES posts to the endpoint, and the MES transaction is created. Nothing else is changed in BC yet.

  2. Processing: the MES processor (job queue) error checks the transaction and does the palletizing, reservation or shipment in BC.

See more information about the workflow: MES Use Case: Production

Endpoint name

mes/shipment

Source table

WiFiAPIs MES Transaction Line

Fixed view/defaults

This endpoint will only create/show transactions with Type = Shipment.

Requests allowed

  • POST is used to create transactions

  • PATCH is not allowed.

  • DELETE is not allowed.

  • GET is possible, but not recommended since this endpoint is specifically designed to insert entries. To view transactions, it is better to use API - MES Transactions

Primary key

The primary key of a transaction line is transactionId + lineNo

Record ID

The record ID is systemId

Procedures

None

Data

Field List

Property

Type

Format

Description


systemId

string

uuid

The automatic system ID, which is in GUID format.

record id

non-editable

transactionId

integer


The Transaction this line belongs to.

  • Skip this when creating a new transaction.

  • Can be used to add a line to a transaction that already has been created. If used, the transaction with this ID must already exist.

PRIMARY KEY

OPTIONAL

lineNo

integer


The sequence number of this line, within the transaction which has ID = transactionId. This is set automatically as the next number.

PRIMARY KEY

non-editable

terminal

string

max 10

The terminal will indicate from which manufacturing unit or machine this entry comes from. This is mandatory, but if there is only one terminal, this can be set up as a default on page API Base Setup.

OPTIONAL

externalReference

string

max 10

The sender needs to use their own reference, because every transaction needs to be unique. The same external reference can be used repeatedly in order to add a line to a transaction already created.

Mandatory

documentType

string

enum

Values:

  • SalesAgreement - a Delivery Agreement (trade items)

  • SalesOrder - a BC Sales Order (standard items)

  • None (or skipped, with no documentNo) - only palletizing

If skipped, it is found from documentNo (see How it works > Endpoint). The Document Type is shown in the response.

OPTIONAL

documentNo

string

max 20

The Delivery Agreement No. or Sales Order No. Skip it when only palletizing.

If documentType is not given, the endpoint gives an error if no Delivery Agreement or Sales Order with this number is found. If documentType is given, the document is first checked when the transaction is processed.

When adding a line to a current Transaction, the documentNo is not necessary. But if it is given, it must match the document number on the transaction.

OPTIONAL

documentLineNo

integer


The line of the Delivery Agreement or Sales Order. If not given, a matching line is found.

OPTIONAL

shipmentDate

string

date

The date of the palletizing, reservation or shipment. If not given, today.

OPTIONAL

location

string

max 10

The location where the items are found. If not given, the location of the transaction (see How it works > Endpoint).

Mandatory *

itemNo

string

max 20

Item No.

Mandatory

quantity

decimal


The quantity, in unitOfMeasure. With a reference to a trade item, quantity and unitOfMeasure can both be skipped: then the whole trade item is used.

Mandatory *

unitOfMeasure

string

max 10

The unit of measure that belongs to the quantity field. Can be skipped if the Terminal has Populate Unit Automatically.

Mandatory *

lot

string

max 10

The lot of the item. Required for lot tracked items, unless the line refers to a specific trade item (then it is taken from the trade item, and a given lot must match).

Mandatory *

tradeItemStage

string

max 20

A direct reference to a trade item can be given with tradeItemStage and tradeItemLineNo.

OPTIONAL

tradeItemLineNo

integer


See tradeItemStage.

OPTIONAL

tradeItemBarcode

string

max 22

A direct reference to a trade item with its barcode.

OPTIONAL

palletBarcode

string

max 20

The pallet to put the trade item on. If it does not exist, it is created (see How it works > Palletizing).

OPTIONAL

palletNo

string

max 20

Can be used instead of palletBarcode for an existing pallet. Required (with palletBarcode) when a new pallet is created. If both are given, they must be for the same pallet.

OPTIONAL

lastModified

date-time utc


The system populates this value automatically.

non-editable


Example Object

Expand to see the example json

An example of one object :

JSON
{
    "systemId": "a70a7ebe-acaa-f111-b03c-e5b3b28654ba",
    "transactionId": 27,
    "lineNo": 1,
    "terminal": "INNOVA",
    "externalReference": "SH-0124",
    "documentType": "None",
    "documentNo": "",
    "documentLineNo": 0,
    "shipmentDate": "2026-09-07",
    "location": "FREEZER_01",
    "itemNo": "00000001",
    "quantity": 10,
    "unitOfMeasure": "BOX",
    "lot": "LOT0056",
    "tradeItemStage": "",
    "tradeItemLineNo": 0,
    "tradeItemBarcode": "",
    "palletBarcode": "00066666667000000124",
    "palletNo": "",
    "lastModified": "2026-09-07T11:10:34.327Z"
}

Usage

The requests below are sent to .../api/wisefish/base/v1.0/companies({companyId})/mesShipment, shortened to .../mesShipment. How to create a new transaction and add lines to it works in the same way as for API - MES Receipt.

Palletizing (no document)

Put a barcoded trade item on a new pallet

JSON
POST
.../mesShipment

{   
    "externalReference": "REF-NO-1",
    "itemNo": "70064",
    "tradeItemBarcode": "0123456",
    "palletBarcode": "00066666667000000124",
    "palletNo": "000012"
}

The pallet does not exist, so it is created (barcode 00066666667000000124, no. 000012, key item 70064), and the trade item with barcode 0123456 is put on it. If that trade item is not of item 70064, the transaction gets an error.

Put a quantity of a lot on an existing pallet

JSON
POST
.../mesShipment

{   
    "externalReference": "REF-NO-2",
    "itemNo": "70064",
    "lot": "PROD180501",
    "quantity": 50,
    "unitOfMeasure": "BOX",
    "palletBarcode": "00066666667000000124"
}

The pallet exists, so palletNo can be skipped. A trade item of the item and lot with 50 boxes (or the first with more, then it is split) is put on the pallet.


Reservation to a Delivery Agreement

Reserve a trade item, and put it on a pallet

JSON
POST
.../mesShipment

{   
    "externalReference": "REF-NO-3",
    "documentNo": "DA-009",
    "itemNo": "70064",
    "tradeItemBarcode": "0123456",
    "palletBarcode": "00066666667000000124"
}

DA-009 is found as a Delivery Agreement. The trade item is put on the pallet, and reserved to the agreement line for the item (documentLineNo can be given to choose the line).

Reserve a quantity of a lot (no barcodes)

JSON
POST
.../mesShipment

{   
    "externalReference": "REF-NO-4",
    "documentType": "SalesAgreement",
    "documentNo": "DA-009",
    "documentLineNo": 20000,
    "itemNo": "70064",
    "quantity": 100,
    "unitOfMeasure": "KG",
    "lot": "LOT-123"
}

100 kg of the lot are reserved to line 20000. Without a reference, only trade items that are not reserved are used.


Finish the shipment on a Delivery Agreement

When the MES has sent everything for a Delivery Agreement, it says so with a shipment transaction without lines. Because this endpoint always creates a line, the transaction is created with the transactions endpoint:

JSON
POST
.../transactions

{   
    "terminal": "INNOVA",
    "externalReference": "DA-009-END",
    "type": "Shipment",
    "documentType": "SalesAgreement",
    "documentNo": "DA-009"
}

When this transaction is processed:

  • It must wait until all other MES transactions on the agreement are processed. Until then, it gets an error, and can be processed again later.

  • The agreement gets MES Status MES Finished.

  • With Sync Quantity and Reserved = After every transaction or After shipment closure on the Terminal, the agreement's quantities are updated to the reserved quantity.

  • The posting document is not created (see WFPAPI-194).


Shipment of standard items on a Sales Order

JSON
POST
.../mesShipment

{   
    "externalReference": "REF-NO-5",
    "documentNo": "1003",
    "itemNo": "70074",
    "quantity": 100,
    "unitOfMeasure": "PCS",
    "lot": "LOT-123"
}

1003 is found as a Sales Order. 100 PCS of the lot are registered as shipped on the sales line (and the shipment posted, if the Terminal has Post Shipment Automatically).

How it works

POST → the transaction is created with status Ready (or On Hold) → the job queue error checks it → and palletizes, reserves or ships → status Processed.
If anything is wrong, the status is Error and nothing is changed in BC. The error can be fixed and the transaction processed again.

  • Nothing is changed in BC (no pallets, splits, reservations or shipments) until the transaction has been processed.

  • Trade items are shipped on Delivery Agreements (or only palletized), standard items on Sales Orders.

  • Post Shipment Automatically only works for Sales Orders. On a Delivery Agreement it gives an error (not implemented, see WFPAPI-194).

Endpoint

Each POST creates one line in table MES Transaction Line with Transaction Type = Shipment, and the response is returned immediately.

Header (MES Transaction)

The line is added to an existing transaction header, or a new header is created:

  • If transactionId is given, the line is added to that transaction. It must exist.

  • Else, if a transaction with the same terminal + externalReference exists, the line is added to it.

  • Else a new transaction header is created.

When a line is added to an existing transaction, the transaction must not be Processed yet, and a given terminal, externalReference and documentNo must match the transaction.

Default values on a new header:

Field

Value

Type

Shipment

Terminal

terminal, or the default terminal

Activity Date

shipmentDate, or today

Document Type

Only if documentNo is given: documentType, or if not given, found from documentNo in this order:

  1. a Delivery Agreement with this number exists → Sales Agreement

  2. a Sales Order with this number exists → Sales Order

Any other number (for example a Production Order) is refused (error in the response).

Lot

Not set: a shipment can have lines of many lots

Location

Terminal Production Location, else User Profile, else location of the first line. Each line is handled on its own location.

Stock Center

Terminal Default Stock Center, else User Profile

Status

Ready, or On Hold if MES Terminal Control says shipments from this terminal/location are processed manually

Line (MES Transaction Line)

Default values on the line, if not given in the request:

Field

Value

Line No.

The next line number of the transaction

Document Type

From the header

Location

The location of the header

Quantity, Unit, Lot

With a reference to a trade item: the lot of the trade item and, if both quantity and unitOfMeasure are skipped, the whole trade item

Item No.

Mapped to the BC item number, if Data Mapping is active

Unit of Measure

If quantity is given without a unit and the Terminal has Populate Unit Automatically: the trade item unit (trade items) or base unit (standard items)

Pallet No.

From the pallet, if the pallet with palletBarcode exists

Errors in the response (nothing is created)

  • itemNo is missing

  • the terminal does not exist

  • externalReference is missing, or has already been used for another transaction from the same terminal (also archived transactions). Not checked if the Terminal has Disable Ext. Reference Check.

  • no Location (neither a default nor given)

  • documentNo is given without documentType, but no Delivery Agreement or Sales Order is found with this number

  • tradeItemStage + tradeItemLineNo refer to a trade item that does not exist

Everything else is checked when the transaction is processed.

Processing

The MES processor (job queue) processes Ready transactions: first the error check, then the posting. Everything for one transaction is done in one unit: if anything fails, nothing is changed in BC, and the job queue continues with the next transaction.

What is done depends on the document of the transaction:

Document

Items

For each line

None

Trade items

Find the trade item → palletize

Delivery Agreement

Trade items

Agreement line → find the trade item → palletize (if a pallet is given) → reserve

Sales Order

Standard items

Sales line → register what is shipped → post (if set up)

Delivery Agreement, no lines


Finish the shipment on the agreement (see Usage > Finish the shipment on a Delivery Agreement)

The steps are the same, whether the transaction only palletizes or also reserves. They are described once below.

Finding the trade item

  • Without a reference: an open trade item of the item and lot on the line's location and the transaction's stock center, that is not reserved: one with exactly the quantity, or else one with enough quantity that is not on a pallet. The lot is required.

  • With a reference (tradeItemBarcode, or tradeItemStage + tradeItemLineNo): the trade item must exist, be of the same item, on the same location, stock center and lot (if given), and have enough quantity. It may be reserved: see Reservation below.

  • Part of a trade item: the trade item is split. The requested quantity is palletized/reserved, the rest stays where it was, as a new trade item (not on the pallet, not reserved). A reserved trade item, or a trade item on a pallet, is not split (only as a whole).

Palletizing

Only when palletBarcode or palletNo is given:

  • The pallet is found with palletBarcode, or else with palletNo. An existing pallet must be on the transaction's stock center and the line's location.

  • If the pallet does not exist, it is created if the Terminal has Pallets Created in MES; then both palletBarcode and palletNo are required. Else: error.

  • Only trade items can be palletized.

Reservation (Delivery Agreement)

  • The agreement must exist. The agreement line is documentLineNo, or a matching line is found. If no line is found: error, unless the Terminal has Create missing Sales Lines. With Sales Line No. is Mandatory, documentLineNo is required.

  • A trade item that is reserved to another agreement gives an error, unless the Terminal has Allow Changing Reservation. A trade item reserved to the same agreement is fine.

  • Wisefish can refuse the reservation (for example when the shipment date of the agreement is before the production date of the trade item). Then the transaction gets the error, and nothing is changed (no split, an old reservation is kept).

  • A line must have either a reservation or a pallet. With Disable Reservation on the Terminal, nothing is reserved (only palletized, and the agreement line created).

Sales Order

  • Only standard items. The Sales Order must exist.

  • Lot tracked items need the lot. Items with Package Sales Outb. Tracking need the palletBarcode (the package).

  • There must be enough inventory of the item on the line's location (and lot).

  • The sales line is documentLineNo, or a matching line is found. If no line is found: error, unless the Terminal has Create missing Sales Lines.

Errors on the transaction (status Error, nothing changed)

  • A transaction cannot have both trade items and standard items. Trade items only without a document or on a Delivery Agreement, standard items only on a Sales Order.

  • The document does not exist, or documentNo on a line is not the document of the transaction.

  • Post Shipment Automatically on a Delivery Agreement: not implemented.

  • A finishing transaction (no lines) while other MES transactions on the agreement are not processed yet.

  • And the checks described above (trade item, pallet, agreement or sales line, inventory).

Result (after processing)

Palletizing

  • A new pallet is created (barcode, pallet no., key item = itemNo, the transaction's stock center and the line's location).

  • The trade item (or the split part) is put on the pallet.

Delivery Agreement

  • A missing agreement line is created, with Create missing Sales Lines.

  • The trade item (or the split part) is reserved to the agreement line. A reservation to another agreement is moved, with Allow Changing Reservation.

  • Sync Quantity and Reserved = After every transaction: the agreement's quantities are updated to the reserved quantity.

  • Finishing (no lines): the agreement gets MES Status MES Finished, see Usage.

Sales Order

  • A missing sales line is created, with Create missing Sales Lines. If more is shipped than ordered, the line's quantity is raised.

  • Item tracking (lot, package) is put on the sales line for the shipped quantity.

  • With Post Shipment Automatically, the shipment is posted in the same unit. If the posting fails, nothing is registered.

The transaction gets status Processed.

The exact behaviour is described by the unit tests: MES Unit Tests - Shipment

Settings

Settings that change what happens in the endpoint or in processing:

Setting

Where

Step

Effect

Production Location, Default Stock Center

MES Terminal

Endpoint

Default values on the transaction header

Disable Ext. Reference Check

MES Terminal

Endpoint

externalReference is not required and not checked for uniqueness

Populate Unit Automatically

MES Terminal

Endpoint

Missing unitOfMeasure is taken from the item

Process Manually

MES Terminal Control

Endpoint

New transactions get status On Hold and are not processed by the job queue

Pallets Created in MES

MES Terminal

Processing

On: an unknown pallet is created (pallet barcode and pallet no. required). Off: the pallet must exist.

Disable Reservation

MES Terminal

Processing

Delivery Agreements: nothing is reserved (only palletizing and agreement lines)

Allow Changing Reservation

MES Terminal

Processing

A trade item reserved to another agreement can be reserved to this one

Create missing Sales Lines

MES Terminal

Processing

A missing agreement line or sales line is created instead of an error

Sales Line No. is Mandatory

MES Terminal

Processing

Delivery Agreements: documentLineNo is required

Sync Quantity and Reserved

MES Terminal

Processing

After every transaction or After shipment closure: the Delivery Agreement's quantities are updated to the reserved quantity

Post Shipment Automatically

MES Terminal

Processing

Sales Orders: the shipment is posted in the same unit. Delivery Agreements: error (not implemented, WFPAPI-194).

Package Sales Outb. Tracking

Item Tracking Code

Processing

Sales Orders: palletBarcode (the package) is required