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):
-
Endpoint: the MES posts to the endpoint, and the MES transaction is created. Nothing else is changed in BC yet.
-
Processing: the MES processor (job queue) error checks the transaction and registers it in BC (documents, lots, trade items, posting).
|
Endpoint name |
|
|
Source table |
|
|
Fixed view/defaults |
This endpoint will only create/show transactions with Type = Receipt. |
|
Requests allowed |
(If GET is used, it will only show lines with Transaction Type = Receipt.) |
|
Primary key |
The primary key of a transaction line is |
|
Record ID |
The record ID is |
|
Procedures |
None |
Data
Field List
|
Property |
Type |
Format |
Description |
|
|---|---|---|---|---|
|
|
string |
guid |
The automatic system ID, which is in GUID format. |
record id non-editable |
|
|
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 |
|
|
integer |
|
The number of this line, within the transaction if ID = |
PRIMARY KEY non-editable |
|
|
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 |
|
|
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 |
|
|
string |
enum |
Allowed values:
If skipped, the system will find it according to |
Mandatory * |
|
|
string |
max 20 |
A receiving transaction must belong to a document, these can be any of the following:
If When adding a line to a current Transaction, the |
Mandatory |
|
|
integer |
|
To specify the line number on the receipt document. |
OPTIONAL |
|
|
string |
date |
The date of the receipt of the items. |
OPTIONAL |
|
|
string |
max 10 |
The location of the received item / trade item. |
OPTIONAL |
|
|
string |
max 20 |
Item No. |
Mandatory * |
|
|
number |
|
|
Mandatory * |
|
|
string |
max 10 |
The unit of measure that belongs to the |
Mandatory * |
|
|
number |
|
Weight, if used, it is the weight in the base weight unit of Wisefish. |
Mandatory * |
|
|
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 |
|
|
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 |
|
|
string |
max 10 |
For some receipts, the lot can be known beforehand. |
OPTIONAL |
|
|
string |
max 22 |
If given, this will be the Trade Item Barcode on the Trade Item entry. |
OPTIONAL |
|
|
string |
max 20 |
If this trade item was put on a pallet, give the pallet barcode in this property. |
OPTIONAL |
|
|
string |
max 20 |
If the pallet has already been created, this field can be skipped. |
OPTIONAL |
|
|
date-time utc |
|
The system populates this value automatically. |
non-editable |
Example Object
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.
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:
{
"@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:
transactionIdandlineNo -
documentTypewas skipped in the request, and set toPurchaseAgreementbecause PR-0050 is found as Receipt Agreement -
lineNohas 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.
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:
{
"@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.
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:
{
"@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:
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:
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:
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:
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
transactionIdis given, the line is added to that transaction. It must exist. -
Else, if a transaction with the same
terminal+externalReferenceexists, 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 |
|
|
Activity Date |
|
|
Document Type |
|
|
Lot |
Only for Fishing Trips: if no |
|
Location |
|
|
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 |
|
Weight Unit of Measure |
The item's weight unit, if |
Errors in the response (nothing is created)
-
itemNois missing -
the terminal does not exist
-
externalReferenceis 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)
-
documentNois missing -
documentTypeis not given and no document is found with thisdocumentNo
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 |
|
|
Populate Unit Automatically |
MES Terminal |
Endpoint |
Missing |
|
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 |
|
Default Purchase Document Type |
Wisefish Setup |
Processing |
Receipt Agreements: the posting document is a Purchase Order or a Purchase Invoice |