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"
        }
    ]   
}

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.

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

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

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"
        }
    ]
}

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.

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"}

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.

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"
}

Prerequisites

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

• Invoice Integration

• Actuals Integration

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 Accruals and Period-End-Closing.

Data Transactions

To get accruals 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(\"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

Test data for accruals integration can be generated in the Accruals module in Dataloy VMS. Generate and batch post the accruals.

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

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.