Moscord API: Developers User Manual

Overview
How to Integrate

Overview

Moscord API enables your business to easily integrate the requisitions to your PMS system. Further, we provide a suite of convenient APIs by using the standard REST interface and response of JSON format.

How to Integrate

There are 5 simple steps to integrate to Moscord API to your PMS system.

1. Request for an API Key for Sandbox Environment

Integration involves programming your application to communicate with Moscord API. But first we need to secure the APIs so that it is only you who can view and process requisitions that belongs to you.

Upon requesting an API Key, we will onboard you on our API Platform and point it to our Sandbox environment. Consider this as the testbed while you are still setting up your application.

2. Request to Onboard your Vessels list in the Marketplace

A Vessels list is an Excel file which contains all vessel IMO numbers and their IP Address. You can forward to us your Excel file and we will upload them for you.

Alongside this process, we will be generating a Secret Key for each vessel IMO number in your Vessels Excel file. This is an additional security measure we have in place in order to ensure that the actual Vessel can access its requisitions.

3. Using Your API Key and Secret Keys

Once you have your API Key and Secret Keys in place, every time you perform an API Request to Moscord API you must specify them as part of the header.

x-api-key: Your-API-Key

x-secret-key: Your-Vessel-IMO's-Secret-Key

4. Getting the List of Requisitions by Vessel IMO Number

Getting the list of your requisitions involves performing a GET request:

HTTP Method: GET
Path: /v1/vessels/{imoNumber}/requests?processStatus=PENDING&type=availabilityRequest&page=1
Headers: 
  x-api-key: Your-API-Key
  x-secret-key: Your-Vessel-IMO's-Secret-Key

Alternatively, it is also possible to get the list of your requisitions by providing a "numberOfRecords" in the query parameters:

HTTP Method: GET
Path: /v1/vessels/{imoNumber}/requests?processStatus=PENDING&type=availabilityRequest&numberOfRecords=100
Headers: 
  x-api-key: Your-API-Key
  x-secret-key: Your-Vessel-IMO's-Secret-Key

If "page" is specified in the query parameters, it will be used and will return up to 50 requisitions per page.
If "numberOfRecords" is used, its value will be used and will return a maximum of 1000 requisitions.
It is possible to combine both the "page" and "numberOfRecords" in the query parameters. The value of "numberOfRecords" will be used with a maximum of 1000 requisitions per page.
If both "page" and "numberOfRecords" were not specified, it will default to use page 1 and will return up to 50 requisitions.

The response will be a JSON format that contains list of your requisitions under the supplied IMO number.

{
  "status": "success",
  "data": {
    "requests": [
      {
        "id": "id1",
        "requestGenerated": "2020-01-06 02:29:54",
        "type": "order",
        "processStatus": "PENDING",
        "description": "Test Order 1",
        "port": "SGAYC - PULAU AYER CHAWAN - SINGAPORE (SG)",
        "requiredDate": "2020-01-07 19:30:00",
        "numberOfPositions": 10,
        "user": "FirstName LastName",
        "userEmail": "testuser@moscord.com"
      },
      {
        "id": "id2",
        "requestGenerated": "2020-01-06 01:29:54",
        "type": "availabilityRequest",
        "processStatus": "IN_PROCESS",
        "description": "Test Availability Request 1",
        "port": "SGAYC - PULAU AYER CHAWAN - SINGAPORE (SG)",
        "requiredDate": "2020-01-08 08:00:00",
        "numberOfPositions": 20,
        "user": "FirstName LastName",
        "userEmail": "testuser@moscord.com"
      }
    ]
  }
}

5. Getting the Details and Items of a Requisition

Getting the details and items of a requisition involves performing a GET request:

HTTP Method: GET
Path: /v1/vessels/{imoNumber}/requests/{requestId}
Headers: 
  x-api-key: Your-API-Key
  x-secret-key: Your-Vessel-IMO's-Secret-Key

The response will be a JSON format that contains the details of the requisition as well as its items.
In each item there will be a "meta" field that can contain all mappings that may be required in your PMS system.

{
  "status": "success",
  "data": {
    "id": "id1",
    "processStatus": "PENDING",
    "type": "order",
    "description": "Test Order 1",
    "requiredDate": "2020-01-08 03:30:00",
    "priority": "Normal supply",
    "port": "SGAYC - PULAU AYER CHAWAN - SINGAPORE (SG)",
    "vesselName": "Vessel 4",
    "vesselImoNumber": "1111111",
    "department": "Cargo-Vessel & Office",
    "remarksToOffice": "Test remarks to office",
    "remarksToSupplier": "Test remarks to supplier",
    "pmUpmRemarks": "Test PM/UPM & Remarks",
    "internalUnitReference": "Test internal unit reference",
    "supplier": "Test Supplier",
    "deliveryPlace": "Test address",
    "requestGenerated": "2020-01-06 02:29:54",
    "currency": "USD",
    "numberOfPositions": 1,
    "user": "FirstName LastName",
    "userEmail": "testuser@moscord.com",
    "items": [
      {
        "meta": {
          "pmsPartNumber": "",
          "pmsProductDescription": "",
          "pmsUnitOfMeasure": ""
        },
        "moscordPartNumber": "40000-XXX-123456",
        "moscordProductDescription": "CHEESE BLUE, BRAND: TEST, 1 KG, COUNTRY OF ORIGIN: DENMARK, TEMPERATURE: CHILLED, ALLERGEN: YES",
        "moscordSize": "",
        "moscordCapacity": "",
        "moscordBrandOrFlag": "TEST",
        "moscordUnitOfMeasure": "KGM",
        "moscordNetPricePerUnitDDP": 0,
        "moscordMinimumOrderQuantity": 1,
        "moscordQuantityOrdered": 100,
        "moscordLineTotalPriceDDP": 0,
        "moscordLeadTime": "",
        "impaCode": "",
        "moscordSupplierPartNumber1": "XXX-123456",
        "moscordSupplierPartNumber2": "",
        "attachment": "This will contain the image of the item in base64 format",
        "attachmentFileName": "This will contain the file name of the attachment",
        "attachmentMimeType": "This will contain the MIME type of the attachment"
      }
    ]
  }
}

6. Updating the Process Status of a Requisition

We provide an API to update the process status of a requisition so as to avoid encountering errors in case you accidentally processed again an already processed requisition.

You can mark them as:

IN_PROCESS: This means that the requisition is being processed.
COMPLETED: This means that you have successfully processed the requisition.
PENDING: This is the default process status once a requisition is created. You can also transition a requisition from IN_PROCESS to PENDING in case you encountered an error, or depending on your use case.

HTTP Method: PATCH
Path: /v1/vessels/{imoNumber}/requests/{requestId}
Headers: 
  x-api-key: Your-API-Key
  x-secret-key: Your-Vessel-IMO's-Secret-Key
Body:
  {
    "processStatus": "IN_PROCESS"
  }

The response will be a JSON format that contains the new process status as well as the details and items of the requisition.

{
  "status": "success",
  "data": {
    "id": "id1",
    "processStatus": "IN_PROCESS",
    "type": "order",
    "description": "Test Order 1",
    "requiredDate": "2020-01-08 03:30:00",
    "priority": "Normal supply",
    "port": "SGAYC - PULAU AYER CHAWAN - SINGAPORE (SG)",
    "vesselName": "Vessel 4",
    "vesselImoNumber": "1111111",
    "department": "Cargo-Vessel & Office",
    "remarksToOffice": "Test remarks to office",
    "remarksToSupplier": "Test remarks to supplier",
    "pmUpmRemarks": "Test PM/UPM & Remarks",
    "internalUnitReference": "Test internal unit reference",
    "supplier": "Test Supplier",
    "deliveryPlace": "Test address",
    "requestGenerated": "2020-01-06 02:29:54",
    "currency": "USD",
    "numberOfPositions": 1,
    "user": "FirstName LastName",
    "userEmail": "testuser@moscord.com",
    "items": [
      {
        "meta": {
          "pmsPartNumber": "",
          "pmsProductDescription": "",
          "pmsUnitOfMeasure": ""
        },
        "moscordPartNumber": "40000-XXX-123456",
        "moscordProductDescription": "CHEESE BLUE, BRAND: TEST, 1 KG, COUNTRY OF ORIGIN: DENMARK, TEMPERATURE: CHILLED, ALLERGEN: YES",
        "moscordSize": "",
        "moscordCapacity": "",
        "moscordBrandOrFlag": "TEST",
        "moscordUnitOfMeasure": "KGM",
        "moscordNetPricePerUnitDDP": 0,
        "moscordMinimumOrderQuantity": 1,
        "moscordQuantityOrdered": 100,
        "moscordLineTotalPriceDDP": 0,
        "moscordLeadTime": "",
        "impaCode": "",
        "moscordSupplierPartNumber1": "XXX-123456",
        "moscordSupplierPartNumber2": "",
        "attachment": "This will contain the image of the item in base64 format",
        "attachmentFileName": "This will contain the file name of the attachment",
        "attachmentMimeType": "This will contain the MIME type of the attachment"
      }
    ]
  }
}

Try Moscord API now.