Breadcrumbs

API - Purchase Agreements

Overview

The table behind this API page is the one that contains the purchase agreements in Wisefish, which are mainly used as Receipt Agreements, but the endpoint also contains Blanket Purchase Agreements.

There are 3 endpoints with same properties, but a different fixed filter on Status and can give access to different procedures:

  1. Endpoint purchaseAgreements shows both open and posted agreements.

  2. Agreements which are open for changes, because the posting document has not been created: openPurchaseAgreements

  3. Closed agreements. these are non-editable, because the posting document has been created: closedPurchaseAgreements

Endpoint names

purchaseAgreements
openPurchaseAgreements
closedPurchaseAgreements

Source table

"WiFi Purchase Agreement Header"

Fixed view

Document Type = Blanket, Receipt

Requests allowed

GET, POST, PATCH, DELETE

Primary key

documentType, documentNo

Record ID

systemId

Procedures

release, reopen, createPostingDocument, receiveItems

Procedures

  • The record Id of the entry must be known in order to use procedures

  • The URL will be: [server]/api/wisefish/wiFiEP/v1.0/companies([CompanyGUID])/openPurchaseAgreements([record-id])/Microsoft.NAV.[procedureName]

  • Only the open purchased agreements can be modified, so if trying to run some procedures on closed agreements that are only allowed for open ones, an error should be returned that explains why.

In general, if the request is successful, the response is 200 OK and could also possibly contain a message in the value property. For example:

JSON
{
    "@odata.context": "https://api.businesscentral.dynamics.com/v2.0/b33a6a3b-244c-4295-84b3-0ad90823c736/AB_Test_191125/api/wisefish/base/v1.0/$metadata#Edm.String",
    "value": "Success"
}

Data

Field List

Property

Type

Format

Description


1

systemId

string

uuid

The record ID must be used when reading only one entry or when using procedures on the endpoint.

RECORD ID

2

documentType

string


The type of agreement. Options:

  • Receipt - a normal purchase

  • Blanket - an ongoing purchase document.

If not given when adding a new line, the default is Receipt. See Wisefish user manuals for more info.

Primary key

3

documentNo

string

max 20

The unique id within each “Document Type”

Primary key

4

status

string


Status shows if the agreement is still open or has been released. The status can only be modified with a procedure, see below.

NON-EDITABLE

5

orderDate

string

date

Order Date

optional

6

vendorOrderNo

string

max 20

Vendor Order No.

optional

7

buyFromVendorNo

string

max 20

This field is related to table Vendor.

Mandatory

8

buyFromVendorName

string

max 100

Vendor information

optional

9

buyFromVendorName2

string

max 50

Vendor information

optional

10

buyFromAddress

string

max 100

Vendor information

optional

11

buyFromAddress2

string

max 50

Vendor information

optional

12

buyFromPostCode

string

max 20

Vendor information

optional

13

buyFromCity

string

max 30

Vendor information

optional

14

buyFromCounty

string


Vendor information

optional

15

buyFromCountry

string

max 10

Vendor information

optional

16

languageCode

string

max 10


optional

17

locationCode

string

max 10

After posting, the items will be on this Location

Mandatory

18

stockCenterCode

string

max 20

After posting, the items will be on this Stock Center

Mandatory

19

externalProducer

string

max 20


optional

20

vesselCode

string

max 20

The number of a vessel (boat or ship)

optional

21

vesselName

string

max 50

The name of the vessel

NON-EDITABLE

22

landingDate

string

date

Landing date

optional

23

fishingArea

string

max 10

Fishing area code

optional

24

placeofLoading

string

max 10

Fields regarding shipping

optional

25

placeofDischarge

string

max 10

Fields regarding shipping

optional

26

placeofDelivery

string

max 10

Fields regarding shipping

optional

27

transporter

string


Fields regarding shipping

optional

28

transportMethodCode

string

max 10

Fields regarding shipping

optional

29

expectedReceiptDate

string

date

Fields regarding shipping

optional

30

amount

number


The total amount of this purchase

NON-EDITABLE

31

currencyCode

string

max 10


optional

32

postingDate

string

date

This date will be used for the ledger entries created when this is posted.

optional

33

vendorInvoiceNo

string

max 20

In order to post the purchase order, this must be given, but can be given on later stage.

Mandatory

34

getBCTIInvoice

boolean



optional

35

noOfLines

integer


Number of lines on this agreement

NON-EDITABLE

36

noOfTradeItems

number


Total number of trade items on this agreement

NON-EDITABLE

37

noOfTradeItemsAllocated

number



NON-EDITABLE

38

noOfTradeItemsReceived

number



NON-EDITABLE

39

lastModified

string

date-time

Automatic time stamp of last modification.

NON-EDITABLE

Example Object

The response with only the properties from the “Purchase Agreement Header” (not the lines, looks like this);

JSON
{
    "systemId": "b443a749-239a-f011-b41a-000d3adf9fc2",
    "documentType": "Receipt",
    "documentNo": "RA2000004",
    "status": "Released",
    "orderDate": "2025-09-25",
    "vendorOrderNo": "",
    "buyFromVendorNo": "4203690429",
    "buyFromVendorName": "Þorbjörn hf.",
    "buyFromVendorName2": "",
    "buyFromAddress": "",
    "buyFromAddress2": "",
    "buyFromPostCode": "240",
    "buyFromCity": "GRINDAVÍK",
    "buyFromCounty": "",
    "buyFromCountry": "IS",
    "languageCode": "ISL",
    "locationCode": "",
    "stockCenterCode": "",
    "externalProducer": "",
    "vesselCode": "1234",
    "landingDate": "2025-09-25",
    "fishingArea": "HALI",
    "placeofLoading": "",
    "placeofDischarge": "",
    "placeofDelivery": "",
    "transporter": "",
    "transportMethodCode": "",
    "expectedReceiptDate": "2025-09-25",
    "amount": 10000,
    "currencyCode": "",
    "postingDate": "2025-09-25",
    "vendorInvoiceNo": "",
    "getBCTIInvoice": false,
    "noOfLines": 1,
    "noOfTradeItems": 100,
    "noOfTradeItemsAllocated": 0,
    "noOfTradeItemsReceived": 0,
    "lastModified": "2025-09-30T17:14:22.093Z",
}


Usage

Read one agreement with lines

Reading one entry of this table must be done with the record Id which is in this case the systemId.

Lines are shown by adding to the URL $expand=purchaseAgreementLines

GET ... purchaseAgreements([system-id])?$expand=purchaseAgreementLines


Expand to see the example json

An example of a response:

JSON
GET ... purchaseAgreements(b443a749-239a-f011-b41a-000d3adf9fc2)?$expand=purchaseAgreementLines

{
    "@odata.context": "https://api.businesscentral.dynamics.com/v2.0/b33a6a3b-244c-4295-84b3-0ad90823c736/AB_Test_191125/api/wisefish/base/v1.0/$metadata#companies(1691e98a-6a95-f011-b41a-6045bde126e9)/purchaseAgreements/$entity",
    "@odata.etag": "W/\"JzIwOzExMTg5ODcyMDAwMzUyNTUzMzI0MTswMDsn\"",
    "systemId": "b443a749-239a-f011-b41a-000d3adf9fc2",
    "documentType": "Receipt",
    "documentNo": "RA2000004",
    "status": "Released",
    "orderDate": "2025-09-25",
    "vendorOrderNo": "",
    "buyFromVendorNo": "4203690429",
    "buyFromVendorName": "Þorbjörn hf.",
    "buyFromVendorName2": "",
    "buyFromAddress": "",
    "buyFromAddress2": "",
    "buyFromPostCode": "240",
    "buyFromCity": "GRINDAVÍK",
    "buyFromCounty": "",
    "buyFromCountry": "IS",
    "languageCode": "ISL",
    "locationCode": "",
    "stockCenterCode": "",
    "externalProducer": "",
    "placeofLoading": "",
    "placeofDischarge": "",
    "placeofDelivery": "",
    "transporter": "",
    "transportMethodCode": "",
    "expectedReceiptDate": "2025-09-25",
    "amount": 10000,
    "currencyCode": "",
    "postingDate": "2025-09-25",
    "vendorInvoiceNo": "",
    "getBCTIInvoice": false,
    "noOfLines": 1,
    "noOfTradeItems": 100,
    "noOfTradeItemsAllocated": 0,
    "noOfTradeItemsReceived": 0,
    "lastModified": "2025-09-30T17:14:22.093Z",
    "purchaseAgreementLines": [
        {
            "@odata.etag": "W/\"JzIwOzE3MjI2NDI3NTI4MzQ1MzA1NzY2MTswMDsn\"",
            "systemId": "2559e15b-239a-f011-b41a-000d3adf9fc2",
            "documentType": "Receipt",
            "documentNo": "RA2000004",
            "lineNo": 10000,
            "type": "Item",
            "itemNo": "ZZZ1003",
            "description": "Lifur - lánað til Lýsi",
            "tradeItems": 100,
            "tIUoM": "KG",
            "quantityBase": 100,
            "quantity": 100,
            "unitOfMeasureCode": "KG",
            "directUnitCost": 100,
            "unitCost": 100,
            "lineAmount": 10000,
            "lineDiscount": 0,
            "lineDiscountAmount": 0,
            "amount": 10000,
            "vat": 11,
            "amountIncludingVAT": 11100,
            "originalProducer": "",
            "productionDate": "2025-09-25",
            "netWeight": 0,
            "netWeightBWU": 100,
            "lastModified": "2025-10-02T13:18:31.53Z"
        }
    ]
}


Create an agreement with lines

JSON
POST .../purchaseAgreements?$expand=purchaseAgreementLines

Body:

{
    "orderDate": "2025-12-02",
    "buyFromVendorNo": "4203690429",
    "locationCode": "001",
    "vendorInvoiceNo": "AFH-001",
    "purchaseAgreementLines": [
        {
            "itemNo": "ZZZ1003",
            "tradeItems": 300,
            "tradeItemUnitOfMeasure": "KG",
            "productionDate": "2025-12-02"
        }
    ]
}

The response contains the the new entry, both header and lines.

Status Changes

Release

This will release the agreement, same as clicking on the Release button within BC.

JSON
POST
[server]/api/wisefish/wiFiEP/v1.0/companies([CompanyGUID])/purchaseAgreements([record-id])/Microsoft.NAV.release

(no parameters)

After a successful request:

  • The Status becomes Released.

Reopen

If an already released agreement needs to be reopened, in order to do some changes.

JSON
POST
[server]/api/wisefish/wiFiEP/v1.0/companies([CompanyGUID])/purchaseAgreements([record-id])/Microsoft.NAV.reopen

(no parameters)

After a successful request:

  • The Status becomes Open.

Posting

Create Posting Document

When all lines have been registered on the purchase agreement, the posting document can be created, i.e. either a Purchase Order or a Purchase Invoice.
Before this is run, the agreement must be released.

JSON
POST
[server]/api/wisefish/wiFiEP/v1.0/companies([CompanyGUID])/purchaseAgreements([record-id])/Microsoft.NAV.createPostingDocument

(no parameters)

After a successful request:

  • A purchase document (Purchase Order or Purchase Invoice, depends on settings) has been created for the agreement.

Receive Items

This method can be used if the API user is allowed to both created the posting document and then immediately post the items into inventory.

JSON
POST
[server]/api/wisefish/wiFiEP/v1.0/companies([CompanyGUID])/purchaseAgreements([record-id])/Microsoft.NAV.receiveItems

(no parameters)

This method does both:

  • Creates a a Purchase Order for the agreement.

  • The purchase order is posted with the “receipt” option, which means that items are in stock, and the order waits for the invoice to be created later.