Marcura

&lt;img src="https://content.pstmn.io/9e5ad1a4-82ee-46d6-9141-5e7b7f9c84b1/ZG93bmxvYWQuc3Zn" width="150" height="100">

This service made to share different maritime datasets. **Marcura** has 15 years expertise in maritime industry and has huge network of agent and charterers. It has rich data collection on **costs**, **locations**, **polygons, vessels restrictions**, **tradeflows** and **lineups**. This service is extension to [**Portlog**](https://desktop.postman.com/?desktopVersion=10.13.0&userId=27133318&teamId=0)

The base url of the set API endpoints is [https://data.portlog.com/](https://data.portlog.com/)

Marcura API

Authentication

Bearer Token

API Key

Commodities

Get commodity mapping

Locations

Port Location

Terminal Location

Berth Location

Port Costs v1

Get Port Cost

Get Terminal Stats

Port Costs v2

Retrieve the port costs for all available vessel segments and operation types (loading/discharging) for a given location and commodity. Response includes indication whether cost includes towage and also DWT range of a returned vessel segment. For details please refer to request/response examples on the right.

Get Costs Per Segment

Restrictions

Restrictions All

Working Hours

PortLog PRO operations to predict voyage.

PortLog PRO

Retrieve laytime predictions (turnaround, paid, unpaid and demurrage/despatch days), most likely cost and voyage alerts for a single or multiple voyages. Each voyage includes multiple itineraries/portcalls and has unique <code>estimateId</code> which can be used to retrieve the results later. Itineraries require only port as input parameter, <b>PortLog</b> will predict terminal based on the itinerary details like commodity, vessel size, charterer, etc. Cargoes can be used across whole voyage or only by single itineraries/portcalls. They are referenced using unique <code>cargoSeq</code>. For details please refer to request/response examples on the right.

Predict voyage

Retrieve available CP templates with defined terms.

Get CP templates

Retrieve available working hour templates.

Get working hour templates

Retrieve a list of saved ProSnapshots by IMOS estimate ID. Returns summary information including the proSnapshotRequest field from the JSON, without PDF data. Each snapshot contains the original request parameters and metadata about when it was created and by whom.

Get snapshots by IMOS estimate ID

Retrieve a saved ProSnapshot by ID as JSON. Returns the complete snapshot data including the original request, selected terminal snapshot, and all alternative terminal snapshots with their respective laytime calculations, costs, restrictions, insights, and alerts.

Get snapshot by ID as JSON

Retrieve a saved ProSnapshot by ID as PDF file for download. The PDF contains a comprehensive report with laytime calculations, cost analysis, terminal comparisons, restrictions summary, insights, and alerts for the selected voyage segment. The file is automatically downloaded with the filename format 'prosnapshot-{snapshot_id}.pdf'.

Get snapshot by ID as PDF

PortLog OTA predicts the optimal time of arrival (OTA) by calculating laytime and port costs for any arrival scenario of your port calls.

PortLog OTA

Performs laytime and PnL predictions for a provided set of estimated arrival times.<br>The Interface Unique Reference (IUR) is used to map all necessary portcall data like vessel, port, operation, commodity and other relevant commercial terms from external voyage provider.The API will return the mapped portcall details and a scenario for each provided ETA with laytime result information and PnL impact

Calculate laytime and costs for OTA scenarios

Lineups V2

Crude oil

Liquid bulk

Dry cargo

Grains

Coal

Iron ore

Terminal Predictor

Predicts terminals in port based on given parameters: port, commodity, operation, DWT. The API will return a list of terminals, together with a percentage score for each terminal, indicating the likelihood of the terminal being selected for the commodity/operation/vessel's DWT.

Predicts terminals in port based on given parameters: port, commodity, operation, DWT

PortLog Insights provides access to your own insights from PortLog for both dry and tank.

PortLog Insights

Gets all own insights from both dry and tank entitlements in json format.

Gets all own insights

Downloads an attachment file associated with an insight. The file can be of any media type.

Downloads insight attachment file

Time in Port

Return the activity breakdown as shown in Time tab + the additional field of calculated days alongside based on the activity duration summary between All Fast and Last Line Ashore. For details please refer to request/response examples on the right.

Get Time In Port

Tradeflows

Everything

Iron Ore

Tradeflows V2

Crude Oil

Liquid Bulk

Commodities at Berth

Commodity detailed level

Commodity level

Facility Operators

Get Facility Operator

Agency Locations

DA-Desk Operator APIs are a set of REST APIs delivered using JSON data format and served over HTTPS. DA-Desk exposes several APIs however this document will focus on the most popular set to keep the document as bite size as possible. While DA-Desk makes best efforts in keeping these API fully backward compatible, in some rare cases changes need to be made. In the event of such changes, the point of contact will receive a notification with ample time to be ready for the change. These APIs use mainly the DA-Desk internal IDs for retrieving and referring to information, however integration codes for agents/suppliers, ports and vessels are passed along with the responses to help the customers integrate the information with their internal systems.

The APIs are hosted behind a CDN (Amazon Cloudfront). If an IP filter is required, please check the IP Range of Cloudfront that applies to your region: [https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/LocationsOfEdgeServers.html](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/LocationsOfEdgeServers.html)

The Production API is hosted on [https://api.marcura.com/dad](https://api.marcura.com/dad).

The Test API is hosted on [https://api.cuat.marcura.com/dad](https://api.cuat.marcura.com/dad).

## Authentication

DA-Desk API uses the shared Marcura API authentication.

All API calls require a valid authenticated user session. Once authentication is performed successfully, a session token is generated and returned. This token needs to be used in every subsequent API call by passing it as a query parameter _?token=_.

Authentication can be performed by calling the shared Marcura API _/auth_.

## Service ID and Version

_serviceId_ and _serviceVersion_ are query parameters used by DA-Desk APIs for tracking and debugging. These parameters are mandatory in all API calls except the authentication. The _serviceId_ should contain your integration application name and _serviceVersion_ should contain the version of the application. Both parameters are of type String.

Example:

`?serviceId=customerXXXIntegration&serviceVersion=1.0`

DA-Desk (Operators)

Searching for DAs can be done using the DA-Desk Operator search API. There are plenty of parameters that this API supports, here below we show an example based on last updated date, filtering for actionable DAs for the user vessel list only and on DA type of MAIN ordering the response by ETA in descending order. The API also support a free text search which is available under the parameter of _text_ as shown in the example. The response of this API is paginated and scrolling through the pages is allowed. However there is a limit of 10,000 entries available in the scroll. If more results are required, please consider changing the search criteria to limit the response size.

DA Search

Once a list of Das is acquired that need to get information for, the DA Details API can be called which will have all the information in one place include details such as the agent full contact details, the nomination type, the exchange rates, the cost information including vouchers, credit notes and many more. This API has integration codes for agent.

DA Details

While the DA details API might contain most of the information requires, a portcall details API is also available that contains more information about the portcall itself including the vessel, port, agent, contracts selected, the full set of agent instructions, the header and footer, the portcall contact persons, internal references and others. It also includes information such as max port costs, timebar and more. The portcall ID can be obtained from the search API or the DA Details API. This API has integration codes for agent, vessel and port.

Portcall Details

The DA goes through several different phases throughout its life such as agent appointed, PDA submitted … all the way through to DA Compete. To retrieve the history of a particular DA, the history API can be used which returns events together with timestamps and the persons involved.

DA History

The DA Download API is a multipurpose API that in summary generates a DA coversheet as a PDF file and prepares it for download. The coversheet depends on the current DA status so calling this API throughout the lifecycle of the DA will give you a different coversheet. For example calling this API after completing PDA Approval, will generate a PDA Approved Coversheet. After the DA has been submitted for FDA operator to agree, this API generates a coversheet and optionally attaches all the invoices linked to this DA. The query parameter _withDocs_ which accepts a Boolean enables or disables the addition of all invoices to the download pack. The currency in which the coversheet is generated can also be controlled by the _displayCurrency_ query parameter.

Another query parameter that controls this API: _expCatId_. This query parameter limits the download to one single expense category (the id of which can be extracted from the DA Details API). If the expCatId selected is an Owner’s Cost expense or a Charterer’s Cost expense, the coversheet generated will become an Owner’s Coversheet or a Charterer’s Coversheet respectively. The invoices attached to this coversheet will be limited to the ones that appear in the selected expense category only.

After the agent submits the FDA and before DA-Desk processes the DA and moves it to FDA for operator to agree, there is another temporary coversheet that can be downloaded to specifically help generating charterer’s expenses if the timebar is approaching and the DA is stuck somewhere in between. This document can be downloaded by supplying the query parameter: _fdaLetter_\=true and will generate a coversheet for the FDA as submitted by the agent.

DA Download

If instead of a coversheet and a whole pack, it is required to obtain individual documents (invoices, credit notes …) to be download for segregation, this API allows you to download the individual documents of a DA by ID. The document IDs can be found in the DA Details API within the cost items section. Please note that cost items have a many to many relationship with documents hence if you are scrolling through a DA, the list of document IDs might not be unique.

Individual Document Download

Payments API provides information about approval of payments, in which currency and other relevant information. If PPL services are also availed, this API will provide information on whether the PPL payment was executed or not. One DA can have multiple payments such as advance and balance. On top, calling this API on the Main DA, it will actually provide a consolidated view including all Supplementary Das and Vendor Invoices.

DA Payments

DA-Desk also offers a set of reports with some pre-computed data that might be interesting for the customer. There are 14 reports in total but some of these reports might not be applicable for the customer. Also reports require permission to be given to by the administrator. To retrieve the list of reports available to you, the following API can be used

Reports

Each report has a different search criteria available. To retrieve the search criteria list of a report use the following API.

Report Criteria

Each report also returns a different result set which can be retrieved using the following API.

Report Columns

Finally the actual search API can be triggered through the following call.

Report Data

# DA-Desk (Agents)

DA-Desk Agents APIs are a set of REST APIs delivered using JSON data format and served over HTTPS. DA-Desk exposes several APIs however this document will focus on the most popular set to keep the document as bite size as possible. While DA-Desk makes best efforts in keeping these API fully backward compatible, in some rare cases changes need to be made. In the event of such changes, the point of contact will receive a notification with ample time to be ready for the change.

The APIs are hosted behind a CDN (Amazon Cloudfront). If an IP filter is required, please check the IP Range of Cloudfront that applies to your region: [https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/LocationsOfEdgeServers.html](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/LocationsOfEdgeServers.html)

The Production API is hosted on [https://api.marcura.com/dad](https://api.marcura.com/dad).

The Test API is hosted on [https://api.cuat.marcura.com/dad](https://api.cuat.marcura.com/dad).

## Authentication

DA-Desk API uses the shared Marcura API authentication.

All API calls require a valid authenticated user session. Once authentication is performed successfully, a session token is generated and returned. This token needs to be used in every subsequent API call by passing it as a standard HTTP Authorization Bearer token in the form of: _Authorization: Bearer_ .

Authentication can be performed by calling the shared Marcura API _/auth_. Please refer to the documentation under [<i>Authentication -&gt; Bearer Token</i>](https://developers.marcura.com/marcura/api/)_._

## Service ID and Version

_serviceId_ and _serviceVersion_ are query parameters used by DA-Desk APIs for tracking and debugging. These parameters are mandatory in all API calls except the authentication. Both parameters are of type String and both can take any (made up) value as long as it is consistent through all the calls. Basically both should be constant, where the serviceVersion should be changed on every customer integration release to identify the different versions. The _serviceId_ should contain your (made up) integration application name and _serviceVersion_ should contain the version of the application.

Example:

`?serviceId=dadesk--integration&serviceVersion=1.0`

DA-Desk (Agents)

Searching for DAs can be done using the DA search API. There are plenty of parameters that this API supports, here below we show an example based on last updated date, filtering for specific status group of "New Appointment Please Accept". The response of this API is paginated and scrolling through the pages is allowed. However there is a limit of 10,000 entries available in the scroll. If more results are required, please consider changing the search criteria to limit the response size.

DA Status Groups

Once a list of Das is acquired that need to get information for, the DA Details API can be called which will have all the information in one place include details such, the exchange rates, the cost information, including cost items, vouchers, credit notes and many more. The API also includes information on what actions can be performed on the DA in this current status.

Information about the portcall can be retireved using the portcall details API. This information includes the vessel, port, contracts selected, the full set of agent instructions, the header and footer, the portcall contact persons and others. It also includes information such as max port costs, timebar and more. The portcall ID can be obtained from the search API or the DA Details API.

Once an agent has been appointed by an operator, the confirmation of acceptance of the appointment is required. That is performed by calling the Accept and Submit API which tells DA-Desk that the agent is accepting the appointment and will be submitting the PDA.

Accept and Submit

This API can be used to push information into the proforma DA including:

- Currency
    
- Reference numbers
    
- Comments
    
- Contact Person
    
- Proforma Basis
    
- Estimated time of Departure
    
- others...

Update PDA

DA Cost Item Search/Create 

Update the value of the cost item. Supplying the query parameter advancePercent=true will automatically re-calcalculate the advance based on the percentage specified in the DA.

Update Cost Item

Add a comment to the cost item. This will be particularly useful is the agent can push relevant information such as how this value was computed and tariff explanations.