API - MES Transactions


Overview

The is an API to create a new transaction in the MES transaction queue.

Endpoint name

mes/transactions

Source table

WiFiAPIs MES Transaction

Fixed view/defaults

No filter, but the table only contains un-archived transactions.
(Transactions should be archived on a regular basis.)

Requests allowed

  • POST is used to create transactions

  • DELETE is allowed, but not when the transaction has been processed.

Primary key

The primary key of a transaction line is id

Record ID

The record ID is the same field as the primary key: id

Procedures

setReady, setOnHold, errorCheck, process

This API will only create the header of the transaction, i.e. the entry in table “MES Transaction”

This table does not contain any items or quantities, the next step would be to use the endpoint transactionLines to add the item lines on the newly created transaction.
See documentation: API - MES Transaction Lines

The default values and the errors in the response are described in How it works below. How each transaction type is processed is described on the page of that type: MES Receipt, MES Output, MES Consumption, MES Transfer, MES Adjustment, MES Shipment.

Data

Field List

Property

Type

Format

Description


1

id

integer


The id of the Transaction

After posting, this value will become a connection to the posted trade item, because it will be inherited into field “WP Connection PK” in Open Trade Item and Trade Item Ledger Entry.

PRIMARY KEY

record id

non-editable

2

terminal

string

max 10

Field “Terminal Code” will say from which manufacturing unit this entry comes from.

If skipped, the Default Terminal for APIs on page API Base Setup is used.

OPTIONAL

3

externalReference

string

max 10

The can must put it’s own reference on every transaction.

The usage of External Reference can be skipped, with a setting on the Terminal: Disable Ext. Reference Check

OPTIONAL

4

type

string

enum

Options:

  • Receipt - use this for both Landing and Purchase

  • Consumption

  • Output

  • Shipment

  • Transfer

  • Adjustment

If the property is skipped, it is set as Output

MANDATORY *


5

documentType

string


The type of the document in documentNo. Allowed values:

  • PurchaseOrder - Purchase Order

  • PurchaseAgreement - Receipt Agreement

  • FishingTrip - Fishing Trip

  • SalesOrder - Sales Order

  • SalesAgreement - Delivery Agreement

  • ProductionOrder - Released Production Order

  • ProductionAgreement - Production Agreement

If skipped, it is found from documentNo (see How it works > Endpoint). Which document types are supported depends on the transaction type, see the page of each type.

optional

6

documentNo

string

max 20

The number of the document this transaction belongs to. A Receipt must have a document; for the other types it depends on the usage. It can be the number of a:

  • Purchase Order

  • Receipt Agreement

  • Fishing Trip

  • Sales Order

  • Delivery Agreement

  • Released Production Order

  • Production Agreement

If documentType is not given, the request is refused if no document with this number is found. If documentType is given, the document is checked when the transaction is processed.

optional

7

activityDate

string

date

The date when this activity occured, for example the production date for output entries, the receipt date of received material etc.

If skipped, the today’s date will be used by default.

optional

8

stockCenter

string

max 20

The Stock Center this entry belongs to. If skipped, it is taken from the Lot, the Terminal or the User Profile (see How it works > Endpoint). Mandatory only if the Terminal has Require Stock Center.

MANDATORY *

9

location

string

max 10

The Location to use when the item transactions will be posted. If skipped, it is taken from the Terminal or the User Profile (see How it works > Endpoint).

MANDATORY *

10

lot

string

max 10

When all the entries belong to the same Lot, this field should be populated to enable total calculations for the lot.

optional

11

stage

string

max 20


optional

12

onHold

boolean


On Hold status can be used to let the transaction wait until the user allows, for example when all the lines have been created on it.

If set = true, then the Status of the entry becomes “On Hold”.

This property is only used to set this transaction on hold when it is created (with POST). It is irrelevant when GET is used.

To allow the transaction to be processed, user can either

  • use setReady procedure, to set the status to “Ready”

  • or run the error check, if it is okay, then status will be set “Ready”

See chapter below about the procedure endpoints.

Only writable

13

credit

boolean


If this is a credit transaction or not.


14

transactionLines

array

json

An array of the Lines that belong to the transactions.

When GET is used, this will show all the lines on the transaction.

When POST is used, an array with objects can be given in order to create the lines at the same time as the header.

optional

15


The following properties are non-editable and can be used when reading transactions, to check their status:

16

status

string


This shows the status of the transaction, options are:

  • Ready

  • Error

  • Processed

  • On Hold

non-editable

17

errorDescription

string


If a transaction has status = Error, there will be a text in this property. Note, that each transaction can have multiple errors, this will only show the first one.


18

createdAt

string

date-time

The date and time when this record was created.

non-editable

19

createdByUser

string


The user who created the record.

NON-EDITABLE

20

lastModified

string

date-time

The date and time when this record was last modified. This is updated when the transaction is processed, both if processed successfully or it ended on error.

non-editable

21

modifiedByUser

string


The user who last modified the record.

NON-EDITABLE


Example Object

This transaction is for received items for a purchase agreement:

JSON
{
    "id": 14,
    "terminal": "STREAM",
    "extReference": "REC-02",
    "type": "Receipt",
    "documentNo": "PR-050",
    "activityDate": "2026-01-27",
    "stockCenter": "FROSTI",
    "location": "BLUE",
    "lot": "",
    "stage": "PURCHASE",
    "lastModified": "2026-02-06T14:03:26.73Z"
}

This transaction is a receipt for a Fishing Trip:

JSON
{
    "id": 9,
    "terminal": "STREAM",
    "externalReference": "ID-0144",
    "type": "Receipt",
    "documentType": "FishingTrip",
    "documentNo": "FT-26-07",
    "activityDate": "2026-01-09",
    "stockCenter": "FROSTI",
    "location": "BLUE",
    "lot": "LANDING-LOT-FROSTI",
    "stage": "LANDED",
    "lastModified": "2026-02-06T12:09:17.567Z"
}

This transaction is for a production output:

JSON
{
    "id": 1,
    "terminal": "PACKING",
    "externalReference": "PROD-01",
    "type": "Output",
    "documentType": "None",
    "documentNo": "",
    "activityDate": "2026-01-27",
    "stockCenter": "FACTORY",
    "location": "BLUE",
    "lot": "LOT001",
    "stage": "PRODUCTION",
    "lastModified": "2026-02-06T14:04:09.613Z"
}


Usage

Read transactions

Get a list of transactions:

JSON
GET https://[server]/api/wisefish/mes/v1.0/companies([companyId])/transactions


Get a single transaction with all lines

JSON
GET https://[server]/api/wisefish/mes/v1.0/companies([companyId])/transactions(8)?$expand=transactionLines

Example response:

JSON
{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/mes/v1.0/$metadata#companies(cf9f7b85-dd11-ef11-9f8b-6045bde9cc61)/transactions/$entity",
    "@odata.etag": "W/\"JzE5OzMxNDI5MTg2MTUwNTg0ODE5MjYxOzAwOyc=\"",
    "id": 8,
    "terminal": "STREAM",
    "externalReference": "ID-0143",
    "type": "Receipt",
    "documentType": "FishingTrip",
    "documentNo": "FT-26-07",
    "activityDate": "2026-01-09",
    "stockCenter": "FROSTI",
    "location": "BLUE",
    "lot": "LANDING-LOT-FROSTI",
    "stage": "LANDED",
    "lastModified": "2026-02-17T15:54:42.137Z",
    "transactionLines": [
        {
            "@odata.etag": "W/\"JzIwOzEwNjMzNTMwMDU4NjgzNDQ0ODU2MTswMDsn\"",
            "systemId": "e8a09907-b0fb-f011-b02e-e41590da1342",
            "transactionId": 8,
            "lineNo": 1,
            "extReference": "",
            "itemNo": "70079",
            "quantity": 5,
            "unitOfMeasure": "BOX",
            "weight": 100,
            "lotCode": "LANDING-LOT-FROSTI",
            "tradeItemBarcode": "",
            "palletBarcode": "0000111122223333454",
            "palletNo": "",
            "lastModified": "2026-01-27T18:43:11.883Z"
        },
        {
            "@odata.etag": "W/\"JzE5OzUwOTU4NDk3NjU1NzcxNTIzMDUxOzAwOyc=\"",
            "systemId": "e9a09907-b0fb-f011-b02e-e41590da1342",
            "transactionId": 8,
            "lineNo": 2,
            "extReference": "",
            "itemNo": "70079",
            "quantity": 7,
            "unitOfMeasure": "BOX",
            "weight": 100,
            "lotCode": "LANDING-LOT-FROSTI",
            "tradeItemBarcode": "",
            "palletBarcode": "0000111122223333454",
            "palletNo": "",
            "lastModified": "2026-01-27T18:43:21.573Z"
        }
    ]
}


Creating a transaction

Create a new transaction (header)

The following will create a new transaction header:

JSON
POST
.../transactions

Body:
{   
    "terminal": "INNOVA",
    "externalReference": "12-31-654",
    "type": "Output",
    "lot": "LOT-03-01",
    "stage": "PRODUCTION"
}

In this example, the terminal “INNOVA” would be set up with …

  • a default Stock Center Code

  • a default Location Cod

Or instead, the User Profile could have a default Location or Stock Center.

The Response then looks like this:

JSON
{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/mes/v1.0/$metadata#companies(cf9f7b85-dd11-ef11-9f8b-6045bde9cc61)/transactions/$entity",
    "@odata.etag": "W/\"JzE5OzU0MjY2ODA4NzgyMjUzODg5MTAxOzAwOyc=\"",
    "id": 67,
    "terminal": "INNOVA",
    "externalReference": "12-31-654",
    "type": "Output",
    "documentType": "None",
    "documentNo": "",
    "activityDate": "2026-02-17",
    "stockCenter": "OWN",
    "location": "BLUE",
    "lot": "LOT-03-01",
    "stage": "PRODUCTION",
    "lastModified": "2026-02-17T16:02:22.353Z"
}

After a successful request:

  • A transaction has been created and visible in page MES Transactions. The response of the API shows the properties of the transaction.

→ Since this is only the header entry of the transaction, which does not have any item information, the next step would be to use the endpoint transactionLines to insert lines on this transactions with item numbers and quantities.


Create a new transaction with one line

This example shows how to create both the header and one line in the same request. Here, the PR-0050 could be the number of a Receipt Agreement, and a pallet with 10 boxes is being received:

JSON
POST
.../transactions

Body:
{   
    "terminal": "GRADER1",
    "externalReference": "ID-0123",
    "type": "Receipt",
    "documentNo": "PR-0050",
    "transactionLines": [
      {
          "itemNo": "70079",
          "quantity": 10,
          "unitOfMeasure": "BOX",
          "palletBarcode": "00050000000000000005"       
      }
    ]
}

The response will show all the properties of the endpoint:

  • The primary key of the created transaction can be seen in property transactionId

  • The primary key of the transaction line is in 2 properties: transactionId and lineNo

  • lineNo has value 1, which means that this is the first item line for this transaction.


Create a new transaction with multiple lines - BULK

In this example a transaction is created that contains 2 trade items that will be posted as a production output on the same lot.

JSON
POST
.../transactions?$expand=lines

{   
    "terminal": "INNOVA",
    "externalReference": "12-31-656",
    "type": "Output",
    "lot": "LOT-03-01",
    "stage": "PRODUCTION",
    "transactionLines": [
        {
            "itemNo": "70064",
            "quantity": 20,
            "unitOfMeasure": "KG",
            "lot": "LOT-03-01"
        },
        {
            "itemNo": "70064",
            "quantity": 20,
            "unitOfMeasure": "KG",
            "lot": "LOT-03-01"
        }
    ]
}


Procedure Endpoints

Set a Transaction on Hold

This procedure can only change a status from either “Ready” or “Error” to “On Hold”

JSON
POST
.../transactions([id])/Microsoft.NAV.setOnHold

Status will be set = On Hold

Before, the status has to be either “Ready” or “Error”


Set a Transaction Ready

This procedure can only change a status from “On Hold” to “Ready”.

JSON
POST
.../transactions([id])/Microsoft.NAV.setReady

Status will be set = Ready

Before, the status has to be “On Hold”.


Error check a Transaction

This procedure is the same as clicking on “Error Check” on the GUI page:

JSON
POST
.../transactions([id])/Microsoft.NAV.errorCheck

The error check will be run, Status will become either Ready or Error

If the Status was “On Hold” before, it will be erased, since the purpose of status is to wait with the transaction until someone decides to handle it, either manually or with an API endpoint.

Process a Transaction

This procedure is the same as clicking on “Process” on the GUI page:

JSON
POST
.../transactions([id])/Microsoft.NAV.process

The transaction will be processed, which means that

  1. First the error check, if error, Status will become “Error”

  2. If no error, the transaction is posted, or whatever the transaction’s purpose is (shipment, receipt, output, consumption etc.)




How it works

POST → the transaction header (and the lines, if given) is created with status Ready (or On Hold) → the job queue error checks it → and posts it → status Processed.
If anything is wrong, the status is Error and nothing is changed in BC.

  • This endpoint sets the same defaults as the type endpoints, with one difference: on Transfer and Adjustment, the type endpoints take the header Location from the first line. Here, it must be given in location, or come from the User Profile.

  • The lines have no location or toLocation. Use API - MES Transfer for transfers.

  • A given documentType is not checked at the endpoint, only when the transaction is processed.

Endpoint

Each POST creates one header in table MES Transaction, and the lines in transactionLines, if given. The response is returned immediately.

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

Field

Value

Type

type, or Output

Terminal

terminal, or the Default Terminal for APIs on API Base Setup

Activity Date

activityDate, or today

Document Type

Only if documentNo is given: documentType, or if not given, the first document found with this number:

  • Receipt: Fishing Trip (if the lot was created for a fishing trip) → Receipt Agreement → Purchase Order

  • Output: Delivery Agreement → Sales Order → Released Production Order → Production Agreement

  • Shipment: Delivery Agreement → Sales Order

  • Consumption: Released Production Order → Production Agreement

  • Transfer, Adjustment: not found, documentType must be given

Document No.

documentNo. Receipt without documentNo, on a lot created for a fishing trip: the Fishing Trip of the lot

Lot

lot. Receipt on a Fishing Trip without lot: the last lot created for the fishing trip

Stock Center

stockCenter, else the Lot, else Terminal Default Stock Center, else User Profile

Location

location, else the Terminal (Receipt: Receiving Location; Output, Consumption, Shipment: Production Location; Transfer, Adjustment: none), else User Profile

Stage

stage, else Lot Processing Stage, else the Terminal (Receipt: Receiving Stage; Output, Consumption: Production Stage; Transfer, Adjustment: Default Stage; Shipment: none), else User Profile

Status

Ready, or On Hold if onHold is true, or if MES Terminal Control says this type from this terminal/location is processed manually

Credit

Set when a line has a negative quantity

The default values on the lines are described on API - MES Transaction Lines.

Errors in the response (nothing is created)

  • no terminal (neither given nor a default), or 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 given nor a default)

  • no Stock Center, if the Terminal has Require Stock Center

  • Receipt without documentNo

  • Output or Consumption without lot

  • documentNo is given without documentType, and no document is found with this number

  • Receipt on a lot created for a fishing trip, but documentNo is another fishing trip

  • an error on one of the transactionLines (see API - MES Transaction Lines): then the whole request fails

Everything else is checked when the transaction is processed.

Processing

The MES processor (job queue) processes Ready transactions in the same way, whichever endpoint created them: first the error check, then the posting. Each transaction is processed in one unit: if anything fails, nothing is changed in BC.

The errors and the result of the posting are described on the page of each type: MES Receipt, MES Output, MES Consumption, MES Transfer, MES Adjustment, MES Shipment.

Settings

Settings that change what happens in the endpoint:

Setting

Where

Step

Effect

Default Terminal for APIs

API Base Setup

Endpoint

Terminal, when terminal is not given

Default Stock Center, Receiving Location, Production Location, Receiving Stage, Production Stage, Default Stage

MES Terminal

Endpoint

Default values on the transaction header, depending on the type

Stock Center Code, Location Code, Stage

User Profile

Endpoint

Default values, when not found on the Lot or the Terminal

Require Stock Center

MES Terminal

Endpoint

Stock Center is mandatory

Disable Ext. Reference Check

MES Terminal

Endpoint

externalReference is not required and not checked for uniqueness

Process Manually

MES Terminal Control

Endpoint

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