The Dataloy REST API allows for the retrieval, updating and entry of all data in Dataloy VMS.

As the Dataloy API is based on REST principles it is easy to write and simple to use when testing applications.

A typical company uses many applications, of which many or most are not designed to work with one another. Integrating separate, but related, applications help organizations achieve greater levels of operational consistency, efficiency and quality. Integration can be considered if a system generates/consumes data relevant to Dataloy VMS and/or can share data with the VMS.

Dataloy REST API uses a generic search/filtering functionality. In general, all resources supports filtering on all properties of that resource and linked resources (for exceptions, see Limitations).

Syntax

The filter query parameter has the following format:

Example that will return currency information for USD:

Syntax Breakdown <Base URL>

For more information see Getting Started with Dataloy REST API

<Resource>

Can be any of the Resources available in the Dataloy API.

<json property>

Can be any json property of the resource (for exceptions, see Limitations).

<OPERATOR>

The operator is always:

• surrounded by parenthesis

• is always upper case

List of Operators

<value>

• Numeric Values are straight forward. Can be integers or decimal numbers using a dot as decimal point.

• Dates must be specified in the format: yyyy-MM-ddTHH:mm:ss

• Strings can be surrounded by double quotes, but it is generally not necessary. Even if the string has spaces.

• Boolean must be specified with 0 for false and 1 for true.

Combining Filters

The filter URL parameter can be added multiple times to filter on multiple properties in one request. To do so, add a new filter parameter to the end of the URL

Syntax for Combining Filters

Example:

Properties for Sub Objects

Filters can be used for sub objects by using a "dot path". Example of a sub object is commodity on Cargo:

Part of the Cargo resource as an example:
  
{
    "cargoReference": 12345,
    "freight": 20000,
    "cargoQuantity":100000,
    "commodity": {
            "commodityName": "Steel",
            "commodityCode": "10000",
            "key": 1069734,
            "self": "http://localhost:8080/ws/rest/Commodity/1069734"
    }
}

To search for cargoes with commodity steel:

Limitations

The following properties are currently not possible for filtering:

• self

• remarks

A few other properties are unsupported, these are documented for each resource.

Examples

Cargo

Get Cargo with freight more than 1000000 and freightCurrency USD or EUR:

Document

Get Documents with documentType "INV" and invoicingStatus "PEN"

Voyage

Get Voyages for the vessel with vessel code ABRA

Get Voyage with reference number VES100

Get Voyage with start date > 01.01.2016 and operator is user with userCode "BAK"

Get Voyages that are operational for vessel ABRA

Get all Voyages that has Oslo as Load Port in 2015

Getting Started with Dataloy REST API (Application Programming Interface) provides an introduction to the Dataloy API directed towards developers and IT-personnel. Basics, such as how to obtain, submit and modify data, are explained.

Dataloy’s API uses a REST interface over HTTP/HTTPS. The currently supported payload is application/JSON.

To Get Started

Follow the below steps - they will return USD currency from Dataloy VMS (illustrating that the API works properly):

https://[ip]:[port]/ws/rest/Currency?filter=currencyCode(EQ)USD

Request Format

For POST and PUT requests, the payload must be JSON and the Content-Type be set to application/JSON.

Base URL

The base URL is customer-specific. To obtain the IP-address and port for the specific API installation, please contact Dataloy.

https://[ip]:[port]/ws/rest

IMPORTANT: All URLs in this documentation is relative to the root URL stated below. The HTTP method will be written in front of the relative URL: Note: The root URL should NOT be hardcoded in your application to allow it to run against multiple servers. The "/ws/rest" part may also change in the future.

GET /Cargo/123456

Example: When the documentation refers to /Cargo, the full URL is https://[ip]:[port]/ws/rest/Cargo.

General URL Structure

Resources (for example: Voyage, Document, ExchnangeRate), have a similar general URL structure. Example: In the table below "/Entity" represents the name of an entity type like "/Cargo" or "/Voyage".

Exception Handling

Dataloy's API return HTTP status codes in the HTTP header and provides additional information in the body in JSON format.

{
    "statusCode": 400,
    "statusText": "Bad Request",
    "message": "Missing field(s) in json body. All fields are required.",
    "date": "2013-02-05T09:49:52",
    "statusFamily": null,
    "method": null,
    "uri": null
}

Retrieve Data from Dataloy API

Information is retrieved by using a GET request on a URL. Each resource has it’s own URL. The API also supports searching resource specific parameters.

GET request on a URL:

Example: The following GET request on example URL will return the document with ID 2729538.

Filtering Data

Dataloy API is equipped with a strong generic filtering functionality. It is able to filter on almost any field visible in the API and filtering any resources returning an array of objects (see Filtering).

Modifying Data Through Dataloy API (PUT)

Use PUT to modify data through the API. Specify the URL of a resource and send the content to be modified in the body of the HTTP call. A successful PUT will return the same body as a GET on that resource. Excluded properties will be ignored. Excluded array elements will be removed. From API version 3, PUT will also update Sub-objects, previous versions are limited to object by object updating. For API versions prior to version 3, Sub-objects should NOT be included in PUT requests.

Examples:

Updating properties for a main object. In this case VoyageHeader

{
   "doProfitLoss": 1.1,
   "tradeVoyageNo": 2345,
   "isBudget": true,
   "voyageStartDate": "2017-03-01T01:58:00",
   "referenceNo": "12341"
}

Updating properties for a sub-object. In this case, Voyage is the main object and Cargo is the sub-object

{
    "cargos": [
        {
            "bookedQuantity": 10000        
        }
    ]
}

Insert an array element

{
  "remarks": [
      {
           "remarkTitle": "A Test remark title 1"
      }
   ]
}

Update an array element by including the key for the array element. The key is generated by the API when inserting a new element.

{
  "remarks": [
      {
           "key": 234581088,
           "remarkTitle": "A Test remark title 1 Updated"
      }
   ]
}

Insert a second array element by including the key for the first array element. Then add a second array element without a key.

{
  "remarks": [
      {
           "key": 234581088,
           "remarkTitle": "A Test remark title 1 Updated"
      },
       {
           "remarkTitle": "A Test remark title 2"
      }
   ]
}

Remove an array element. When having two elements in an array, you can remove one of them by removing the element in the PUT body

{
  "remarks": [
      {
           "key": 234581088
      }
   ]
}

Sub-objects

Inserting (POST) or updating (PUT) references to sub-objects can be done in different ways: (All the examples below is using VoyageHeader as a main object and the specified company will be linked to the VoyageHeader.)

Specify the key to an existing sub-object

All existing objects has a key that is created by Dataloy API. This can be used for linking an existing object to another object.

{   "company":4601029}

Specify the code to an existing sub-object

A lot of the objects in Dataloy API has an unique code that can be used for identifying an object. This code can also be used for linking an existing object to another object.

{   "company": "09"}

Specify the sub-object

Another option for linking a sub-object is to provide the object to be linked.

{   "company": {       "key": 163348582   }}

Create a new object

The last option is to create a new sub-object and link it to a object in the same request. When excluding the key property a new object will be created.

{
   "company": {       
       "companyCode": "1234",
       "companyName": "Test Company"
   }
}

Inserting Data Through Dataloy API (POST)

Send a POST request to a base resource URL with a body conforming with the minimum requirements of that resource.

Example: POST request URL:

Body of Document HTTP POST

{
    "documentAmount": 0.0,
    "companyCurrencyAmount": 0.0,
    "sourceCurrencyAmount": 0.0,
    "documentDate": "2013-04-04T00:00:00",
    "documentType": "PMI",
    "invoicingStatus": "POS",
    "documentNo": "XXXXXX",
    "company": 10001,
    "documentCurrency": "USD",
    "documentText": "text here",
    "businessPartner": 20002,
    "documentLinesFromDocument":
    [
        {
            "documentAmount": 0.0,
            "companyCurrencyAmount": 0.0,
            "sourceCurrencyAmount": 0.0,
            "sourceCurrency": "USD",
            "refDocument": "52011962",
            "documentLineText": "text here",
            "isAccountsPayable": "true",
            "businessPartner": "16959"
        }
    ]
}

Generic Dataloy API Fields

The following fields exist for all Dataloy VMS API resources:

Date Format

From version 2.0.0 the date format has been changed to conform ISO 8601:

yyyy-MM-ddThh:mm:ss Example: 2014-01-01T00:00:00

Versions prior to 2.0.0:

Date format for JSON messages: yyyy-MM-dd hh:mm:ss Example: 2014-01-01 00:00:00 Date format for filtering: yyyy-MM-ddThh:mm:ss Example: 2014-01-01T00:00:00

REST - Representational State Transfer

A quick introduction to REST is available at http://www.infoq.com/articles/rest-introduction.

JSON - JavaScript Object Notation

JSON is a text format that is natively supported by Javascript. It is less verbose than XML and is easier for users to read. JSON is not written in order, so fields might change position between calls. A quick introduction: http://www.json.org/

Tools for Simple Tests

Several tools are available to aid the testing of the API. This enables a payload to be sent to a URL with a specific type of request, for example, GET, PUT, POST.

Examples of available tools (but NOT limited to):

Chrome:

• Advanced REST client: https://chrome.google.com/webstore/search/advanced%20rest%20client

• Postman: https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en-US

Firefox:

• Poster: https://addons.mozilla.org/en-us/firefox/addon/poster/

Note: Dataloy recommends tools like JSONView to Chrome (to browse the API more conveniently when developing).

Documentation of API resources is currently in progress. Presently the reference documentation is manually updated. (More Information: Accounting Integration API).

It is possible sort the result of any search. The following type of sorting are supported:

• ASCENDING (ascending order, case - or database sensitive)

• ASCENDING INSENSITIVE (ascending order, case-insensitive)

• DESCENDING (descending order, case - or database - sensitive)

• DESCENDING INSENSITIVE (descending order, case-insensitive)

ASCENDING

http://localhost:8080/ws/rest/Vessel?sort=vesselName(AS)

ASCENDING INSENSITIVE

http://localhost:8080/ws/rest/Vessel?sort=vesselName(ASI)

DESCENDING

http://localhost:8080/ws/rest/Vessel?sort=vesselName(DS)

DESCENDING INSENSITIVE

http://localhost:8080/ws/rest/Vessel?sort=vesselName(DSI)

It is possible use sorting in combination with any filter and pagination:

http://localhost:8080/ws/rest/Vessel?sort=vesselName(DSI)&filter=flag.countryCode(EQ)HK&pageNumber=4&limit=10

Authentication and authorization is done through OAuth 2.

To get access to the protected resources OAuth 2.0 uses Access Tokens. An Access Token is a string representing the granted permissions.

To access to Dataloy API, you must request an Access Token.

To obtain an access token you need to do a POST request, to the provided URL, passing the client id and client secret in the payload

Example of POST payload to token URL

{
"client_id":"G99j845dM4MtckQlKt8E6o......",
"client_secret":"-mMElVOMzvht2SyQPfVh-WIaPCbOxRdWN5YngBxtBKybQmli-....",
"audience":"https://dataloy.internal",
"grant_type":"client_credentials"
}

Parameters

Response

If all goes well, you'll receive an HTTP 200 response with a payload containing access_token, token_type, and expires_in values:

{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1....................fXClgZe2pFQBxPqARz9xfWlrFnc1El34ZPyRLoGlLIJLiE0NvOA1JLWycXCNo9N7AenAKEbj-gb2eW4TnpAiidDRmMV3m36UCuRAxWdVcvsRaJxXcquf79wAgEoEKriJklCxwKOnOyngbTZ2vDNim0nrw6-W0NOjRARkkY_w-188dY829z_urjsWuCC7TOMwfrQDLL2h72L2UrqlyL0hHMGQesau6h8KUsGg3EIoWPQ-Pf6o2CNCtGyr7DNuuLpCw9HqXiz5v-RIvKLBoaRMAAJJqBeXvpPvOcyicBlalcTWB5NMCe6Ldi9xqFmwjhO1CAtIk9QUa8wsOcXxg",
"expires_in": 86400,
"token_type": "Bearer"
}

Call API endpoint

To call an API endpoint you must pass the retrieved Access Token as a Bearer token in the Authorization header of your HTTP request.

curl https://{URL}/ws/rest/{Resource}-H "Authorization: Bearer eyJ.........qLbZQ"

When an endpoint is invoked with an expired token the server sends a HTTP 401 response with the following payload:

{
    "statusCode": 401,
    "statusText": "Unauthorized",
    "message": "Token expired.",
    "date": "2019-11-13T06:26:01",
    "statusFamily": "CLIENT_ERROR",
    "method": "GET",
    "uri": "http://platform-dev.dataloy.com/ws/rest/Cargo?filter=subCargos.freight%28GTE%292500000"

The client should not ask for a new token for each call but use the same token as long as it is valid.

It is possible to adjust the number of fields that have to be returned from a resource. It's possible to both increase and decreases the number of fields from the default view. So if only field A and B from a resource is needed and the other X number of fields can be ignored, it can be specified in the header of the request. This will reduce the overhead of data transferred and improve performance. If more fields are needed in one request, to avoid making a second request to get all the data that is needed, this can also be done. So if fields A, B and C are returned in the default view, but also field D is needed, this can be specified in the header.

Customize the Number of Fields returned

Retrieving data from a resource may provide more information than needed. Fields with data to be returned can be specified by first adding a header field and then specifying the fields to be returned in the header field value. The header field value is specified as a JSON message following the same structure as the resource structure that is used when making the request. This enables fields to be specified in main- and sub-objects.

The examples listed illustrate how it is used for a business partner. The procedure is, however, the same for all resources. The key and self attribute will always be returned, but the number of displayed/hidden fields can be customized.

Business Partner without any field restriction will result in ( view example):

{
    "businessPartnerName": "Big Customer",
    "businessPartnerSort": "BIG.",
    "businessPartnerCode": "45999",
    "codeProperty": "businessPartnerCode",
    "bankAccounts": [],
    "individuals": [],
    "user": null,
    "createdDate": "2014-01-27T18:38:52",
    "changedById": 3689599,
    "createdById": 1045293,
    "externalObjectKey": null,
    "modifiedDate": "2024-09-29T10:59:34",
    "portAgentType": null,
    "bankAccount": null,
    "paymentTerms": {
        "key": 1004281,
        "self": "https://dev.dataloy.com/ws/rest/PaymentTerms/1004281"
    },
    "businessUnit": {
        "key": 1000576,
        "self": "https://dev.dataloy.com/ws/rest/BusinessUnit/1000576"
    },
    "baselineTerm": {
        "key": 1004265,
        "self": "https://dev.dataloy.com/ws/rest/BaselineTerm/1004265"
    },
    "contactInfo": [
        {
            "key": 5987711,
            "self": "https://dev.dataloy.com/ws/rest/ContactInfo/5987711"
        }
    ],
    "businessPartnerName2": null,
    "companyRegistrationNo": "987987987",
    "isInterCompany": false,
    "isTotalCommissionPayable": false,
    "maxAdvancePaymentPercent": 100,
    "rating": null,
    "ratingExpiryDate": null,
    "vatNumber": null,
    "addresses": [
        {
            "key": 5993125,
            "self": "https://dev.dataloy.com/ws/rest/Address/5993125"
        }
    ],
    "businessPartnerLink": {
        "key": 1004433,
        "self": "https://dev.dataloy.com/ws/rest/BusinessPartner/1004433"
    },
    "businessPartnerType": {
        "key": 1000032,
        "self": "https://dev.dataloy.com/ws/rest/BusinessPartnerType/1000032"
    },
    "companyBankAccount": null,
    "www": [
        {
            "key": 5987713,
            "self": "https://dev.dataloy.com/ws/rest/Www/5987713"
        }
    ],
    "payee": {
        "key": 1004433,
        "self": "https://dev.dataloy.com/ws/rest/BusinessPartner/1004433"
    },
    "remarks": [],
    "isObjectActive": true,
    "key": 1045574,
    "self": "https://dev.dataloy.com/ws/rest/BusinessPartner/1045574"
}

Examples

1. Return Business Partner name only:

fields: {"businessPartnerName":"*"}

{
  "businessPartnerName": "Big Customer",
  "self": "https://dev.dataloy.com/ws/rest/BusinessPartner/1045574",
  "key": 1045574
}

2. Return address1 only:

fields: {"addresses": {"address1":"*"}}

{
  "addresses": [
    {
      "address1": "Halfdan Kjerulfs gate 4",
      "key": 5993125,
      "self": "https://dev.dataloy.com/ws/rest/Address/5993125"
    }
  ],
  "self": "https://dev.dataloy.com/ws/rest/BusinessPartner/1045574",
  "key": 1045574
}

3. Return Business Partner name and address1:

fields: {"businessPartnerName":"*", "addresses":{"address1":"*"}}

{
  "businessPartnerName": "Big Customer",
  "addresses": [
    {
      "address1": "Halfdan Kjerulfs gate 4",
      "key": 5993125,
      "self": "https://dev.dataloy.com/ws/rest/Address/5993125"
    }
  ],
 "self": "https://dev.dataloy.com/ws/rest/BusinessPartner/1045574",
 "key": 1045574
}

4. Return all BusinessPartner and its BusinessUnit fields:

fields: {"all":"*", "businessUnit":{"all":"*"}}

{
    "businessPartnerName": "Big Customer",
    "businessPartnerSort": "BIG.",
    "businessPartnerCode": "45999",
    "codeProperty": "businessPartnerCode",
    "bankAccounts": [],
    "individuals": [],
    "user": null,
    "createdDate": "2014-01-27T18:38:52",
    "changedById": 3689599,
    "createdById": 1045293,
    "externalObjectKey": null,
    "modifiedDate": "2024-09-29T10:59:34",
    "portAgentType": null,
    "bankAccount": null,
    "paymentTerms": {
        "key": 1004281,
        "self": "https://dev.dataloy.com/ws/rest/PaymentTerms/1004281"
    },
    "businessUnit": {
        "key": 1000576,
        "self": "https://dev.dataloy.com/ws/rest/BusinessUnit/1000576",
        "codeProperty": "businessUnitCode",
        "createdDate": "2004-04-29T19:20:03",
        "changedById": 30037916,
        "createdById": 999999,
        "externalObjectKey": null,
        "modifiedDate": "2024-10-22T08:38:11",
        "voyageCurrency": {
            "key": 400132,
            "self": "https://dev.dataloy.com/ws/rest/Currency/400132"
        },
        "businessUnitName": "Dry Bulk",
        "businessUnitCode": "DRY",
        "users": [
            {
                "key": 999999,
                "self": "https://dev.dataloy.com/ws/rest/User/999999"
            },
            {
                "key": 1046662,
                "self": "https://dev.dataloy.com/ws/rest/User/1046662"
            },
            {
                "key": 1511445,
                "self": "https://dev.dataloy.com/ws/rest/User/1511445"
            },
            {
                "key": 2351470,
                "self": "https://dev.dataloy.com/ws/rest/User/2351470"
            },
            {
                "key": 2424912,
                "self": "https://dev.dataloy.com/ws/rest/User/2424912"
            },
            {
                "key": 5992348,
                "self": "https://dev.dataloy.com/ws/rest/User/5992348"
            },
            {
                "key": 6078354,
                "self": "https://dev.dataloy.com/ws/rest/User/6078354"
            },
            {
                "key": 8321684,
                "self": "https://dev.dataloy.com/ws/rest/User/8321684"
            },
            {
                "key": 9500018,
                "self": "https://dev.dataloy.com/ws/rest/User/9500018"
            },
            {
                "key": 10016596,
                "self": "https://dev.dataloy.com/ws/rest/User/10016596"
            },
            {
                "key": 11508528,
                "self": "https://dev.dataloy.com/ws/rest/User/11508528"
            },
            {
                "key": 11603321,
                "self": "https://dev.dataloy.com/ws/rest/User/11603321"
            },
            {
                "key": 13953540,
                "self": "https://dev.dataloy.com/ws/rest/User/13953540"
            },
            {
                "key": 13953633,
                "self": "https://dev.dataloy.com/ws/rest/User/13953633"
            },
            {
                "key": 20618402,
                "self": "https://dev.dataloy.com/ws/rest/User/20618402"
            },
            {
                "key": 21635445,
                "self": "https://dev.dataloy.com/ws/rest/User/21635445"
            },
            {
                "key": 23723095,
                "self": "https://dev.dataloy.com/ws/rest/User/23723095"
            }
        ],
        "securityGroupAliases": [],
        "remarks": [],
        "isObjectActive": true
    },
    "baselineTerm": {
        "key": 1004265,
        "self": "https://dev.dataloy.com/ws/rest/BaselineTerm/1004265"
    },
    "contactInfo": [
        {
            "key": 5987711,
            "self": "https://dev.dataloy.com/ws/rest/ContactInfo/5987711"
        }
    ],
    "businessPartnerName2": null,
    "companyRegistrationNo": "987987987",
    "isInterCompany": false,
    "isTotalCommissionPayable": false,
    "maxAdvancePaymentPercent": 100,
    "rating": null,
    "ratingExpiryDate": null,
    "vatNumber": null,
    "addresses": [
        {
            "key": 5993125,
            "self": "https://dev.dataloy.com/ws/rest/Address/5993125"
        }
    ],
    "businessPartnerType": {
        "key": 1000032,
        "self": "https://dev.dataloy.com/ws/rest/BusinessPartnerType/1000032"
    },
    "companyBankAccount": null,
    "www": [
        {
            "key": 5987713,
            "self": "https://dev.dataloy.com/ws/rest/Www/5987713"
        }
    ],
    "remarks": [],
    "isObjectActive": true,
    "key": 1045574,
    "self": "https://dev.dataloy.com/ws/rest/BusinessPartner/1045574"
}

To return a defined number of objects for any Dataloy resource it has to be specified in the URL the page number, pageNumber parameter, and the number of objects that the page has to contain, limit parameter. For example:

/ws/rest/Document?pageNumber=1&limit=10&filter=documentAmount(GT)100000

it will return the first page containing at max 10 Document objects having the property documentAmount greater than 100000. In the response will be added an header parameter called totalObjectsNumber that indicates the total number of objects of the endpoint.

From API 5.18 is possible to avoid to get totalObjectsNumber sending the HTTP header parameter noCount = YES, this will allow a bit better performance.

Another example:

/ws/rest/Vessel?filter=flag.countryCode(EQ)HK&pageNumber=4&limit=10

it will return the fourth page containing at max 10 Vessels objects having the countryCode property equals to EQ.

Get updates for nominated and operational voyages in Master scenario:

{
    "eventType":"U",
    "user": "your user code",
    "objectType":"Voyage",
    "expression": "dlpObject.getVoyageHeader() != null && (dlpObject.getVoyageHeader().getVoyageStatus().getStatusTypeCode().equals(\"NOM\") || dlpObject.getVoyageHeader().getVoyageStatus().getStatusTypeCode().equals(\"OPR\")) && dlpObject.getVoyageHeader().getIsBudget().equals(false) && dlpObject.getVoyageHeader().getIsTemplate().equals(false) &&dlpObject.getVoyageHeader().getIsEstimate().equals(false) && dlpObject.getVoyageHeader().getIsUnallocated().equals(false) && dlpObject.getScenarios() != null && dlpObject.getScenarios().size() > 0 && dlpObject.getScenarios().get(0).getScenarioCode().equals(\"MASTER\")",
    "onlyMainObject": true,
    "url": "",
    "webhookUsername": "",
    "webhookPassword": ""
}

Get notification when an invoice is posted and ready to be transferred to accounting. Set the status to Posted when it's transferred to accounting. For more information about accounting integration see: https://dataloy-cloud.atlassian.net/wiki/spaces/VMSINT/pages/923414837

{
    "eventType":"U",
    "user": the user code to be used in the subscription,
    "objectType":"Document",
    "expression": "dlpObject.getInvoicingStatus() != null && dlpObject.getInvoicingStatus().getStatusTypeCode().equals(\"RFP\") && (dlpObject.getDocumentType().getDocumentType().equals(\"INO\") || dlpObject.getDocumentType().getDocumentType().equals(\"INI\") || dlpObject.getDocumentType().getDocumentType().equals(\"CRI\") || dlpObject.getDocumentType().getDocumentType().equals(\"CRO\"))",
    "onlyMainObject": true,    
    "url": "your webhook url"
}

Get notified when accruals are posted and and ready to be transferred to accounting. Set the status to Posted when it's transferred to accounting. For more information about accounting integration see: https://dataloy-cloud.atlassian.net/wiki/spaces/VMSINT/pages/923414837

{
    "eventType":"U",
    "user": the user code to be used in the subscription,
    "objectType":"Document",
    "expression": "dlpObject.getInvoicingStatus() != null && dlpObject.getInvoicingStatus().getStatusTypeCode().equals(\"RFP\") && (dlpObject.getDocumentType().getDocumentType().equals(\"ACR\") || dlpObject.getDocumentType().getDocumentType().equals(\"ACP\"))",
    "onlyMainObject": true,    
    "url":"your webhook url"
}

Webhooks

Webhooks are user-defined HTTP callbacks that receive events for the subscribed event types. Webhook notifications are asynchronous, the order is not guaranteed.

Events are categorised into event types. Events occur due to changes in the state of a resource, such as when a voyage is updated. When an event occurs, the registered applications are notified via HTTP POST. The POST contains the event details, including the event type that caused the event.

When an application receives the event, it must respond with a 200-level HTTP status code.

Subscription

When a webhook subscription is made, through the resource WebhookSubscription, for a Dataloy object, BunkerOrder for instance, the subscribed webhook will be pushed with all the changes that occurred to the subscribed object and its object hierarchy. So if a PortCall of the subscribed BunkerOrder is updated the webhook will be notified.

The Dataloy webhook event type is a concatenation of the following attributes:

• Resource name (Document, Voyage, ..)

• Operation type (C,U, D create, update, delete)

• Object key

The user can subscribe to a webhook for a given event, for example:

The message sent to the subscribed endpoint is set in the body of the POST method. The message is a JSON object and has the following structure:

{
 "id": "1573335-244070007",
 "eventTime": "2016-09-14T13:37:26",
 "objectType": "PortCall",
 "eventType": "U",
 "dataloyObject":189126972,
 "dataloyObjectSelf":"http://localhost:8080/ws/rest/PortCall/7823672"
 "subscription":{
            "key":243885046,
            "self":"http://localhost:8080/ws/rest/WebhookSubscription/243885046"
            "objectType":"BunkerOrder",
            "dataloyObject":244070007,
            "eventType": "U",
             "url":"http://test1.dataloy.com:8080/webhook/"
   }
"resource":{ 
      "key":244070007,
      "self":"http://localhost:8080/ws/rest/BunkerOrder/244070007",
      "vessel":{ 
         "vesselName":"VESSEL1",
         "key":188616815,
         "self":"http://localhost:8080/ws/rest/Vessel/188616815"
      },
      "currency":{ 
         "currencyCode":"USD",
         "currencyName":"U.S. DOLLAR",
         "key":400132,
         "self":"http://localhost:8080/ws/rest/Currency/400132"
      },
      "exchangeRate":3.0,
      "modifiedDate":"2016-09-21T06:38:29",
      "portCall":{ 
         "key":189126972,
         "self":"http://localhost:8080/ws/rest/PortCall/189126972",
         "eventLogs":[ 
            { 
               "key":189126978,
               "self":"http://localhost:8080/ws/rest/EventLog/189126978",
               "event":{ 
                  "key":1000052,
                  "self":"http://localhost:8080/ws/rest/Event/1000052",
                  "eventCode":"DEP",
                  "eventDesc":"Departed"
               },
               "eventLogDate":"2015-02-13T17:18:00"
            },
            { 
               "key":189126974,
               "self":"http://localhost:8080/ws/rest/EventLog/189126974",
               "event":{ 
                  "key":1000050,
                  "self":"http://localhost:8080/ws/rest/Event/1000050",
                  "eventCode":"ARR",
                  "eventDesc":"Arrived"
               },
               "eventLogDate":"2015-02-06T20:18:00"
            },
            { 
               "key":189126976,
               "self":"http://localhost:8080/ws/rest/EventLog/189126976",
               "event":{ 
                  "key":1000051,
                  "self":"http://localhost:8080/ws/rest/Event/1000051",
                  "eventCode":"BRT",
                  "eventDesc":"Berthed"
               },
               "eventLogDate":"2015-02-07T10:06:00"
            }
         ]
      },
      "extraCost":0.0,
      "bunkeredDate":"2016-01-01T00:00:00",
      "orderDate":"2016-09-06T10:16:36",
      "bunkerPaidBy":null,
      "createdDate":"2016-09-21T06:12:42",
      "createdById":999999,
      "bunkerOrderStatus":{ 
         "key":243093653,
         "self":"http://localhost:8080/ws/rest/StatusType/243093653",
         "statusTypeDesc":"Requirement",
         "statusTypeCode":"REQBO"
      },
      "externalReferenceNo":null,
      "bunkerOrderLines":[ 
         { 
            "key":244070009,
            "self":"http://localhost:8080/ws/rest/BunkerOrderLine/244070009",
            "minQuantity":50.0,
            "maxQuantity":100.0,
            "extraCost":0.0,
            "bunkeredQuantity":111.0,
            "unitPrice":100.0,
            "bunkerType":{ 
               "key":73564540,
               "self":"http://localhost:8080/ws/rest/BunkerType/73564540",
               "isoCode":null,
               "isoYear":null,
               "bunkerTypeCode":"FO",
               "bunkerTypeDesc":"FO",
               "sulphurPercent":null
            }
         }
      ],
      "company":null,
      "bunkerBroker":{ 
         "businessPartnerName":"BUSINESS PARTNER 1",
         "businessPartnerSort":"BUSINESS PARTNER 1",
         "businessPartnerCode":"1111",
         "businessPartnerType":{ 
            "businessPartnerType":"BS",
            "businessPartnerTypeDesc":"Bunker Supplier",
            "key":1000034,
            "self":"http://localhost:8080/ws/rest/BusinessPartnerType/1000034"
         },
         "key":39697371,
         "self":"http://localhost:8080/ws/rest/BusinessPartner/39697371"
      },
      "bunkerAccountOf":null,
      "bunkerSupplier":{ 
         "businessPartnerName":"BUSINESS PARTNER 2",
         "businessPartnerSort":"BUSINESS PARTNER 2",
         "businessPartnerCode":"22222",
         "businessPartnerType":{ 
            "businessPartnerType":"BS",
            "businessPartnerTypeDesc":"Bunker Supplier",
            "key":1000034,
            "self":"http://localhost:8080/ws/rest/BusinessPartnerType/1000034"
         },
         "key":39697206,
         "self":"http://localhost:8080/ws/rest/BusinessPartner/39697206"
      },
      "remarks":[ 
 
      ]
   }
}

The attributes have the following meaning:

New functionalities since version 3.9

With API 3.9 the following new functionalities have been introduced:

• Possibility to be notified of changes via email

• Possibility to customize the JSON pushed as Adjust Number of Fields to be Returned from a Request

• Possibility to filter changes that have to be pushed via expressions

• Possibility to filter changes that have to be pushed via scripts

Notifications via email

To be notified via email in the WebhookSubscription must be specified the channelInfo property with channelType EMAIL and the URL with the email address:

{
       "channelInfo": {
           "url": "info@dataloy.com",
           "channelType": "EMAIL"
       }
   }

channelType can be EMAIL or HTTP if HTTP is set the URL attribute must contain the endpoint where to push notifications.

Possibility to customize the JSON pushed

Through the attribute JSON of WebhookSubscription is possible to specify which attributes of the object must be pushed (see Adjust Number of Fields to be Returned from a Request). The value of JSON must be encoded with Base64.

For instance, if the subscription is for the object BunkerOrderLine a possible value for the JSON attribute could be:

{"extraCost":"*"}

that encoded will be

"json": "ew0KCSJleHRyYUNvc3QiOiIqIg0KfQ=="

In this way the sub-object in the attribute resource will be smaller:

{ 
   "id":"245-320996749",
   "eventTime":"2018-01-30T10:42:11",
   "eventType":"U",
   "objectType":"BunkerOrderLine",
   "dataloyObject":320996749,
   "dataloyObjectSelf":"http://platform-dev.dataloy.com:80/ws/rest/BunkerOrderLine/320996749",
   "subscription":{ 
      "key":332501529,
      "self":"http://platform-dev.dataloy.com:80/ws/rest/WebhookSubscription/332501529",
      "isSubscriptionActive":true,
      "user":{ 
         "key":999999,
         "self":"http://platform-dev.dataloy.com:80/ws/rest/User/999999",
         "userCode":"DATALOY",
         "userName":"dataloy"
      },
      "objectType":null,
      "dataloyObject":null,
      "url":null,
      "dlpAlertScript":{ 
         "key":318269643,
         "self":"http://platform-dev.dataloy.com:80/ws/rest/DlpAlertScript/318269643",
         "scriptCode":"BUP",
         "scriptName":"Bunkered Unit Price updated"
      },
      "eventType":null,
      "unsubscriptionDate":null,
      "channelInfo":{ 
         "key":332501528,
         "self":"http://platform-dev.dataloy.com:80/ws/rest/ChannelInfo/332501528",
         "channelType":{ 
            "key":311504704,
            "self":"http://platform-dev.dataloy.com:80/ws/rest/ChannelType/311504704",
            "channelTypeCode":"EMAIL"
         },
         "url":"ab@dataloy.com"
      }
   },
   "resource":{ 
      "key":320996749,
      "self":"http://platform-dev.dataloy.com:80/ws/rest/BunkerOrderLine/320996749",
      "extraCost":0.0
   }
}

Possibility to filter changes that have to be pushed via expressions

Through the attribute expression of WebhookSubscription is possible to write a Java expression against the object changed. At runtime If the expression return true the notification will be sent, otherwise no.

For instance, if the subscription is done for the object BunkerOrderLine a possible expression could be:

that for any changes at any BunkerOrderLine object will check if the unit price is not null and its value is between 10 and 100, if yes the notification will be sent.

In the expression must be used the variable dlpObject to refer to the changed object, the object will contain the new values. If the expression needs to check also the previous values of the object, the variable oldDlpObject can be used.

For instance:

that will check if the new extra cost of a BunkerOrder is greater than the previous one.

If you want to be notified when an attribute change value from null to not null:

The old values will be accessible only for those Dataloy object changed via Dataloy API.

Possibility to filter changes that have to be pushed via scripts

Contact Dataloy to have info regarding scripts.

New functionalities since version 3.16

In version 3.16 (and later) it is possible to decide if a webhook subscription should only be notified on changes to the object subscribed. So for instance making a subscription for the Voyage object, the changes that will occur to linked objects, like PortCall, Cargo, etc, will be not notified. To achieve this behaviour a new boolean attribute called onlyMainObject in WebhookSubscription has been added, setting it to true only the changes for the subscribed will be sent.

A new endpoint in WebhookSubscription POST:sendFailedNotifications has been added to resend manually the failed webhook notification.

New functionalities since version 5.23

In version 5.23 (and later) it is possible to decide if a webhook subscription should only be notified with the raw object, without the envelope payload. To achieve this behavior a new boolean attribute called rawObject in WebhookSubscription has been added, setting it to true the raw object will be sent.

New functionalities since version 5.24

A new attribute xsl has been added which allows you to store an XSL stylesheet to transform the subscribed object to XML. The value of the field must be encoded with Base64. This is part only of Enterprise API.

New functionalities since version 6.44

In order to not get notified by the changes done by the user of the subscription the attribute notSendMyChanges can be set to true.

Supported Methods

GET /WebhookSubscription

Get a list of WebhookSubscription objects. Filter to avoid huge amounts of data (see Filtering documentation for examples).

GET /WebhookSubscription/{key}

Get a single WebhookSubscription object.

Example GET Return Body

{
  "key": 243907762,
  "self": "http://localhost:8080/ws/rest/WebhookSubscription/243907762",
  "isSubscriptionActive": true,
  "unsubscribed": false,
  "eventType": "U",
  "dataloyObject": 243896793,
  "createdDate": "2016-09-16T08:35:46",
  "modifiedDate": "2016-09-16T08:35:46",
  "createdById": 999999,
  "objectType": "BunkerOrder",
  "user": {
    "key": 999999,
    "self": "http://localhost:8080/ws/rest/User/999999",
    "userName": "dataloy",
    "userCode": "DATALOY"
  },
  "url": "http://test1.dataloy.com:8080/webhook/",
  "unsubscriptionDate": null,
  "webhookUsername": null,
  "webhookPassword": null,
  "remarks": []
}

since API 3.9:

{
    "key": 320298564,
    "self": "http://platform-dev.dataloy.com:80/ws/rest/WebhookSubscription/320298564",
    "isSubscriptionActive": true,
    "unsubscribed": false,
    "user": {
        "key": 999999,
        "self": "http://platform-dev.dataloy.com:80/ws/rest/User/999999",
        "userCode": "DATALOY",
        "userName": "dataloy"
    },
    "objectType": "BunkerOrder",
    "createdDate": "2018-01-11T10:53:14",
    "url": "http://platform-dev.dataloy.com/ws/rest/dataloy/sendJson",
    "modifiedDate": "2018-01-11T10:53:14",
    "createdById": 999999,
    "dataloyObject": null,
    "expression": null,
    "dlpAlertScript": null,
    "eventType": "U",
    "unsubscriptionDate": null,
    "scriptParameterValues": [],
    "useMsg": false,
    "json": "{}",
    "webhookPassword": "XXX",
    "webhookUsername": "dataloy",
    "channelInfo": null,
    "remarks": []
}

POST /WebhookSubscription

Create a new WebhookSubscription.

Examples

Create a subscription to get notifications when the BunkerOrder with primary key 243896793 is updated:

{
    "eventType":"U",
    "user":999999,
    "objectType":"BunkerOrder",
    "dataloyObject":243896793,
    "url":"http://test1.dataloy.com:8080/webhook/"
     
}

Create a subscription to get notifications when any BunkerOrder is updated:

{
    "eventType":"U",
    "user":999999,
    "objectType":"BunkerOrder",
    "url":"http://test1.dataloy.com:8080/webhook/"
     
}

Create a subscription to get notifications when a BunkerOrder is created:

{
    "eventType":"C",
    "user":999999,
    "objectType":"BunkerOrder",
    "url":"http://test1.dataloy.com:8080/webhook/"
     
}

Create a subscription to get notifications when the BunkerOrder with primary key 243896793 is deleted:

{
    "eventType":"D",
    "user":999999,
    "objectType":"BunkerOrder",
    "dataloyObject":243896793,
    "url":"http://test1.dataloy.com:8080/webhook/"
     
}

Create a subscription to get notifications when any BunkerOrder is deleted:

{
    "eventType":"D",
    "user":999999,
    "objectType":"BunkerOrder",
    "url":"http://test1.dataloy.com:8080/webhook/"
     
}

Create a subscription to get notifications when any BunkerOrder is updated via email, since API 3.9:

{
    "eventType":"U",
    "user":999999,
    "objectType":"BunkerOrder",
    "channelInfo":{ 
         "url": "info@dataloy.com",
         "channelType": "EMAIL"
    }
}

Create a subscription to get notifications only when a Voyage object is changed, since API 3.16:

{
    "eventType":"U",
    "user":999999,
    "objectType":"Voyage",
    "channelInfo":{ 
         "url": "info@dataloy.com",
         "channelType": "EMAIL"
    },
    "onlyMainObject": true
}

PUT /WebhookSubscription/{key}

Only the following attributes can be updated:

• unsubscribed

• url

• webhookUsername

• webhookPassword

Since API 3.9 is possible to change also these other attributes:

• channelInfo

• json

• expression

• dlpAlertScript

• scriptParameterValues

• useMsg

To unsubscribe a subscription the following JSON must be sent. It is not possible to update the subscription if it has been unsubscribed:

{
    "unsubscribed": true   
}

DELETE /WebhookSubscription/{key}

To delete a WebhookSubscription first it has to be unsubscribed. It is not possible to delete WebhookSubscription that got Webhook notifications, regardless that it has been unsubscribed or not.

The Dataloy VMS API documentation is intended as the main source of information and answers to queries and issues regarding integration with Dataloy VMS. It provides an overview of how integration with Dataloy VMS may be accomplished and detailed information about each type of integration.

High focus has been placed on quality of standard, substance and user-friendliness. The API knowledge base is kept continuously up-to-date. There is also a questions & answers section and a troubleshooting article section..

To search/navigate either click the links below or use the left-hand navigation panel to search by keyword, category or hierarchy.

API:

• What is it?

• Authentication / Authorization

• Getting Started

• Data Model

• Filtering

• Sorting

• Pagination

• Adjust Number of Fields to be Returned from a Request

• Webhooks

• Master Data Objects

User Guides:

• Accounting Integration API

• Schedule API

• Bunker Order Integration API

• Service Order Integration API

• Vessel Report

• Consumptions API

Questions & Answers, Troubleshooting Articles:

• Questions & Answers API

• Troubleshooting Articles API

Since API 3.3 Remark has a new attribute attachments that contains a list of Attachment objects. The Attachment resource has an attribute called file where can be stored the content of the file encoded in Base64.

The attribute fileName is mandatory, the attribute "filesize" is not mandatory but the client should pass it.

The two resources can be manipulated exactly as all other resources.

When a new Remark is posted with attachments in the JSON the source field must be before the attachments field.

When getting an attachment, data can be encoded in base64, but also unencoded. Attachments added from the API will be encoded and attachment added from the Java VMS client may be unencoded.

Some examples

Create a new remark with a file attached:

POST: http://{URL}/ws/rest/Remark BODY:

{
  "remarkTitle": "test 1",
  "source": 19637583,
  "attachments": [
    {
      
      "file":"small file 1",
      "fileName":"test1.txt"
    }
  ]
}

Attach an Attachment to an existing Remark

PUT: http://{URL}/ws/rest/Remark/244324058 BODY:

{
  "attachments": [
    {
      "file":"small file 2",
      "fileName":"test2.txt"
    }
  ]
}

The objective of accounting integration is to automate the creation and flow of transactions between the Dataloy VMS and an accounting system. The advantage is, for example, reduced risk of errors as several transactions handled by the Dataloy VMS system generates transactions to be entered in a client accounting system. An integration also allows for synchronizing the basic data entities (or Master Data, i.e. several of the same being stored and maintained in both systems) between systems. Some Master Data, for example, Business Partners, must be synchronized for the integration to work.

Accounting Integration Transactions

Transactions from Dataloy VMS to Accounting:

• Sales and purchase invoices are transferred whenever an invoice/invoices is/are posted in the VMS.

• Bunker transactions are transferred whenever a bunker transaction is posted in the VMS.

• Vessel/Voyage information is sometimes required by Accounting before invoices and/or bunker transactions are transferred. A scheduled task for transferring this type of information to Accounting can be set up (contact Dataloy for more information).

• Accruals will be transferred by users when performing period-end-closing (more information: Accruals page and the Period-End-Closing process).

Transactions from Accounting to Dataloy VMS:

• Receipts and payments being transferred from Accounting to Dataloy VMS. The transaction to collect and payments and send to the VMS is either triggered by Accounting or by a scheduled task (set up by Dataloy Systems).

• Exchange rates will be transferred from Accounting to Dataloy VMS. This transaction is either triggered by Accounting or by a scheduled task (set up by Dataloy Systems) to collect and retrieve the rates.

• Actuals is part of the Period-End-Closing process and is usually transferred from Accounting to Dataloy VMS.

The endpoint AuditLog (https://dataloy-systems.stoplight.io/docs/dataloyModel/model/schemas/audit-log) can be used to get all changes of any object in the data model.

To get the changes of a given object with key KEY_X:

• {BASE_URL}/ws/rest/AuditLog?filter=source(EQ)KEY_X

In the same request send the HTTP Header parameter fields with this JSON

{"objectName":"*","attributeName":"*","actionTime":"*","entryText":"*","source":"*","newValue":"*","oldValue":"*","isChangedByUser":"*","action":{"actionName":"*"},"user":{"userName":"*"}}

The response will be an array of AuditLog objects:

[
    {
        "key": 8345668,
        "self": "https://dev.dataloy.com/ws/rest/AuditLog/8345668",
        "objectName": "Voyage",
        "attributeName": "ladenConsumption",
        "source": 8336217,
        "user": {
            "key": 3689599,
            "self": "https://dev.dataloy.com/ws/rest/User/3689599",
            "userName": "Andrea Biasillo"
        },
        "actionTime": "2023-03-03T19:23:00",
        "entryText": "Field update: ladenConsumption",
        "isChangedByUser": true,
        "newValue": "83.29555785678073",
        "oldValue": "67.03034584820784",
        "action": {
            "key": 1000009,
            "self": "https://dev.dataloy.com/ws/rest/Action/1000009",
            "actionName": "EDIT"
        }
    },
    {
        "key": 8345669,
        "self": "https://dev.dataloy.com/ws/rest/AuditLog/8345669",
        "objectName": "Voyage",
        "attributeName": "co2Laden",
        "source": 8336217,
        "user": {
            "key": 3689599,
            "self": "https://dev.dataloy.com/ws/rest/User/3689599",
            "userName": "Andrea Biasillo"
        },
        "actionTime": "2023-03-03T19:23:00",
        "entryText": "Field update: co2Laden",
        "isChangedByUser": true,
        "newValue": "267.045558488839",
        "oldValue": "214.89928878935433",
        "action": {
            "key": 1000009,
            "self": "https://dev.dataloy.com/ws/rest/Action/1000009",
            "actionName": "EDIT"
        }
    },
    {
        "key": 8345670,
        "self": "https://dev.dataloy.com/ws/rest/AuditLog/8345670",
        "objectName": "Voyage",
        "attributeName": "tcResultDay",
        "source": 8336217,
        "user": {
            "key": 3689599,
            "self": "https://dev.dataloy.com/ws/rest/User/3689599",
            "userName": "Andrea Biasillo"
        },
        "actionTime": "2023-03-03T19:23:00",
        "entryText": "Field update: tcResultDay",
        "isChangedByUser": true,
        "newValue": "4877.341669917246",
        "oldValue": "6227.220974136807",
        "action": {
            "key": 1000009,
            "self": "https://dev.dataloy.com/ws/rest/Action/1000009",
            "actionName": "EDIT"
        }
    },
    {
        "key": 8345671,
        "self": "https://dev.dataloy.com/ws/rest/AuditLog/8345671",
        "objectName": "Voyage",
        "attributeName": "ballastConsumption",
        "source": 8336217,
        "user": {
            "key": 3689599,
            "self": "https://dev.dataloy.com/ws/rest/User/3689599",
            "userName": "Andrea Biasillo"
        },
        "actionTime": "2023-03-03T19:23:00",
        "entryText": "Field update: ballastConsumption",
        "isChangedByUser": true,
        "newValue": "42.7633723560667",
        "oldValue": "42.90031887514484",
        "action": {
            "key": 1000009,
            "self": "https://dev.dataloy.com/ws/rest/Action/1000009",
            "actionName": "EDIT"
        }
    ]

The endpoint AuditLog can be used to know all the objects that have been deleted:

/ws/rest/AuditLog?filter=action.actionName(EQ)REMOVE

in combitation with other filters and the HTTP Header parameter fields with this value:

{"entryText":"*","user":"*","actionTime":"*"}

return a response like this one:

[
    {
        "key": 18475755,
        "self": "https://dev.dataloy.com/ws/rest/AuditLog/18475755",
        "user": {
            "key": 2527205,
            "self": "https://dev.dataloy.com/ws/rest/User/2527205"
        },
        "actionTime": "2024-02-02T08:37:34",
        "entryText": "Deleted LaytimeTimeSheetItem #14707386"
    },
    {
        "key": 18475756,
        "self": "https://dev.dataloy.com/ws/rest/AuditLog/18475756",
        "user": {
            "key": 2527205,
            "self": "https://dev.dataloy.com/ws/rest/User/2527205"
        },
        "actionTime": "2024-02-02T08:37:34",
        "entryText": "Deleted LaytimeTimeSheetItem #14707388"
    },
    {
        "key": 18475757,
        "self": "https://dev.dataloy.com/ws/rest/AuditLog/18475757",
        "user": {
            "key": 2527205,
            "self": "https://dev.dataloy.com/ws/rest/User/2527205"
        },
        "actionTime": "2024-02-02T08:37:34",
        "entryText": "Deleted LaytimeTimeSheetItem #14707389"
    },
    {
        "key": 18475758,
        "self": "https://dev.dataloy.com/ws/rest/AuditLog/18475758",
        "user": {
            "key": 2527205,
            "self": "https://dev.dataloy.com/ws/rest/User/2527205"
        },
        "actionTime": "2024-02-02T08:37:34",
        "entryText": "Deleted LaytimeTimeSheetItem #14707387"
    },
    {
        "key": 18475783,
        "self": "https://dev.dataloy.com/ws/rest/AuditLog/18475783",
        "user": {
            "key": 2527205,
            "self": "https://dev.dataloy.com/ws/rest/User/2527205"
        },
        "actionTime": "2024-02-02T08:37:57",
        "entryText": "Deleted LaytimeTimeSheetItem #18475759"
    },
    {
        "key": 18475784,
        "self": "https://dev.dataloy.com/ws/rest/AuditLog/18475784",
        "user": {
            "key": 2527205,
            "self": "https://dev.dataloy.com/ws/rest/User/2527205"
        },
        "actionTime": "2024-02-02T08:37:57",
        "entryText": "Deleted LaytimeTimeSheetItem #18475760"
    },
    {
        "key": 18475785,
        "self": "https://dev.dataloy.com/ws/rest/AuditLog/18475785",
        "user": {
            "key": 2527205,
            "self": "https://dev.dataloy.com/ws/rest/User/2527205"
        },
        "actionTime": "2024-02-02T08:37:57",
        "entryText": "Deleted LaytimeTimeSheetItem #18475761"
    },
    {
        "key": 18475802,
        "self": "https://dev.dataloy.com/ws/rest/AuditLog/18475802",
        "user": {
            "key": 2527205,
            "self": "https://dev.dataloy.com/ws/rest/User/2527205"
        },
        "actionTime": "2024-02-02T08:38:04",
        "entryText": "Deleted LaytimeTimeSheetItem #18475780"
    },
    {
        "key": 18475803,
        "self": "https://dev.dataloy.com/ws/rest/AuditLog/18475803",
        "user": {
            "key": 2527205,
            "self": "https://dev.dataloy.com/ws/rest/User/2527205"
        },
        "actionTime": "2024-02-02T08:38:04",
        "entryText": "Deleted LaytimeTimeSheetItem #18475781"
    },
    {
        "key": 18475804,
        "self": "https://dev.dataloy.com/ws/rest/AuditLog/18475804",
        "user": {
            "key": 2527205,
            "self": "https://dev.dataloy.com/ws/rest/User/2527205"
        },
        "actionTime": "2024-02-02T08:38:04",
        "entryText": "Deleted LaytimeTimeSheetItem #18475782"
    }
]

where in the field entryText there is the object type and object key that has been deleted-

It is possible to activate and deactivate any Master Data object. A new property has been added for this purpose, isObjectActive.

To deactivate an object the following JSON has to be used in the PUT method:

{
	"isObjectActive": false
}

To activate an object the following JSON has to be used in the PUT method:

{
	"isObjectActive": true
}

Master Data objects has to be deactivated before they can be deleted.

Integration Set-Up

When a payment is registered in the accounting system, it should be transferred as applicable to the Posted sections of either the Accounts Payable or the Accounts Receivable modules (where the matching invoice/s can be found) in Dataloy VMS.

Since a payment in accounting systems may cover multiple Dataloy VMS payments/receipts, extracting payments from accounting means extracting invoices matching to a payment. Only payments/receipts records with a matching invoice in the applicable accounting system and with a required reference to a Dataloy invoice are to be extracted.

In Dataloy VMS all payments must match with the referenced invoice. To insert a payment/receipt in Dataloy VMS use the request under Data Transaction (below).

Data Transaction

• A payment record should ONLY ever have one document line. Never more.

Amount Prefix

This matrix is showing which prefix the payment amount should have for the various cases.

To Post a Payment/Receipt to Dataloy VMS:

{
    "documentAmount": 10000.00,
    "companyCurrencyAmount": 10000.00,
    "sourceCurrencyAmount": 10000.00,
    "documentCurrency": "USD",
    "documentDate": "2014-01-01T00:00:00",
    "documentType": "PMO",
    "documentNo": "111111199",
    "externalDocumentNo": "50300",
    "company": "01",
    "businessPartner": "60526",
    "invoicingStatus": "POS",   
    "documentText": "text here",
    "documentLines":
    [
        {
            "documentAmount": 10000.00,
            "companyCurrencyAmount": 10000.00,
            "sourceCurrencyAmount": 10000.00,
            "documentCurrency": "USD",
            "invoicingStatus": "POS",
            "documentLineText": "text here",
            "businessPartner": "BPCODE",
            "isAccountsPayable": true,
            "refDocument": "71800125"
        }
    ]   
}

Invoicing

Prerequisites

Certain integrations need to be in place before the set-up and testing of an invoice integration:

• Transfer of voyage related data to the accounting system.

• Synchronization of business partners between Dataloy VMS and the accounting system.

• Exchange rate transfer to Dataloy VMS.

• Map accounts between Dataloy VMS and the accounting system.

Integration Set-Up

When invoices are posted in Dataloy VMS, the document status is automatically set to Ready-for-Posting. Set up a scheduled task and use the request under Data Transaction to extract invoices and credit notes that are ready for posting. When an invoice is transferred to accounting, update the status to Posted.

Reverse Invoice

To reverse a posted invoice you need the document key and POST as in the example below

POST /Document/{document key}/reverse

Dissolve Invoice

To dissolve an assembled invoice you need the document key and POST as in the example below

POST /Document/{document key}/dissolve

Data Transaction

To get invoices that are ready for posting in Webhooks the following subscription can be created:

{
    "eventType":"U",
    "user": the user code to be used in the subscription,
    "objectType":"Document",
    "expression": "dlpObject.getInvoicingStatus() != null && dlpObject.getInvoicingStatus().getStatusTypeCode().equals(\"RFP\") && (dlpObject.getDocumentType().getDocumentType().equals(\"INO\") || dlpObject.getDocumentType().getDocumentType().equals(\"INI\") || dlpObject.getDocumentType().getDocumentType().equals(\"CRI\") || dlpObject.getDocumentType().getDocumentType().equals(\"CRO\"))",
    "url": "your webhook url"
}

Alternatively, a scheduled job can be set-up to use the following request:

Get invoices that are ready for posting to accounting

Payment Terms

There will be only one Document object in the API despite two payment terms for an invoice (for example 95/5 percent). However, the Document will have two documentPaymentTerms objects in the Document.documentPaymentTerms list.

To create two documents when integrating:

1. Loop on paymentTerms and create one document for each payment term.

2. Calculate the following values:

   • dueDate: document.documentPaymentTerms.dueDate

   • documentAmount: document.documentAmount * document.documentPaymentTerms.percentage / 100

   • companyCurrencyAmount: document.companyCurrencyAmount * document.documentPaymentTerms.percentage / 100

   • sourceCurrencyAmount: document.sourceCurrencyAmount * document.documentPaymentTerms.percentage / 100

Test Data

Test data for invoicing integration can be generated in the Dataloy VMS post fixture modules (Accounts Receivable, Accounts Payable and Hire Payable).

Post Transaction

When an invoice is successfully transferred to an accounting system, the document status must be updated to Posted in Dataloy VMS. This is done in a PUT request:

Update status to posted for a specific invoice

PUT request on /Document/{key}
  
{
    "invoicingStatus": "POS"
}

Easy way of writing expressions for webhook from version 6.9

The user need not know the attribute names in order to use an expression and will have the possibility to select an attribute from the list of attributes on the given objectType in the subscription and can chose the operators from the list of operators.

This is achieved by the use of special characters as listed below-

• using . (Dot) in the expression field will list all the sub objects for the given object type. The list of attributes will be filtered based on the characters typed

• $(dollar) will list the operators that can be used

• using old or ,(comma) will enable the use of oldDlpObject in the expression

For example, instead of using this in an expression

dlpObject.getInvoicingStatus() != null && dlpObject.getInvoicingStatus().getStatusTypeCode().equals(“RFP”) && (dlpObject.getDocumentType().getDocumentType().equals(“ACP”)

a simple of achieving this would be to use

.invoicingStatus.statusTypeCode = RFP && .documentType.documentType = ACP OR .documentType.documentType = ACP 

The need for the user to create expressions with null checks for the objects is also removed and will be taken care by the platform. Expressions will work the same way if the object is checked for null or not. For example both of the below shall work the same.

.invoicingStatus.statusTypeCode = RFP && .documentType.documentType = ACP OR .documentType.documentType = ACP 
.invoicingStatus != null && invoicingStatus.statusTypeCode = RFP && .documentType.documentType = ACP OR .documentType.documentType = ACP 

Refer Create Expression Webhook Subscription for more details about creating an expression subscription in vms

Do Not Unsubscribe

A new attribute, called doNotUnsubscribe (type boolean), has been added to prevent that the subscription will get unsubscribed, also if the endpoint is not reachable for more time of the max time of attempts set for the given server.

Alerts Menu Item

• Webhooks is moved out from Setup to Alerts Menu Item on VMS web

• Alert menu item has two inclusions - Webhooks and Notifications

  • Webhooks - shows the list of subscriptions made by the user if the user is a non-administrative role and shows all the subscriptions in the system for an administrator user

  • Notifications - shows the list of Notifications for all the subscriptions visible for the user.

Webhooks

• Clicking one of the rows in webhooks, opens the webhook subscription drawer with three tabs - Overview, Notifications and Comments

  • While Overview has some new additions to it, Comments remain the same from before.

• Notifications tab in the subscription drawer includes the list of notifications filtered for the selected subscription. From 6.10.0, this list is updated to be similar to the other lists on VMS web with enabled filters and sorting.

• Further clicking on one of the rows in the notifications list on subscription drawer, we can see the details of the Notification Msg sent for the subscription along with the error msg if the msg sending failed.

Notifications

• Holds the list of notifications for those subscriptions which the user has access to.

  • Administrator can access all the notifications for all the subscriptions available in the system, while non admin users can access only the subscriptions for the given logged in user. For example,

Template_msg

The possibility for the user to define a message template that should be used when sending notifications for a webhook subscription is introduced.

In order to use this, the user when creating a webhook subscription should provide the necessary input to the field/attribute “templateMsg". Make sure the placeholders are indicated by a '?' followed by the field/attribute directly accessible from the root object type on which the subscription is being made.

For example, when creating a subscription on Bank object , the user can use template_msg like ‘Bank with Name ?bankName is changed by ?changedById’ .

This would result in the below notification for the user (example data, for reference only)

Prerequisites

Invoice Integration needs to be in place before setting up and testing actuals integration.

Integration Set-Up

Transfer of actuals (or physicals) from Accounting to Dataloy VMS can either be setup as a manual task through the Period-End-Closing Process or as a scheduled task. Actuals in accounting are actual costs and revenues, and once entered into Dataloy VMS, the actual record will appear in the Posted section of the Accruals module. Bunker transactions in Accounting that has been transferred from Dataloy VMS are not to be transferred, as they are already treated as actuals in Dataloy VMS (more information: actuals and accruals page and the Period-End-Closing process.

Data Transaction

To insert an actual in Dataloy VMS:

• An actual record should ONLY ever have one document line. Never more.

• The document date should be the first day of the period month.

• Client can choose to insert actuals one by one or group actuals by period, currency, voyage, account and company

• Set a unique document number (documentNo).

Use request:

Post an actual to Dataloy

POST /Document
  
{
    "documentAmount": 10000.00,
    "companyCurrencyAmount": 10000.00,
    "sourceCurrencyAmount": 10000.00,
    "documentDate": "2014-01-01T00:00:00",
    "documentType": "ACC",
    "documentNo": "111111187",
    "company": "01",
    "invoicingStatus": "POS",
    "documentCurrency": "USD",
    "documentText": "text here",
    "glAccount": "1000",
    "documentLines":
    [
        {
            "documentAmount": 10000.00,
            "companyCurrencyAmount": 10000.00,
            "sourceCurrencyAmount": 10000.00,
            "documentCurrency": "USD",
            "exchangeRate": 1,
            "invoicingStatus": "POS",
            "documentLineText": "text here",
            "voyage": "VOY100",
            "glAccount": "1000"
        }
    ]
}

Post Transaction

No post transaction is required.

Voyages

Prerequisites

No prerequisites.

Integration Set-Up

Accounting systems often require voyage related data before transferring accounting related transactions. Set up a scheduled task and use the request under Data Transaction to gather all voyages that has been modified since the last time a scheduled task was run.

Test Data

Modify some existing voyages in the Booking and Operations module for testing, for example, changing a date in the schedule (note: changing dates will also affect the schedule for other voyages).

Data Transaction

To get new voyages in Webhooks the following subscription can be created:

{
"eventType": "U",
"user":
"objectType": "VoyageHeader",
"expression": "(oldDlpObject.getVoyageStatus() != null && oldDlpObject.getVoyageStatus().getStatusTypeCode().equals(\"EST\") && dlpObject.getVoyageStatus() != null && dlpObject.getVoyageStatus().getStatusTypeCode().equals(\"NOM\")) || (oldDlpObject.getReferenceNo() == null && dlpObject.getReferenceNo() != null && dlpObject.getVoyageStatus() != null && dlpObject.getVoyageStatus().getStatusTypeCode().equals(\"NOM\"))",
"url":
}

To get updated for all changes on a voyage the following webhook subscription can be created:

{
"eventType": "U",
"user":
"objectType": "VoyageHeader",
"url":
}

To extract all fixed voyages from Dataloy VMS that has been modified since a given date, use request below in conjunction with the base URL:

Get all fixed voyages modified since given date

GET /VoyageHeader?filter=modifiedDate(GTE)2014-01-01T12:30:00

Post Transaction

No post transaction is required.

Prerequisites

Before setting up and testing a bunker transaction integration other integrations need to be in place.

• Transfer of voyage related data to the accounting system.

• Synchronization of business partners between Dataloy VMS and the accounting system.

• Exchange rate transfer to Dataloy VMS.

Integration Set-Up

When a bunker transaction is posted in Dataloy VMS, the document status is set to Ready-for-Posting. Set up a scheduled task and use the request under Data Transaction to extract bunker transactions that are ready for posting. When a bunker transaction is transferred to accounting, update the status to Posted.

Test Data

Test data for bunker transactions can be generated in Booking and Operations > Bunkers-FO tab > Bunker Transactions.

Data Transaction

To get bunker transactions that are ready for posting in Webhooks the following subscription can be created:

{
    "eventType":"U",
    "user": the user code to be used in the subscription,
    "objectType":"Document",
    "expression": "dlpObject.getInvoicingStatus() != null && dlpObject.getInvoicingStatus().getStatusTypeCode().equals(\"RFP\") && (dlpObject.getDocumentType().getDocumentType().equals(\"ACC\"))",
    "url":"your webhook url"
}

Alternatively a scheduled job can be setup to use the following request:

Get bunker transactions that are ready for posting to accounting

Post Transaction

When an invoice is successfully transferred to the accounting system, the document status has to be updated to Posted in Dataloy VMS. This is done in a PUT request:

Update status to posted for a specific invoice

PUT /Document/{key}
  
{
    "invoicingStatus": "POS"
}

Prerequisites

• An exchange rate source for extracting data to be inserted in Dataloy VMS.

• Base Currency must be set. Note: Locate Base Currency by getting ws/rest/System/1000000, then following relevant country link (Country Currency = the Base Currency).

Integration Set-Up

Set up a task for extracting exchange rates from either an accounting system or from a source delivering exchange rates service. Then insert the exchange rate into Dataloy VMS using the request under Data Transaction (below).

Data Transaction

To insert an exchange rate in Dataloy VMS (fields required):

Post an exchange rate to Dataloy

POST /ExchangeRate
  
{
    "currency": "EUR",
    "fromCurrency": "USD",
    "exchangeRate": 0.74042,
    "exchangeRateDate": "2014-01-01T00:00:00"
}

Post Transaction

No post transaction is required.

When inserting data that in the end will result in an account payable, you might want to post the invoice directly. This can be done with a couple of API calls.

Generate Invoice Lines

To generate invoice lines you need to know the key of the voyage that your data relates to. If you dont have the voyage key already you need to get it from the API either by getting it at an earlier stage in your integration or with a separate call in this stage. If you for instance already have the port call key you can get the voyage key by doing a GET request on PortCall.

To generate invoice lines post the below request, where key is the voyage key. For multiple voyages, add multiple keys.

POST /ws/rest/Document/refreshDocumentLines?key=123&key=456&isAccountsPayable=true
Body: empty

To locate the voyage key for Service Order and Bunker Order:

Service Order:
GET /ws/rest/ServiceOrder/{key}
Http header:
fields: {"portCall": {"voyage": {"key":"*"}}}

Bunker Order:
GET /ws/rest/BunkerOrder/{key}
Http header:
fields: {"portCall": {"voyage": {"key":"*"}}}

Then get the new invoice lines, called document lines in the API

Service Orders:
GET /ws/rest/DocumentLine?filter=voyage(IN)(123,456)&filter=document(NULL)
&filter=invoicingStatus.statusTypeCode(EQ)PEN&filter=portCall.key(EQ)118616134&filter=portCost.portAgent.daReference(EQ)DA-123

Bunker Orders:
GET /ws/rest/DocumentLine?filter=voyage(IN)(7173894)&filter=document(NULL)
&filter=invoicingStatus.statusTypeCode(EQ)PEN&filter=portCall.key(EQ)7173995
&filter=bunkerOrderLine.bunkerOrder.key(EQ)8366819

Get invoice defaults (optional)

The below endpoint will give you data that can be used when assembling the invoice. Like bank account, issuing company and so on. If you already have the data you can skip this step.

POST /ws/rest/Document/invoiceDefaults

Header: disablebl = true (only for jvms customers)

Body:
{"documentLines":[{"key":111},{"key":222}], "invoicingStatus": "PEN"}

Assemble invoice

Assemble the invoice with this request

POST /ws/rest/Document/assemble

Header: disablebl = true (only for jvms customers)

​​{
    "bankAccount": "bankAccountNo",
    "businessPartner": "businessPartnerCode",
    "documentCurrency": "USD",
    "documentDate": "2022-02-23T00:00:00",
    "documentLines": [{ "key": 111 }, { "key": 222 }],
    "documentPaymentTerms": [
        {
            "baselineDate": "2022-02-23T00:00:00",
            "baselineTerm": "baselineTermCode",
            "dueDate": "2022-03-02T00:00:00",
            "paymentTerms": "paymentTermsCode",
            "percentage": 100
        }
    ],
    "documentText": "A document text",
    "exchangeRate": 1,
    "exchangeRateDate": "2022-02-23T09:28:26",
    "externalDocumentNo": "1234",
    "issuingCompany": "companyCode",
    "invoicingStatus" : "INV"
}

• Mandatory fields: documentText, documentDate, issuingCompany, bankAccount, baseLineDate, baseLineTerms, dueDate, paymentTerms and percentage.

• If payment terms percentage is 100%, there should only be one entry in documentPaymentTerms

• BaseLineTerm is customer specific and needs to be agreed with customer. The baseline terms can be found at /ws/rest/BaselineTerm

• PaymentTerms is customer specific and needs to be agreed with customer. The payment terms can be found at /ws/rest/PaymentTerms

The request will return the new invoice, called Document in the API. Keep the Document key to post the document in next step.

Post invoice

The final request will set the status to ready for posting which will cause accounting integrations to pick up the invoice and transfer it to accounting. The Document key is returned the assemble response in previous step.

PUT /ws/rest/Document/789

Header: disablebl = true (only for jvms customers)

{"invoicingStatus":"RFP"}

Prerequisites

Synchronization of business partners between Dataloy VMS and the applicable accounting system is required before transferring accounting related transactions. To synchronize business partner updates between systems, decide which system is to be the Master System (where the business partners will be updated). The Master System will then send updated business partner data to the other system.

Integration Set-Up

• Dataloy VMS used as master:

  • Dataloy recommends setting up up a Webhook. As an alternative, setup a scheduled job and use the request under Data Transaction (below) to gather all business partners data having been modified since the last time a scheduled task was run.

• Dataloy VMS is not used as master: Use the requests under Data Transaction (below) to insert and update the business partners in Dataloy VMS.

Data Transaction

Dataloy VMS as a master for business partners

Webhook

Setup Webhook subscriptions for BusinessPartner, Address and ContactInfo. From Address and Contact info there is a reference back to the BusinessPartner key in the source field.

Scheduled Job (If Webhook is not an option)

Extract the business partners whose data has been modified since a selected date from Dataloy VMS using the following request in conjunction with the base URL:

Get business partner information

GET /BusinessPartner?filter=modifiedDate(GTE)2014-01-01T12:30:00

Set up a scheduled job and gather all voyages that have been modified since the last time a scheduled task was run.

Other systems as Master for Business Partners

Check if relevant business partner/s is/are already existing in Dataloy VMS by using the following request in conjunction with the base URL:

Get business partner by key

GET /BusinessPartner?filter=businessPartnerCode(EQ)99999

If the business partner is already existing in Dataloy VMS

Update BusinessPartner

PUT /BusinessPartner
  
{
    "key":1111111,
    "businessPartnerName": "Test Name",
    "businessPartnerCode": "123456789",
    "businessPartnerSort": "TESTNAME",
    "companyRegistrationNo": "123456789", 
    "businessPartnerType": "C",
  
    "bankAccounts":[
    {
      "key":222222,
      "iban":"9754",
      "bankAccountNo":"6523",
      "bank": 1033615,
      "currency": 400132
    }
    ],
   
    "addresses": [
    {
        "key":333333,
        "country": "NL",
        "address1": "Street Name 54",
        "address2": "5th floor",
        "address3": "",
        "city": "Amsterdam",
        "postalCode": "1000 AA"
    }
    ],
    "contactInfo": [
        {
            "key":444444,
            "email": "test@test.com",
            "faxNo": "55555555",
            "mobileNo": "66666666",
            "phoneNo": "77777777",
            "telexNo": "88888888"
        }
    ]
}

If the business partner does not exist in Dataloy VMS

BusinessPartner API documentation

POST /BusinessPartner
  
{
    "businessPartnerName": "Test Name",
    "businessPartnerCode": "123456789",
    "businessPartnerSort": "TESTNAME",
    "companyRegistrationNo": "123456789",  
    "businessPartnerType": "C",
  
    "bankAccounts":[
    {
      "iban":"9754",
      "bankAccountNo":"6523",
      "bank": {
        "bankName":"BP bank",
        "abaNumber":"1111",  
        "chip":"2222",
        "swiftAddress":"42341"
       },
      "currency": 400132
    }
    ],
   
    "addresses": [
    {
        "country": "NL",
        "address1": "Street Name 54",
        "address2": "5th floor",
        "address3": "",
        "city": "Amsterdam",
        "postalCode": "1000 AA"
    }
    ],
    "contactInfo": [
        {
            "email": "test@test.com",
            "faxNo": "55555555",
            "mobileNo": "66666666",
            "phoneNo": "77777777",
            "telexNo": "88888888"
        }
    ]
}

Inquiries can be sent to

Create a Voyage with a Loading and Discharging PortCall with one Cargo with a Loading and Discharging CargoPort.

Creating a new Cargo with a Loading and Discharging CargoPort and PortCall. The PortCall objects have EventLogDates that specify Arrival, Berthing, Un-berthing, and Departure dates.

POST /Cargo
 
{
    "cargoMeasurement": "MT",
    "cargoPorts": [
        {
            "cargoPortSequence": 1,
            "cargoQuantity": 1234,
            "laytimeTermsMeasurement": "H",
            "port": {
                "key": 102381
            },
            "portCall": {
                "portCallSequence": 3,
                "reasonForCall": "L",
                "port": 102381,
                "voyage": 6136896
            },
            "reasonForCall": "L"
        },
        {
            "cargoPortSequence": 1,
            "cargoQuantity": 1234,
            "freightRate": 1210,
            "laytimeTermsMeasurement": "H",
            "port": {
                "key": 101486
            },
            "portCall": {
                "portCallSequence": 4,
                "reasonForCall": "D",
                "port": 101486,
                "voyage": 6136896
            },
            "reasonForCall": "D"
        }
    ],
    "charterer": {
        "key": 1004307
    },
    "commodity": {
        "key": 1675975
    },
    "freightCurrency": "USD",
    "voyage": {
        "key": 6136896
    }
}

Adding to a Cargo a new Loading or Discharging CargoPort and PortCall

PUT /Cargo/{KEY}
 
{
    "cargoPorts": [
        {
            "key": 18739785
        },
        {
            "key": 18739786
        },
        {
            "port": 103991,
            "reasonForCall": "D",
            "cargoPortSequence": 2,
            "portCall": {
                "portCallSequence": 6,
                "reasonForCall": "D",
                "port": 103991,
                "voyage": 18739534,
                "ownedByVoyage": 18739534
            }
        }
    ]
}

Fixing the date on an EventLog object. Note, only EventLogs with EventLog.EventLogDate from the past can be fixed, otherwise, the returned value of isDateFixed will be false.

PUT /EventLog/{KEY}

{
    "isDateFixed":true
}

The objective of the Service Order integration is to trigger the ordering of port related services and receive updates on estimated, revised and actual cost from parties handling the orders. The costs are internally assigned to the correct port call, vessel and voyage and processed further inside the VMS.

Description

Note: Recommended before proceeding - read: Getting Started with Dataloy REST API.

The endpoints for the Port Service Order process are:

1. .

2. .

3. .

ServiceOrder objects are created by Dataloy VMS with the status Draft, status code DFT.

The integration should use Webhooks to be notified when a new ServiceOrder object is created.

POST.WebhookSubscription:

     {
        "user":  12345679,
        "channelInfo": {
            "url": "https://push.here.com",
            "channelType": "HTTP"
        },
        "eventType": "C",
        "objectType": "ServiceOrder"
    }

The JSON sent, when a service order is created, will have this structure:

{
   "id":"0:ffff7f000001:-1c943d78:678f500d:42f06",
   "eventTime":"2025-01-22T07:41:46",
   "eventType":"C",
   "objectType":"ServiceOrder",
   "dataloyObject":69801182,
   "dataloyObjectSelf":"https://dev.dataloy.com/ws/rest/ServiceOrder/69801182",
   "subscription":{
      "key":69801122,
      "self":"https://dev.dataloy.com/ws/rest/WebhookSubscription/69801122"
   },
   "resource":{
      "key":69801182,
      "self":"https://dev.dataloy.com/ws/rest/ServiceOrder/69801182",
      "currency":{
         "key":400132,
         "self":"https://dev.dataloy.com/ws/rest/Currency/400132"
      },
      "status":{
         "key":51969046,
         "self":"https://dev.dataloy.com/ws/rest/StatusType/51969046"
      },
      "orderDate":"2024-05-18T20:22:00",
      "exchangeRate":1.0,
      "portAgentType":null,
      "portCall":{
         "key":69276170,
         "self":"https://dev.dataloy.com/ws/rest/PortCall/69276170"
      },
      "serviceOrderLines":[
         
      ],
      "amount":0.0,
      "amountAdvanced":0.0,
      "amountHandlingCost":0.0,
      "amountHandlingCostVoyageCurrency":0.0,
      "amountPortCost":0.0,
      "amountPortCostVoyageCurrency":0.0,
      "amountVariousCost":0.0,
      "amountVariousCostVoyageCurrency":0.0,
      "amountVoyageCurrency":0.0,
      "emailSentDate":null,
      "amountAdvancedCurrency":{
         "key":400132,
         "self":"https://dev.dataloy.com/ws/rest/Currency/400132"
      },
      "businessPartner":{
         "key":1318806,
         "self":"https://dev.dataloy.com/ws/rest/BusinessPartner/1318806"
      },
      "nominationEmail":null,
      "externalReferenceNo":"1737531705924",
      "createdById":66007605,
      "createdDate":"2025-01-22T07:41:45",
      "externalObjectKey":null,
      "modifiedDate":null,
      "changedById":66007605,
      "remarks":[
         
      ],
      "isObjectActive":true
   }
}

It is possible to be notified only by the raw object, in this case the WebhookSubscription has to have the following property:

"rawObject" : true

In this case the JSON sent will be like this:

{
   "key":69801182,
   "self":"https://dev.dataloy.com/ws/rest/ServiceOrder/69801182",
   "currency":{
      "key":400132,
      "self":"https://dev.dataloy.com/ws/rest/Currency/400132"
   },
   "status":{
      "key":51969046,
      "self":"https://dev.dataloy.com/ws/rest/StatusType/51969046"
   },
   "orderDate":"2024-05-18T20:22:00",
   "exchangeRate":1.0,
   "portAgentType":null,
   "portCall":{
      "key":69276170,
      "self":"https://dev.dataloy.com/ws/rest/PortCall/69276170"
   },
   "serviceOrderLines":[
      
   ],
   "amount":0.0,
   "amountAdvanced":0.0,
   "amountHandlingCost":0.0,
   "amountHandlingCostVoyageCurrency":0.0,
   "amountPortCost":0.0,
   "amountPortCostVoyageCurrency":0.0,
   "amountVariousCost":0.0,
   "amountVariousCostVoyageCurrency":0.0,
   "amountVoyageCurrency":0.0,
   "emailSentDate":null,
   "amountAdvancedCurrency":{
      "key":400132,
      "self":"https://dev.dataloy.com/ws/rest/Currency/400132"
   },
   "businessPartner":{
      "key":1318806,
      "self":"https://dev.dataloy.com/ws/rest/BusinessPartner/1318806"
   },
   "nominationEmail":null,
   "externalReferenceNo":"1737531705924",
   "createdById":66007605,
   "createdDate":"2025-01-22T07:41:45",
   "externalObjectKey":null,
   "modifiedDate":null,
   "changedById":66007605,
   "remarks":[
      
   ],
   "isObjectActive":true
}

The fields property to customize the messages must be encoded with Base64 and set in attribute json of the WebhookSubscription

If the integration want to be notified also when there are changes to the PortCall connected with the ServiceOrder, a WebhookSubscription like this should be POST:

     {
        "user":  12345679,
        "channelInfo": {
            "url": "https://push.here.com",
            "channelType": "HTTP"
        },
        "eventType": "U",
        "objectType": "PortCall",
        "dataloyObject": 36344213
    }

where “dataloyObject“: 3644213 is the PortCall key.

To add a new line to a a order:

{
    "serviceOrderLines": [
        {
            "amountEstimate": 200,
            "description": "first line",
            "isCharterersCost": false,
            "isOwnersCost": false,
            "serviceCode": "PRC"
        }
    ]
}

Starting from 7.3.0, invoices can be automatically posted. Ensure your changes are invoiced accurately by including the autoPost = true HTTP header in your PUT requests.

PUT /ws/rest/ServiceOrder/6420123 HTTP/1.1
Host: localhost:8080
autoPost: true
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkVJWjlvcFlVZWZaLXVsbTk5SUpCTyJ9.eyJpc3MiOiJodHRwczovL2ludGVybmFsLmV1LmF1dGgwLmNvbS8iLCJzdWIiOiJhdXRoMHw2NGY5ODE4MzU5OGI3YTg2ZjllZDUzMTAiLCJhdWQiOlsiaHR0cHM6Ly9kYXRhbG95LmludGVybmFsIiwiaHR0cHM6Ly9pbnRlcm5hbC5ldS5hdXRoMC5jb20vdXNlcmluZm8iXSwiaWF0IjoxNzEyMDU2MjIwLCJleHAiOjE3MTIwNjM0MjAsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgZW1haWwiLCJhenAiOiJadGZXVTdYZEJmaGtQb0pSNHhCelVGQlpKU1htbzlJdCJ9.ZU
Content-Length: 190

{"serviceOrderLines":[{"key":6420124,"amountEstimate":12501,"amountFinal":0,
"amountRevised":0,"description":null,"isCharterersCost":true,
"isOwnersCost":false,"serviceCode":{"key":6003979}}]}

Service Order statues

• Draft, DFT

• Estimated, EST

• Revised, REV

• Final, FIN

• Cancel, CAN

Service Order status transitions

Service Order status transitions when Agent nomination is enabled

Prerequisites

Before setting up and testing an invoice integration other integrations need to be in place:

Integration Set-Up

When accruals have been verified and posted in Dataloy VMS, the document status is set to Ready-for-Posting.

More information, go to and .

Data Transactions

To get accruals that are ready for posting in the following subscription can be created:

{
    "eventType":"U",
    "user": the user code to be used in the subscription,
    "objectType":"Document",
    "expression": "dlpObject.getInvoicingStatus() != null && dlpObject.getInvoicingStatus().getStatusTypeCode().equals(\"RFP\") && (dlpObject.getDocumentType().getDocumentType().equals(\"ACR\") || dlpObject.getDocumentType().getDocumentType().equals(\"ACP\"))",
    "url":"your webhook url"
}

Alternatively, a scheduled job can be setup to use the following request:

Get accruals and accrual reversals that are ready for posting to accounting

Test Data

Post Transaction

When an accrual is successfully transferred to an accounting system, the accrual status must to be updated to Posted in Dataloy VMS. This is done in a PUT request:

Update status to posted for a specific invoice

PUT /Document/{key}
  
{
    "invoicingStatus": "POS"
}

Additional Information

List of Document Statuses in Dataloy VMS

List of Document Line Fields

Bank Fields List

Overview

Position reports update a port call's sailing, arrival, in port, and departure status. Most fields in the PositionReport object will only provide information, while a few affect the port call's results.

The following fields will affect the port call's results:

• eventLogs

  • An captures port events along with their dates and times. The port events include ARRIVAL, BERTHED, UNBERTHED, and DEPARTURE. To record the arrival date of a port call, an event log entry should include the ARRIVAL event along with the corresponding date.

  • An EventLog is also linked to ROBs to communicate the Remaining on Board (ROB) of a specific bunker during a specific event. For instance, the of Fuel Oil (FO) on arrival will be specified by having the robs field on the arrival event log entry, containing the key of the FO bunker category.

Fields impacting the port call's results will have Major Change Factor marked as yes, along with a description, on the .

PositionReport can be one of these types:

• Noon Report

  • logs the ship's status at sea, updating the estimated arrival date and ROB info

• Arrival Report

  • logs when the ship arrives in the port, fixing the arrival date and ROB info

• Berth Report

  • logs when the ship has berthed in the port, fixing the berthed date and ROB info

• Unberth Report

  • logs when the ship has unberthed in the port, fixing the unberthed date and ROB info

• In Port Report

  • logs supplementary information such as hours in service, weather, wind direction and average wind direction when the ship is docked.

• Departure Report

  • logs when the ship leaves the port, fixing the departure date and ROB info

Details

Noon Report

Noon report example

GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
fields: {"eventLogs": {"event": {"eventCode":"*"}, "robs": {"bunkerCategory": {"bunkerCategoryCode":"*"}, "rob": "*"}}}
Authorization: Bearer ....

POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....

{
    "vesselReportType": "NOON",
    "reportDateLocal": "2024-08-01T19:00:00",
    "portCall": 6130402, //key from the response of the PortCall query
    "latitude": 60.2139,
    "longitude": 4.5300,
    "eventLogs": [
        {
           "key": 6130395, //arrival event log key
            "eventLogDate": "2024-08-02T02:36:00",
            "robs": [
                {
                    "key": 6130460, //arrival DL Rob key
                    "rob": 250
                }
            ]
        }
    ],
    "windDirection": 911643,
    "weather": 950928,
    "distanceSailed": 3150.00
}

Arrival Report

Arrival report example

GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
fields: {"eventLogs": {"event": {"eventCode":"*"}, "robs": {"bunkerCategory": {"bunkerCategoryCode":"*"}, "rob": "*"}}}
Authorization: Bearer ....

POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....

{
    "vesselReportType": "ARR",
    "reportDateLocal": "2024-08-01T19:00:00",
    "portCall": 6130402, //key from the response of the PortCall query
    "latitude": 60.2139,
    "longitude": 4.5300,
    "eventLogs": [
        {
           "key": 6130395, //arrival event log key
            "eventLogDate": "2024-08-02T03:00:00",
            "robs": [
                {
                    "key": 6130460, //arrival DL Rob key
                    "rob": 235
                },
                {
                    "key": 6130469, //arrival FO Rob key
                    "rob": 225.85
                }
            ]
        }
    ]
}

Berth Report

Berth report example

GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
fields: {"eventLogs": {"event": {"eventCode":"*"}, "robs": {"bunkerCategory": {"bunkerCategoryCode":"*"}, "rob": "*"}}}
Authorization: Bearer ....

POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....

{
    "vesselReportType": "BRT",
    "reportDateLocal": "2024-08-03T10:36:00",
    "portCall": 6130402, //key from the response of the PortCall query
    "eventLogs": [
        {
            "key": 6130394, //berth event log key
            "eventLogDate": "2024-08-03T10:36:00",
            "robs": [
                {
                    "key": 6130441, //berth DL rob key
                    "rob": 220
                },
                {
                    "key":6130468, //berth FO rob key
                    "rob": 225
                }
            ]
        }
    ]
}

Unberth Report

Unberth report example

GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
fields: {"eventLogs": {"event": {"eventCode":"*"}, "robs": {"bunkerCategory": {"bunkerCategoryCode":"*"}, "rob": "*"}}}
Authorization: Bearer ....

POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....

{
    "vesselReportType": "UBRT",
    "reportDateLocal": "2024-08-05T08:00:00",
    "portCall": 6130402, //key from the response of the PortCall query
    "eventLogs": [
        {
            "key": 6130393, //unberth event log key
            "eventLogDate": "2024-08-05T08:00:00",
            "robs": [
                {
                    "key": 6130453, //berth DL rob key
                    "rob": 218.5
                },
                {
                    "key":6130443, //unberth FO rob key
                    "rob": 225
                }
            ]
        }
    ]
}

In Port Report

In port report example

GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
fields: {"eventLogs": {"event": {"eventCode":"*"}, "robs": {"bunkerCategory": {"bunkerCategoryCode":"*"}, "rob": "*"}}}
Authorization: Bearer ....

POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....

{
    "vesselReportType": "PORT",
    "reportDateLocal": "2024-08-03T18:00:00",
    "portCall": 3345932, //key from the response of the PortCall request
    "hoursInService": 225.85,
    "weather": 950927,
    "windDirection": 911638,
    "averageWindForce": 1
}

Departure Report

Departure Report example

GET /ws/rest/PortCall?filter=voyage.key(EQ)123456&portCallSequence(EQ)2=null HTTP/1.1
Host: BASEURL
fields: {"eventLogs": {"event": {"eventCode":"*"}, "robs": {"bunkerCategory": {"bunkerCategoryCode":"*"}, "rob": "*"}}}
Authorization: Bearer ....

POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....

{
    "vesselReportType": "DEP",
    "reportDateLocal": "2024-08-05T08:30:00",
    "portCall": 6130402, //key from the response of the PortCall query
    "eventLogs": [
        {
            "key": 6130397, //departure event log key
            "eventLogDate": "2024-08-05T08:30:00",
            "robs": [
                {
                    "key": 6130465, //departure DL rob key
                    "rob": 215
                },
                {
                    "key":6130449, //departure FO rob key
                    "rob": 225
                }
            ]
        }
    ]
}

More examples

[
    {
        "key": 6130402,
        "eventLogs": [
            {
                "key": 6130391,
                "event": {
                    "key": 1000051,
                    "eventCode": "BRT"
                },
                "robs": [
                    {
                        "key": 6130447,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916946,
                            "bunkerCategoryCode": "DO"
                        }
                    },
                    {
                        "key": 6130450,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916944,
                            "bunkerCategoryCode": "FO"
                        }
                    },
                    {
                        "key": 6130462,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916945,
                            "bunkerCategoryCode": "FL"
                        }
                    },
                    {
                        "key": 6130464,
                        "rob": 249.75,
                        "bunkerCategory": {
                            "key": 916947,
                            "bunkerCategoryCode": "DL"
                        }
                    }
                ]
            },
            {
                "key": 6130396,
                "event": {
                    "key": 6088041,
                    "eventCode": "UBRT"
                },
                "robs": [
                    {
                        "key": 6130444,
                        "rob": 249.75,
                        "bunkerCategory": {
                            "key": 916947,
                            "bunkerCategoryCode": "DL"
                        }
                    },
                    {
                        "key": 6130452,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916945,
                            "bunkerCategoryCode": "FL"
                        }
                    },
                    {
                        "key": 6130459,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916946,
                            "bunkerCategoryCode": "DO"
                        }
                    },
                    {
                        "key": 6130470,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916944,
                            "bunkerCategoryCode": "FO"
                        }
                    }
                ]
            },
            {
                "key": 6130392,
                "event": {
                    "key": 1000052,
                    "eventCode": "DEP"
                },
                "robs": [
                    {
                        "key": 6130440,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916944,
                            "bunkerCategoryCode": "FO"
                        }
                    },
                    {
                        "key": 6130448,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916945,
                            "bunkerCategoryCode": "FL"
                        }
                    },
                    {
                        "key": 6130454,
                        "rob": 249.75,
                        "bunkerCategory": {
                            "key": 916947,
                            "bunkerCategoryCode": "DL"
                        }
                    },
                    {
                        "key": 6130458,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916946,
                            "bunkerCategoryCode": "DO"
                        }
                    }
                ]
            },
            {
                "key": 6130395,
                "event": {
                    "key": 1000050,
                    "eventCode": "ARR"
                },
                "robs": [
                    {
                        "key": 6130451,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916945,
                            "bunkerCategoryCode": "FL"
                        }
                    },
                    {
                        "key": 6130460,
                        "rob": 250.0,
                        "bunkerCategory": {
                            "key": 916947,
                            "bunkerCategoryCode": "DL"
                        }
                    },
                    {
                        "key": 6130467,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916946,
                            "bunkerCategoryCode": "DO"
                        }
                    },
                    {
                        "key": 6130469,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916944,
                            "bunkerCategoryCode": "FO"
                        }
                    }
                ]
            }
        ]
    },
    {
        "key": 6130400,
        "eventLogs": [
            {
                "key": 6130394,
                "event": {
                    "key": 1000051,
                    "eventCode": "BRT"
                },
                "robs": [
                    {
                        "key": 6130441,
                        "rob": 230.53559444257462,
                        "bunkerCategory": {
                            "key": 916947,
                            "bunkerCategoryCode": "DL"
                        }
                    },
                    {
                        "key": 6130457,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916945,
                            "bunkerCategoryCode": "FL"
                        }
                    },
                    {
                        "key": 6130461,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916946,
                            "bunkerCategoryCode": "DO"
                        }
                    },
                    {
                        "key": 6130468,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916944,
                            "bunkerCategoryCode": "FO"
                        }
                    }
                ]
            },
            {
                "key": 6130398,
                "event": {
                    "key": 1000050,
                    "eventCode": "ARR"
                },
                "robs": [
                    {
                        "key": 6130445,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916945,
                            "bunkerCategoryCode": "FL"
                        }
                    },
                    {
                        "key": 6130456,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916944,
                            "bunkerCategoryCode": "FO"
                        }
                    },
                    {
                        "key": 6130463,
                        "rob": 230.78559444257462,
                        "bunkerCategory": {
                            "key": 916947,
                            "bunkerCategoryCode": "DL"
                        }
                    },
                    {
                        "key": 6130471,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916946,
                            "bunkerCategoryCode": "DO"
                        }
                    }
                ]
            },
            {
                "key": 6130393,
                "event": {
                    "key": 6088041,
                    "eventCode": "UBRT"
                },
                "robs": [
                    {
                        "key": 6130442,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916945,
                            "bunkerCategoryCode": "FL"
                        }
                    },
                    {
                        "key": 6130443,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916944,
                            "bunkerCategoryCode": "FO"
                        }
                    },
                    {
                        "key": 6130453,
                        "rob": 230.53559444257462,
                        "bunkerCategory": {
                            "key": 916947,
                            "bunkerCategoryCode": "DL"
                        }
                    },
                    {
                        "key": 6130466,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916946,
                            "bunkerCategoryCode": "DO"
                        }
                    }
                ]
            },
            {
                "key": 6130397,
                "event": {
                    "key": 1000052,
                    "eventCode": "DEP"
                },
                "robs": [
                    {
                        "key": 6130446,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916945,
                            "bunkerCategoryCode": "FL"
                        }
                    },
                    {
                        "key": 6130449,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916944,
                            "bunkerCategoryCode": "FO"
                        }
                    },
                    {
                        "key": 6130455,
                        "rob": 0.0,
                        "bunkerCategory": {
                            "key": 916946,
                            "bunkerCategoryCode": "DO"
                        }
                    },
                    {
                        "key": 6130465,
                        "rob": 230.53559444257462,
                        "bunkerCategory": {
                            "key": 916947,
                            "bunkerCategoryCode": "DL"
                        }
                    }
                ]
            }
        ]
    }
]

POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....

{
    "vesselReportType": "ARR",
    "reportDateLocal": "2024-08-02T02:58:00",
    "portCall": 3345932, //key from the response of the PortCall request
    "eventLogs": [{"event": "ARR", "eventLogDate": "2024-08-02T03:00:00"}],
    "robFo": 225.85,
    "robDl": 235.0
}

POST /ws/rest/Remark HTTP/1.1

{
    source: 5535223, //key from the response of PositionReport request
    "remark": "Arrival on the port remark"
}

GET /ws/rest/PortCall?filter=voyage.voyageHeader.referenceNo(LKIC)TST001&port.portName(LKIC)Bergen case insensitive HTTP/1.1
Authorization: Bearer ....

POST /ws/rest/PositionReport HTTP/1.1
Host: BASEURL
Content-Type: application/json
Authorization: Bearer ....

{
    "vesselReportType": "ARR",
    "reportDateLocal": "2024-08-02T02:58:00",
    "portCall": 3345932, //key from the response of the PortCall request
    "eventLogs": [{"event": "ARR", "eventLogDate": "2024-08-02T03:00:00"}],
    "robFo": 225.85,
    "robDl": 235.0
}