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:
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:
Note: Recommended before proceeding - read: Getting Started with Dataloy REST API.
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.
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" } ] } |
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. | |
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 |
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. |
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
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)
Fig. 1
To View Inserted/Updated Disbursement Accounts (DAs):
Modules > Booking and Operations > Port Call Browser.
To View the Various Costs Entered:
Modules > Booking and Operations > Booking and Operations.
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
Fig. 3: DA Handling Costs
Fig 4: DA Various Costs
|