API - MES Receipt


Overview

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

Receiving transactions are used to handle either Purchase Orders, Receipt Agreements or Fishing Trips.

Working with a receipt 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 registers it in BC (documents, lots, trade items, posting).

Endpoint name

mes/receipt

Source table

WiFiAPIs MES Transaction Line

Fixed view/defaults

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

Requests allowed

  • POST is used to create transactions

  • PATCH is not allowed.

  • DELETE is not allowed.

(If GET is used, it will only show lines with Transaction Type = Receipt.)

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

guid

The automatic system ID, which is in GUID format.

record id

non-editable

transactionId

integer


The Transaction this line belongs to. 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. It is not possible to use an ID that does not exist.

PRIMARY KEY

Mandatory or use externalReference instead

lineNo

integer


The number of this line, within the transaction if ID = transactionId

PRIMARY KEY

non-editable

terminal

string

max 10

The Terminal Code will say from which manufacturing unit this entry comes from. If there is only one terminal, this can be set up as a default.

OPTIONAL

externalReference

string

max 10

The sender can use its own reference, in order to add a line to a transaction already created.

Mandatory

or use transactionId instead

documentType

string

enum

Allowed values:

  • PurchaseAgreement (Receipt Agreement)

  • FishingTrip

  • PurchaseOrder

If skipped, the system will find it according to documentNo (see How it works > Endpoint).

Mandatory *

documentNo

string

max 20

A receiving transaction must belong to a document, these can be any of the following:

  • Receipt Agreement No.

  • Fishing Trip No.

  • Purchase Order No.

If documentType is not given, the endpoint gives an error if no document 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, because it has already been put on the transaction. But if it is given, it must match the document number on the transaction.

Mandatory

documentLineNo

integer


To specify the line number on the receipt document.

OPTIONAL

receiptDate

string

date

The date of the receipt of the items.

OPTIONAL

location

string

max 10

The location of the received item / trade item.

OPTIONAL

itemNo

string

max 20

Item No.

Mandatory *

quantity

number


quantity and unitOfMeasure are mandatory, unless weight is used instead.

Mandatory *

unitOfMeasure

string

max 10

The unit of measure that belongs to the quantity field.

Mandatory *

weight

number


Weight, if used, it is the weight in the base weight unit of Wisefish.

Mandatory *

weightUnitOfMeasure

string

max 10

Only to be used for irregular items, or when real weight must be registered. Or when weight is in another unit than the general weight unit of the system. If not given, it will be set as the Weight Unit of the item.

OPTIONAL

pieces

number


For some trade items, the number of pieces is given and saved on the Trade Item record. This can for example be number of fish in a box.

OPTIONAL

lot

string

max 10

For some receipts, the lot can be known beforehand.

OPTIONAL

tradeItemBarcode

string

max 22

If given, this will be the Trade Item Barcode on the Trade Item entry.

OPTIONAL

palletBarcode

string

max 20

If this trade item was put on a pallet, give the pallet barcode in this property.

OPTIONAL

palletNo

string

max 20

If the pallet has already been created, this field can be skipped.

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
{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#companies(cf9f7b85-dd11-ef11-9f8b-6045bde9cc61)/mesReceipt/$entity",
    "@odata.etag": "W/\"JzIwOzE2MTcxNTMyODcwMDc0OTAwMjM0MTswMDsn\"",
    "systemId": "5c251d5b-d80c-f111-b02e-c90982a94d21",
    "transactionId": 72,
    "lineNo": 1,
    "terminal": "POSTMAN",
    "externalReference": "REC-04",
    "documentType": "PurchaseAgreement",
    "documentNo": "PR-049",
    "receiptDate": "2026-02-18",
    "itemNo": "70064",
    "quantity": 50,
    "unitOfMeasure": "KG",
    "weight": 50,
    "pieces": "",
    "lot": "PURCH01",
    "tradeItemBarcode": "",
    "palletBarcode": "",
    "palletNo": "",
    "lastModified": "2026-02-18T14:44:41.65Z"
}

Usage

The requests below are sent to .../api/wisefish/base/v1.0/companies({companyId})/mesReceipt, shortened to .../mesReceipt.

Create a receipt transaction for a single item

Using an “External Reference” that does not exist on an existing transaction, will create a new one.

In the following example, the PR-0050 could be the number of a Receipt Agreement, and a pallet with 10 boxes is being received.

JSON
POST
.../mesReceipt

Body:
{   
    "externalReference": "ID-0123",
    "documentNo": "PR-0050",
    "itemNo": "70079",
    "quantity": 10,
    "unitOfMeasure": "BOX",
    "palletBarcode": "00050000000000000005"
}

The response will show all the properties of the endpoint:

JSON
{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#companies(cf9f7b85-dd11-ef11-9f8b-6045bde9cc61)/mesReceipt/$entity",
    "@odata.etag": "W/\"JzIwOzE1NTI3NzUwMjkzNjQ0MzE2MTM2MTswMDsn\"",
    "systemId": "d13ef9f5-24df-f011-b02a-a0f00c1d9c9e",
    "transactionId": 33,
    "lineNo": 1,
    "externalReference": "ID-0123",
    "documentType": "PurchaseAgreement",
    "documentNo": "PR-0050",
    "itemNo": "70079",
    "quantity": 10,
    "unitOfMeasure": "BOX",
    "weight": 100,
    "pieces": "",
    "tradeItemBarcode": "",
    "palletBarcode": "00050000000000000005",
    "palletNo": "",
    "lastModified": "2025-12-22T10:57:09.707Z"
}
  • 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

  • documentType was skipped in the request, and set to PurchaseAgreement because PR-0050 is found as Receipt Agreement

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


Add trade item to an existing receipt transaction

Using Transaction ID

Posting again, with the transactionId just created, will add a new line on the same transaction.

JSON
POST
.../mesReceipt

{   
    "transactionId": 33,
    "documentNo": "PR-0050",
    "itemNo": "70079",
    "quantity": 11.5,
    "unitOfMeasure": "kg",
    "palletBarcode": "00050000000000000005"
}

The response shows that line number 2 has now been added:

JSON
{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#companies(cf9f7b85-dd11-ef11-9f8b-6045bde9cc61)/mesReceipt/$entity",
    "@odata.etag": "W/\"JzIwOzExNzk4NzY0NzQxMTM0ODI2NzYyMTswMDsn\"",
    "systemId": "552f8937-25df-f011-b02a-a0f00c1d9c9e",
    "transactionId": 33,
    "lineNo": 2,
    "externalReference": "ID-0123",
    "documentType": "PurchaseAgreement",
    "documentNo": "PR-0050",
    "itemNo": "70079",
    "quantity": 11.5,
    "unitOfMeasure": "KG",
    "weight": 11.5,
    "pieces": "",
    "tradeItemBarcode": "",
    "palletBarcode": "00050000000000000005",
    "palletNo": "",
    "lastModified": "2025-12-22T10:58:59.703Z"
}


Using External Reference

In a similar way, the same externalReference can be used repeatedly, to add multiple lines on the same transaction.

JSON
POST
.../mesReceipt

Body:
{   
    "externalReference": "ID-0123",
    "documentNo": "PR-0050",
    "itemNo": "70079",
    "quantity": 12.0,
    "unitOfMeasure": "kg",
    "palletBarcode": "00050000000000000005"
}

The response shows, that now the third line has been created on the same transaction:

JSON
{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#companies(cf9f7b85-dd11-ef11-9f8b-6045bde9cc61)/mesReceipt/$entity",
    "@odata.etag": "W/\"JzIwOzEzNzA2MjgyODE5NzMyMTE2NDQzMTswMDsn\"",
    "systemId": "35accb2a-26df-f011-b02a-a0f00c1d9c9e",
    "transactionId": 33,
    "lineNo": 3,
    "externalReference": "ID-0123",
    "documentType": "PurchaseAgreement",
    "documentNo": "PR-0050",
    "itemNo": "70079",
    "quantity": 12,
    "unitOfMeasure": "KG",
    "weight": 12,
    "pieces": "",
    "tradeItemBarcode": "",
    "palletBarcode": "00050000000000000005",
    "palletNo": "",
    "lastModified": "2025-12-22T11:05:47.823Z"
}


Receiving purchases

Receiving items on a purchase order which exists in BC:

JSON
POST
.../mesReceipt
{   
    "externalReference": "12345",
    "documentType": "PurchaseOrder",
    "documentNo": "PO-001",
    "receiptDate": "2026-02-16",
    "itemNo": "001",
    "quantity": 100,
    "lot": "BATCH-123",
    "unitOfMeasure": "STK"
}


Receiving landed raw material

Create Fishing Trip

First the Fishing Trip needs to be created, if it does not already exist:

JSON
POST
.../fishingTrips
{
    "landingDate": "2024-04-16",
    "landingTime": "16:00",
    "endDate": "2024-04-05",
    "startDate": "2024-04-04",
    "vessel": "2625",
    "aveWeightOfFish": 3.45,
    "salesPrice": 982
}
The response will say what the ID of the Fishing Trip is. Let's say it would be:
{
  "tripNo": "900061",
  ...
}

Receive raw material

Then the mesReceipt endpoint can be used repeatedly for all the items received.

Example:

JSON
POST
.../mesReceipt
{   
    "externalReference": "12345",
    "documentType": "FishingTrip",
    "documentNo": "900061",
    "receiptDate": "2023-08-17",
    "itemNo": "001",
    "weight": 1200,
    "palletBarcode": "00050000000000000001"
}
...then another pallet.
{   
    "externalReference": "12346",
    "documentType": "FishingTrip", 
    "documentNo": "900061",
    "receiptDate": "2023-08-17",
    "itemNo": "001",
    "weight": 1205,
    "palletBarcode": "00050000000000000002"
}
...and third pallet, etc.
{   
    "externalReference": "12347",
    "documentType": "FishingTrip", 
    "documentNo": "900061",
    "receiptDate": "2023-08-17",
    "itemNo": "001",
    "weight": 1998,
    "palletBarcode": "00050000000000000003"
}


Older version (Inbound from Innova)

In the older version this was posted in the following way with endpoint InboundInnovaEntries:

JSON
POST
.../inboundInnovaEntries
{
    "soapID": "108",
    "aveWeightOfFish": 3.45,
    "endDate": "2024-04-05",
    "itemId": "1",
    "landingDate": "2024-04-16T00:00:00Z",
    "masters": 1,
    "productionDate": "2023-08-17T00:00:00Z",
    "registrationDate": "2024-04-15T20:10:00Z",
    "salesPrice": 982,    
    "startDate": "2024-04-04",
    "supplier": "2625",
    "tripno": "900061",
    "warehouseId": "RawMaterial",
    "weight": 1200
}

How it works

POST → the transaction is created with status Ready (or On Hold) → the job queue error checks it → and registers it on the document (and posts it, if set up) → 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 documents, lots, pallets or trade items) until the transaction has been processed.

  • Receipt Agreements only take trade items. Standard items must be received on a Purchase Order.

  • The receipt is only registered on the document, not posted, unless the Terminal has Post Receipt Automatically.

Endpoint

Each POST creates one line in table MES Transaction Line with Transaction Type = Receipt, 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

Receipt

Terminal

terminal, or the default terminal

Activity Date

receiptDate, or today

Document Type

documentType. If not given, it is found from documentNo, in this order:

  1. the given lot belongs to a Fishing Trip → Fishing Trip (the lot must belong to that trip)

  2. a Receipt Agreement with this number exists → Receipt Agreement

  3. a Purchase Order with this number exists → Purchase Order

Lot

Only for Fishing Trips: if no lot is given, the last lot created for the Fishing Trip.

Location

location of the first line, else Terminal Receiving Location, else User Profile. The location on each line is used for posting.

Stock Center

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

Stage

Lot Processing Stage, else Terminal Receiving Stage, else User Profile

Status

Ready, or On Hold if MES Terminal Control says receipts 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

Lot

From the header

Location

From the header

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)

Weight Unit of Measure

The item's weight unit, if weight is given without a unit

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 given nor a default)

  • documentNo is missing

  • documentType is not given and no document is found with this documentNo

Everything else is checked when the transaction is processed.

Processing

The MES processor (job queue) processes Ready transactions: first the error check, then the registering (and 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.

Errors on the transaction (status Error, nothing registered)

  • Document: must exist. A Receipt Agreement must be a Receipt Agreement and Open. A Purchase Order may be open or released.

  • Items: Receipt Agreements only take trade items. Standard items must be received on a Purchase Order.

  • Lot: a given lot must exist in BC, unless the Terminal has Receiving Lot Created in MES (then the lot is created). With Receiving Lot Created in MES, the lot is required for lot tracked items. Fishing Trips: the lot is required and must belong to the Fishing Trip.

  • Stage: required for trade items.

  • Document line: with Purchase Line Must Exist, a matching line must exist on the agreement/order. A purchase line marked MES Finished gives an error. The agreement line must have a Stock Center.

  • Posting: with Post Receipt Automatically, if the posting fails, nothing is registered.

Result (after processing)

Receipt Agreement

  • For each line, the agreement line is found (same item, trade item unit, variant and lot), or a line without lot is used (it gets the lot), or a new line is created.

  • The number of trade items on the agreement line is raised, and an inbound line is created with the lot, pallet and quantity. Each inbound line becomes a trade item when the agreement is posted.

  • The agreement line keeps its purchase unit; the MES unit is the trade item unit. For irregular items the weight from MES is used.

  • A new lot or pallet from MES is created.

  • With Post Receipt Automatically: the posting document (Purchase Order or Purchase Invoice, acc. to Wisefish Setup Default Purchase Document Type) is created from the agreement and the receipt posted. The trade items are then in stock.

Purchase Order

  • For each line, the purchase line is found (item, variant, unit, or documentLineNo), or created.

  • If more is received than ordered, the line's quantity is raised (the originally ordered quantity is kept).

  • Item tracking (lot) is put on the purchase line for the received quantity. For trade items, a trade item inbound line is also created.

  • Lot: from MES, or (when lots are created in BC) created on the first receipt, saved on the purchase line and used again for the next receipts.

  • With Post Receipt Automatically: the receipt is posted.

Fishing Trip

  • For each line, a trade item is posted on the lot.

The transaction gets status Processed.

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

Settings

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

Setting

Where

Step

Effect

Receiving Location, Receiving Stage, 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

Receiving Lot Created in MES

MES Terminal

Processing

On: the lot comes from MES (required for lot tracked items), an unknown lot is created. Off: a given lot must exist in BC; if no lot is given, it is created in BC.

Purchase Line Must Exist

MES Terminal

Processing

On: error if the agreement/order has no matching line. Off: the line is created.

Post Receipt Automatically

MES Terminal

Processing

The receipt is posted in the same unit as the registration. If the posting fails, nothing is registered.

Trade Item Barcode Unique

MES Terminal

Processing

A given tradeItemBarcode must not exist already

Default Purchase Document Type

Wisefish Setup

Processing

Receipt Agreements: the posting document is a Purchase Order or a Purchase Invoice