This article provides several use cases to help you understand how to integrate with GoFreight REST APIs.

Example I: Creating and Viewing Ocean Shipments

This example will guide you through the steps required to create an Ocean Import MB/L using our API and subsequently view the details using the Shipment Master Bills API.

Create an Ocean Import MB/L

API Endpoint:

POST /shipments/ocean-import/mbl/

The API provides you with the ability to create an ocean import MB/L (master bill of lading). You can also create containers and H/BL (house bill of lading) associated to the MB/L.

curl --request POST \
    --url https://api.core.gofreight.co/api/v1/shipments/ocean-import/mbl/ \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --header 'X-GATEWAY-TOKEN: {{your-api-key}}' \
    --data '{
    "data": [
        {
            "mbl_no": "MB12345678",
            "port_of_loading": "USLAX",
            "port_of_discharge": "CNTAO",
            "estimated_arrival_date": "2023-07-20T08:15:30",
            "estimated_departure_date": "2023-07-10T08:15:30",
            "vessel_name": "APL SENTOSA",
            "voyage": "0BX3WE1MA",
            "ship_mode": "FCL",
            "service_term_from": "CY",
            "service_term_to": "CY",
            "carrier": "MAEU",
            "oversea_agent": "OVTI",
            "weight_unit": "KG",
            "measurement_unit": "CBM",
            "hbl_list": [
                {
                    "hbl_no": "HB12345678",
                    "shipper": "SHPR",
                    "consignee": "CNEE",
                    "notify": "NTFY",
                    "service_term_from": "CY",
                    "service_term_to": "CY"
                }
            ],
            "container_list": [
                {
                    "container_no": "TCLU1234567",
                    "seal_no": "SEAL123",
                    "container_type_size": "20GP",
                    "weight": 18000.0,
                    "measurement": 28.0,
                    "pickup_no": "PICK123",
                    "is_available_for_pickup": true,
                    "pickup_date": "2023-07-01T10:00:00",
                    "last_free_date": "2023-07-30",
                    "empty_return_date": "2023-08-01"
                }
            ]
        }
    ]
}'

After a successful request, you’ll receive a response similar to this one:

{
    "data": [
        {
            "ref": "A2300905",
            "uri": "/api/v1/shipments/ocean-import/mbl/?ref=A2300905",
            "hbl_list": [
                {
                    "ref": "27435",
                    "uri": "/api/v1/shipments/ocean-import/hbl/?ref=27435"
                }
            ],
            "container_list": [
                {
                    "ref": "42874",
                    "uri": "/api/v1/shipments/containers/42874/"
                }
            ]
        }
    ]
}

Retrieve M/BL

API Endpoint:

GET /api/v1/shipments/master-bills/

Once you have created the ocean shipment, you may want to view the associated Shipment Master Bills. The Shipment Master Bills API provides you with the ability to retrieve Shipment Master Bills, which are master bills of lading related to ocean freight shipping and airway bills related to air freight shipping.

curl --request GET \
    --url 'https://api.core.gofreight.co/api/v1/shipments/master-bills?\
        page=1& \
        limit=10& \
        transportation_mode=OI& \
        port_of_loading=USNYC& \
        port_of_discharge=GBLON& \
        post_date.gt=2023-01-01& \
        post_date.gte=2023-01-01& \
        post_date.lt=2023-07-25& \
        post_date.lte=2023-07-25& \
        ocean_shipment.mbl_no=MBL12345& \
        air_shipment.mawb_no=MAWB67890' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --header 'X-GATEWAY-TOKEN: {{your-api-key}}'

Please note that the transportation_mode parameter is required, and its possible values are ‘OI’, ‘OE’, ‘AI’, and ‘AE’.

After a successful request, you’ll receive a response similar to this one:

{
    "meta": {
        "total": 0,
        "current_page": 0,
        "total_pages": 0
    },
    "data": [
        {
            "ref": "string",
            "post_date": "2019-08-24",
            "transportation_mode": "OI",
            "service_term_from": "CY",
            "service_term_to": "CY",
            "estimated_departure_date": "2019-08-24T14:15:22Z",
            "actual_departure_date": "2019-08-24T14:15:22Z",
            "estimated_arrival_date": "2019-08-24T14:15:22Z",
            "actual_arrival_date": "2019-08-24T14:15:22Z",
            "port_of_loading": {
                "ref": "string",
                "uri": "string"
            },
            "port_of_discharge": {
                "ref": "string",
                "uri": "string"
            },
            "carrier": {
                "ref": "string",
                "uri": "string",
                "name": "string"
            },
            "oversea_agent": {
                "ref": "string",
                "uri": "string",
                "name": "string"
            },
            "ocean_shipment": {
                "ref": "string",
                "uri": "string",
                "mbl_no": "string",
                "ship_mode": "FCL"
            },
            "air_shipment": null
        }
    ]
}

The response will contain a meta part with information about the total number of shipments, the current page, and the total number of pages, and a data part with an array of Shipment Master Bills objects.

Example II: Get container

API Endpoint:

GET /api/v1/container

The Get Container API offers the ability to retrieve information about a specific shipping container. This data includes details such as the container’s reference number, its number and seal number, its type and size, its weight and measurement, pickup details, and dates pertaining to its usage.

The Container JSON object is returned in every successful HTTP GET response for the Container API. This object provides a detailed summary of a particular container’s data. This includes critical details such as the reference, container number, seal number, container type/size, weight and its unit, measurements and its unit, pickup number, the availability of the container for pickup, and dates related to pickup and return.

To retrieve the information of a container, you’ll need to make an HTTP GET request to the Container API:

curl --request GET \
    --url https://api.core.gofreight.co/api/v1/shipments/containers/{{ref}}/ \
    --header 'Accept: application/json' \
    --header 'X-GATEWAY-TOKEN: {{your-api-key}}'

After a successful request, you’ll receive a response similar to this one:

{
    "ref": "CONTAINER1234",
    "container_no": "ABC123XYZ",
    "seal_no": "SN7890",
    "container_type_size": "20FT",
    "weight": 18000,
    "weight_unit": "KG",
    "measurement": 30,
    "measurement_unit": "CBM",
    "pickup_no": "PICKUP123",
    "is_available_for_pickup": true,
    "pickup_date": "2023-07-25T08:30:00",
    "last_free_date": "2023-07-30",
    "empty_return_date": "2023-07-31"
}

Example III: Custom Field Integration

Custom Field Integration offers the ability to customize fields in shipment or invoice. Take Ocean Import MB/L for an example as below, you can:

  1. Retrieving available custom fields for Ocean Import MB/L
  2. Create an Ocean Import MB/L with available custom fields

Step 1: Retrieve Available Custom Fields

API Endpoint:

GET /api/v1/shipments/ocean-import/mbl/custom-field/

The Custom Field JSON array object is returned in every successful HTTP GET response for the Custom Field API. This object provides the list of detailed custom field’s data. The detail includes critical details such as the name, label, description and custom field type.

To retrieve the list of available custom fields, you’ll need to make an HTTP GET request to the Custom Field API:

curl --request GET \
    --url https://api.core.gofreight.co/api/v1/shipments/ocean-import/mbl/custom-field/ \
    --header 'Accept: application/json' \
    --header 'X-GATEWAY-TOKEN: {{your-api-key}}'

After a successful request, you’ll receive a response similar to this one:

{
    "data": [
        {
            "name": "custom_field_1",
            "label": "Custom Field 1",
            "description": "Custom Field 1 Description",
            "type": "text"
        },
        {
            "name": "custom_field_2",
            "label": "Custom Field 2",
            "description": "Custom Field 2 Description",
            "type": "text"
        }
    ]
}

Step 2: Create an Ocean Import MB/L with available custom fields

Next, once you’ve retrieved the list of available custom fields, you’ll be able to create the Ocean Import MB/L with these fields inside $cf object by making an HTTP POST request.

curl --request POST \
    --url https://api.core.gofreight.co/api/v1/shipments/ocean-import/mbl/ \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --header 'X-GATEWAY-TOKEN: {{your-api-key}}' \
    --data '{
    "data": [
        {
            "mbl_no": "MB12345678",
            "port_of_loading": "USLAX",
            "port_of_discharge": "CNTAO",
            "estimated_arrival_date": "2023-07-20T08:15:30",
            "estimated_departure_date": "2023-07-10T08:15:30",
            "vessel_name": "APL SENTOSA",
            "voyage": "0BX3WE1MA",
            "ship_mode": "FCL",
            "service_term_from": "CY",
            "service_term_to": "CY",
            "carrier": "MAEU",
            "oversea_agent": "OVTI",
            "weight_unit": "KG",
            "measurement_unit": "CBM",
            "hbl_list": [
                {
                    "hbl_no": "HB12345678",
                    "shipper": "SHPR",
                    "consignee": "CNEE",
                    "notify": "NTFY",
                    "service_term_from": "CY",
                    "service_term_to": "CY"
                }
            ],
            "container_list": [
                {
                    "container_no": "TCLU1234567",
                    "seal_no": "SEAL123",
                    "container_type_size": "20GP",
                    "weight": 18000.0,
                    "measurement": 28.0,
                    "pickup_no": "PICK123",
                    "is_available_for_pickup": true,
                    "pickup_date": "2023-07-01T10:00:00",
                    "last_free_date": "2023-07-30",
                    "empty_return_date": "2023-08-01"
                }
            ],
            "$cf": {
                "custom_field_1": "value_1",
                "custom_field_2": "value_2"
            }
        }
    ]
}'

After a successful request, the values of custom fields will be added in the shipment.

Example IV: Using GoFreight API to Printing an Invoice PDF

This document describes how to use the GoFreight API to generate a PDF and check the status of the generation task.

Initiating Print Task

The Print Invoice by Ref. API endpoint allows you to initiate an asynchronous task for generating PDF of a specific invoice.

Input:

The API call uses a POST request to the following URL:

POST /api/v1/invoices/{ref}/print

Replace {ref} with the actual reference number of the invoice you want to print.

Output:

Upon successful request, the API responds with a JSON object containing the following properties:

  • ref: This is a reference string for the asynchronous generation task.
  • uri: This is the URI you can use to check the status of the generation task.

Example Usage:

curl --request POST \
  --url https://api.core.gofreight.co/api/v1/invoices/123456/print \
  --header 'Content-Type: application/json' \
  --header 'X-GATEWAY-TOKEN: {{your-api-key}}'

This example would initiate a generation task for invoice with reference number 123456 and return a response containing the task reference and URI for checking the status.

Checking Print Task Status

The Get status of an async task API endpoint allows you to check the status of your print task using the reference obtained from the previous API call.

Input:

The API call uses a GET request to the following URL:

GET /api/v1/async-tasks/status/{ref}/

Replace {ref} with the reference string obtained from the print invoice API response.

Output:

The API responds with a JSON object containing the following properties:

  • status: This indicates the current status of the async task. Possible values include:
  • message: This provides an optional message related to the task status (might be empty).
  • uri: If the status is SUCCESS, this contains the URI to access the async task result (e.g., the PDF invoice).

Example Usage:

curl --request GET \
  --url https://api.core.gofreight.co/api/v1/async-tasks/status/abc123 \
  --header 'X-GATEWAY-TOKEN: {{your-api-key}}'

This example would check the status of the async task with reference abc123.

Retrieving Print Result (if successful)

Once the print task status is SUCCESS, you can use the provided uri from the status check API to retrieve the actual print result (e.g., PDF invoice). The format of the retrieved data depends on the specific result type.

Example Usage:

Assuming the status check API returned a uri like: https://api.core.gofreight.co/api/v1/async-tasks/result/abc123

curl --request GET \
  --url https://api.core.gofreight.co/api/v1/async-tasks/result/abc123 \
  --header 'X-GATEWAY-TOKEN: {{your-api-key}}'

This would retrieve the task result (a PDF invoice)