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:

[ 1 The Disbursement Process ] [ 2 Supported Methods ] [ 3 Properties ] [ 4 Properties ] [ 5 List of Disbursement Account (DA) Statuses in Dataloy VMS ] [ 6 Disbursement Account (DA) Stages ] [ 7 Verifying Inserted (or Updated) Disbursement Accounts (DAs) in the VMS ]

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

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

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.