Disbursement Account Integration API

This API as been Deprecated, use instead Service Order Integration

Short Description

The objective of the Disbursement Account (DA) integration is to transfer port call and port cost data between Dataloy VMS and an agency system in order to correctly assign port costs to the correct port call, vessel and voyage and import this data into the VMS.

Chapter Contents:

Long Description

The Disbursement Process

The Disbursement Account (DA) Process Consists of Two Steps:
1. Appointment of port calls in Dataloy VMS following the step-by-step instructions at Appointment API.
2. Receive DA data from applicable agency system and ensure that Dataloy VMS automatically updates the total cost of the port, voyage and results with the most updated data.

Prerequisites

Before setting up and testing a DA integration the following is required:

Mapping of port cost codes between Dataloy VMS and the agency system (Dataloy VMS: Modules - Master Data - General Master Data Administration - Port Cost Code).
Mapping of handling cost codes between Dataloy VMS and the agency system. (Dataloy VMS: Modules - Master Data - General Master Data Administration - Handling Cost Code).
Mapping of various text codes between Dataloy VMS and the agency system. (Dataloy VMS: Modules - Master Data - General Master Data Administration - Various Text).
Synchronization of business partners between Dataloy VMS and the agency system. (Dataloy VMS: Modules - Master Data - General Master Data Administration - Business Partners).

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

Supported Methods

POST /DisbursementAccount

Insert/Update a disbursement account (DA):
Note: Required fields: portCall, businessPartner, invoiceReference, currency, status, costItems, accountCode, costItemKey. Updating an existing DisbursementAccount: unchanged properties (except required fields) need not be updated.

Insert/Update a DA

POST http://[ip]:[port]/ws/rest/DisbursementAccount/

GET /DisbursementAccount

Not yet implemented.

DELETE/ DisbursementAccount

Not yet implemented.

Example of Disbursement Account JSON Message

Request Body:

Updated for API version 2.0.0 using the new required date format yyyy-dd-MMThh:mi:ss to conform ISO 8601, (prior versions has date format: yyyy-dd-MM hh:mi:ss)

{  
   "portCall":1050921,
   "businessPartner":"50001",
   "agentTypeCode":"OA",
   "proformaReference":"proforma ref",
   "invoiceReference":"da ref",
   "invoiceDate":"2014-01-01T00:00:00",
   "currency":"USD",
   "exchangeRate":1,
   "status":"EST",
   "costItems":[  
      {  
         "accountCode":"101",
         "amount":100,
         "comment":"port cost 1 ",
         "costItemKey":"12345",
         "isOwnersCost":false,
         "isCharterersCost":false
      },
      {  
         "accountCode":"102",
         "amount":400,
         "comment":"port cost 2",
         "costItemKey":"123456"
      },
      {  
         "accountCode":"410",
         "amount":100,
         "comment":"handling cost",
         "costItemKey":"1234567"
      },
      {  
         "accountCode":"411",
         "amount":400,
         "comment":"handling cost 2",
         "costItemKey":"12345678"
      },
      {  
         "accountCode":"BAF",
         "amount":100,
         "comment":"var cost",
         "costItemKey":"123456789"
      }
   ]
}

Properties

Property	Type	Length	Mandatory	Description	Comments
portCall	/PortCall		Yes	Identifier for DA port call.	Port Call ID is to be transferred in the appointment resource. Port Call ID Testing: Dataloy VMS: Booking and Operations > Right-click a Port Call > Select Row > Audit Log > Copy Port Call Record ID.
businessPartner	/BusinessPartner		Yes	Code for the business partner/agent.	Dataloy Agent Codes have to be retreived from Dataloy VMS. Code Retrieval: Dataloy VMS: BusinessPartner resource: BusinessPartner?filter=businessPartnerType.businessPartnerType(EQ)A.
agentTypeCode	/PortAgentType			Code of the agent type.
proformaReference	String	16		Proforma reference.
invoiceReference	String	16	Yes	Invoice reference/DA reference.
invoiceDate	Date			Invoice date.
currency	/Currency		Yes	Currency of the DA.
exchangeRate	/ExchangeRate			Exchange rate from the DA currency to the voyage currency.
status	/StatusType		Yes	Status of the DA (see DA Status List).
costItems	Array of /CostItem		Yes

Properties

Property	Type	Length	Mandatory	Description	Comments
accountCode	/PortCostCode /HandlingCostCode /VariousText		Yes	Account code of the cost.
amount	Double		Yes	Cost amount in DA currency.
comment	String	1024		Comment related to the cost.
costItemKey	String	16	Yes	Identifier of this cost in the agency system.	A key from the agency system on line level. This is for the API to distinguish the lines and update the correct one in the different phases estimate, revised and final.
isOwnersCost	Boolean			True if this is an owner's cost.	ONLY applicable to costs with port cost account code.
isCharterersCost	Boolean			True if this is a charterer's cost.	ONLY applicable to costs with port cost account code.

List of Disbursement Account (DA) Statuses in Dataloy VMS

Code	Code Description	Description
EST	Estimate	Proforma stage of the DA.
REV	Revised	Revised stage of the DA.
FIN	Final	Final stage of the DA.

Supplementary DA's should use status type FIN

Disbursement Account (DA) Stages

Dataloy VMS supports insertion/updates of proforma disbursement accounts (PDAs), revised disbursement accounts (RDAs) and final disbursement accounts (FDAs).

Inserting (or Updating) a Disbursement Account (DA)
- To insert (or update) a disbursement account (DA) into Dataloy VMS post a populated JSON message (see JSON example) to the Dataloy API.
- Fields required to be populated when posting a DA to Dataloy VMS: portCall, businessPartner, invoiceReference, currency, status, accountCode, costItemKey.
  Note: When updating an existing DisbursementAccount, unchanged properties (except required fields) need not be updated. The insertion process is shown in Fig. 1 (see Validations).
Validations
Prior to inserting/updating the DA in Dataloy VMS, the following validations will be performed on the JSON message:
1. Are the required fields populated?
  1. Yes: Continue Insertion.
  2. No: Nothing is inserted and a HTTP status code is returned.
2. Does the Port Call, Business Partner, Agent Type (if populated), Currency and Status exist in Dataloy VMS?
  1. Yes: Continue Insertion.
  2. No: Nothing is inserted and a HTTP status code is returned. Also, the status codes are returned in the HTTP header, additional information will be provided in the body in JSON format.
3. Does the account code exist in Dataloy and is it unique?
Fig. 1
Inserting (or Updating) a Proforma Disbursement Account (PDA)

Populate the status field in the JSON message with EST (Estimate) and post a DA JSON message to the Dataloy API.
Note: The status field must be populated with EST in order for the VMS to treat it as a PDA.
Validate the JSON message.

Validated: Insert Disbursement Account (DA).
Not validated: Return Error.

Inserting (or Updating) a Revised Disbursement Account (RDA)

Populate the status field in the JSON message with REV (Revised) and post a DA JSON message to the Dataloy API.
Note: The status field must be populated with REVin order for the VMS to treat it as a RDA.
Validate the JSON message.

Validated: Insert Disbursement Account (DA).
Not validated: Return Error

Inserting (or Updating) a Final Disbursement Account (FDA)

Populate the status field in the JSON message with FIN (Final) and post a DA JSON message to the Dataloy API.
Note: The status field must be populated with FIN in order for the VMS to treat it as a FDA.
Validate the JSON message.

Validated: Insert Disbursement Account (DA).
Not validated: Return Error.

Verifying Inserted (or Updated) Disbursement Accounts (DAs) in the VMS

To View Inserted/Updated Disbursement Accounts (DAs):

Go to Modules > Booking and Operations > Port Call Browser.
The Port Call Browser window will open.
Select the port call the DA belongs to.
To view:
1. port costs related to selected port call: click the Port Cost tab.
2. handling costs related to selected port call: click the Handling Cost tab.
Selected data will display with the DA header information in the top list and the individual cost items in the bottom list.

To View the Various Costs Entered:

Go to Modules > Booking and Operations > Booking and Operations.
The Booking and Operations window will open.
Select the voyage the port call belongs to.
Select the Various Cost/Revenue tab in the Schedule list (bottom list).
Click on the Voyage button (costs are currently inserted on voyage level).

Note: Currently the disbursement account (DA) stage (PDA etc.) cannot display in Dataloy VMS. However, if the amounts are estimates, the Amount LC (Estimated) column is populated. If they are revised/final amounts, the Amount LC (Revised)/Amount LC (Actual) column is populated. This ONLY applies to Port Cost and Handling Cost. The Various costs has ONLY a single amount, i.e. NO estimate/revised amounts. The examples of inserted disbursement accounts in Figures 2, 3 and 4 all shows where the DAs in the JSON example are inserted in Dataloy VMS.

Fig. 2: DA Port Costs