Service Order Integration API

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. ServiceCode.

2. ServiceOrder.

3. ServiceOrderLine.

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
}

Adjust Number of Fields to be Returned from a Request

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.

The integration can change an existing Service Order through HTTP PUT, see ServiceOrder, ServiceOrderLine.

To add a new line to a a order:

PUT:https://url/ws/rest/ServiceOrder/{ServiceOrder_key}

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

Auto Posting of Invoices

Auto posting of service order invoices is supported for integrations with external agency systems. This feature allows invoices to be automatically posted when service orders are updated via the API.

A key prerequisite is configuring the Auto Post Service Order system setting. This setting determines the service order status from which auto posting is enabled and includes invoicing properties such as Default Payment Term and Default Baseline Term.

Once configured, it's essential to include the autoPost = true HTTP header in all PUT requests to service orders and/or service order lines. This will trigger the automatic posting of the invoices based on the updated data.

Important Note

• Manual Changes Will Not Trigger Auto Posting

  • Changes made via the VMS client UI (manually by users) will NOT trigger auto posting. This feature is exclusive to API-based integrations.

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