Cargofive Last update: 07-12-2020

Cargofive is a platform that allows you to search, compare and manage maritime freight rates between different shipping companies in record time, managing to obtain quotes in just a few minutes.

APIs

API Rest

API is a set of rules and specifications that applications can follow to communicate with each other. So that we understand it, the use of an API is the most useful mechanism to connect two softwares with each other, in this way, we can guarantee the exchange of messages or data in standard format.

  • Available operations

    • The operations available in the API environment are POST (create), GET (read and query), PUT (edit) and DELETE (delete).

First steps API Cargofive

  • Get API Key

    • In order to access the Cargofive API, you will need to have a registered and active user on our platform. Once this is accomplished, you must request the additional credentials that will allow you to obtain an access token. From Cargofive you will be provided with all the necessary data to complete this process.

  • Testing with Potsman

    • Before doing a full integration you will probably want to run some tests. For this you can use the Postman application, a brief explanation of how to install and use it correctly will be given below.

  • Postman installation

    • To install Postman you must access the site https://www.postman.com/downloads and proceed to download the installer compatible with your operating system.

  • Essential tests

    • After installing Postman, you can begin to perform the necessary tests. In this section we will use some endpoints of the Cargofive API that will be explained in detail later.

    • Headers

      • Before making a request, you must configure the corresponding headers:

      Content-Type: application/json

      X-Requested-With: XMLHttpRequest

    • Get Bearer Token

      • To perform an operation on the Cargofive API, you must have a valid Bearer Token, which certifies that it is correctly authenticated.

      To obtain the Bearer Token you will have to make a POST call to the endpoint https://app.cargofive.com/oauth/token along with the following parameters that you must configure in the Body tab by selecting form-data:

      • client_id:The client id that has been provided by Cargofive.
      • client_secret:The client secret that has been provided by Cargofive.
      • grant_type: Here you must put "password".
      • username: The email with which you are registered in Cargofive.
      • password: The password you use to enter Cargofive.

      When completing the request, you will be given the "access_token" with which you can access the different endpoints of the Cargofive API. To do this, you must copy the value between the quotation marks (“) and paste it in the Bearer Token value located in the authorization tab for all the requests that you will make to the Cargofive API.

    • Make a test request

      • By having a valid bearer token (access_token) you can perform the different operations that are allowed by the API. To do this, you must first configure the bearer token obtained in the previous process. Before making any request, go to the Authorization tab and in the Type drop-down select the Bearer Token option and finally in the token field paste the value of the bearer token (access_token).

      Once the bearer token is configured, it will be ready to make a valid request to the API. In this opportunity, a GET request will be exemplified to consult rates to the following endpoint:

      https://api.cargofive.com/search/rates/group/ORIGIN/DESTINY/START/END/TYPE

      Método: GET

      The parameters to be used on the endpoint are:

      • ORIGIN: Origin port using UN / LOCODE
      • DESTINY: Destination port using UN / LOCODE
      • START: Validity start date (YYYY-MM-DD)
      • END: Validity end date (YYYY-MM-DD)
      • TYPE: DRY, REEFER, OPENTOP y FLATRACK.

      The result of this operation will be a json with the information corresponding to the rates that meet the criteria of the parameters sent.

Endpoints available

To access each endpoint, you must have a valid bearer token. All requests have the following optional parameters available:

  • size (integer): Limits the number of records that a request returns.
  • paginate (integer): Paginate the results according to the indicated value.

Cargofive REST API https://app.cargofive.com/api/v1/

Note that there are some endpoints pointing to the URL: https://api.cargofive.com/

  • Get token

    • URL:https://app.cargofive.com/oauth/token

    Method:POST

    Parameters

    • grant_type: Type of access required by the token generator, its value is "password".
    • username: email to access Cargofive.
    • password: password to access Cargofive.
    • scope: its default value will be *.
    • client_id: Number value provided in the generation of tokens.
    • client_secret: Hash oauth provided in token generation.

    Returns: JSON with Bearer token (access_token).

  • Users

    • URL:https://app.cargofive.com/api/v1/user

    Method:GET

    Returns: JSON with the authenticated user details.

  • List of Quotes (Deprecated)

    • URL:https://app.cargofive.com/api/v1/quotes

    Method:GET

    Parameters

    • Integration: True // If the value is true, the list will only return new and / or recently edited quotes, ignoring those that have already been integrated previously.
    • Type: FCL, LCL o AIR.
    • Status: Win, Draft, Sent.
    • Size: Limits the number of records that the query returns. Enter a integer number.

    Returns: JSON array with the detail of each quote associated with the user who consults.

    Model: Download JSON


  • Quote by ID (Deprecated)

    • URL:https://app.cargofive.com/api/v1/quotes/ID

    Method:GET

    Parámetros

    • ID: ID of the quote to consult.

    Returns: JSON with the details of the requested quote.

  • List of Quotes | version 2(Deprecated)

    • URL:https://app.cargofive.com/api/v2/quotes

    Method:GET

    Parameters

    • Integration: True // If the value is true, the list will only return new and / or recently edited quotes, ignoring those that have already been integrated previously.
    • Type: FCL, LCL o AIR.
    • Status: Win, Draft, Sent.
    • Paginate: Allows you to indicate the number of records to obtain per page. Enter a integer number.

    Returns: JSON with list of quotes. By default, the result is paged at a maximum of 100 records per page.

    Model: Download JSON


  • Quote by ID | versión 2

    • URL:https://app.cargofive.com/api/v2/quotes/ID

    Method:GET

    Parameters

    • ID: ID of the quote to consult.

    Returns: JSON with the details of the requested quote.

  • Companies

    • URL:https://app.cargofive.com/api/v1/companies

    Method:GET

    Returns: JSON array with the detail of each client company associated with the querying user.


  • Create Company

    • URL:https://app.cargofive.com/api/v1/company

    Method:POST

    Parameters

    Parameters marked with * are mandatory

    • business_name* (string): Company name (required).
    • phone (string): Company phone number.
    • address (string): Company address.
    • email (string): Email.
    • tax_number (string): Taxpayer number.
    • options (json): Allows you to save additional values in a json array.
    • pdf_language (enum | 'spanish','english','portuguese'):Language in which the PDF is generated for a quote associated with the company that is being created.
    • payment_conditions (string): Payment terms.

  • See Company Details

    • URL:https://app.cargofive.com/api/v1/company/ID

    Method:GET

    Parameters

    • ID (integer): Id of the company to consult.

    Returns: JSON with the details of the requested company.


  • Update Company

    • URL:https://app.cargofive.com/api/v1/company/ID

    Method:PUT

    Parameters

    • ID (integer): Id of the company to modify.

    Important: When carrying out tests with postman, it may be that when sending the request with PUT, it may not complete the requested action (It is a documented postman incident). If this happens, change the method to POST and add the following to the body form-data: _method: PUT.


  • Delete Company

    • URL:https://app.cargofive.com/api/v1/company/ID

    Method:DELETE

    Parameters

    • ID (integer): Id of the company to delete.
  • Contacts

    • URL:https://app.cargofive.com/api/v1/contacts

    Method:GET

    Returns: JSON array with the detail of each contact belonging to the companies associated with the querying user.


  • Create Contact

    • URL:https://app.cargofive.com/api/v1/contact

    Method:POST

    Parameters

    Parameters marked with * are required

    • first_name* (string): First name (required).
    • last_name* (string): Last name (required).
    • email (string): Email.
    • phone (string): Phone number.
    • position (string): Position in the company.
    • options (json): Allows you to save additional values in a json array.
    • company_id (integer): ID of the company with which the contact will be associated.

  • See Contact

    • URL:https://app.cargofive.com/api/v1/contact/ID

    Method:GET

    Parameters

    • ID (integer): ID of the contact to consult.

    Returns: JSON with the details of the requested contact.


  • Update Contact

    • URL:https://app.cargofive.com/api/v1/contact/ID

    Method:PUT

    Parameters

    • ID (integer): ID of the contact to modify.

    Important: When carrying out tests with postman it may be that when sending the request with PUT, it does not complete the requested action (It is a documented postman incident), if this happens, change the method to POST and add it to the form-data of the body the following: _method: PUT.


  • Delete Contact

    • URL:https://app.cargofive.com/api/v1/contact/ID

    Method:DELETE

    Parameters

    • ID (integer): ID of the contact to delete.
  • Local Charges FCL (Deprecated)

    • URL:https://app.cargofive.com/api/v1/fcl/global/charges

    Method:GET

    Returns: JSON array with the detail of each local FCL charge associated with the querying user.

  • Rates FCL v2 (Deprecated)

    • URL:https://api.cargofive.com/api/rates

    Method:GET

    Parameters (Query)

    • origin: Origin port UN/LOCODE.
    • destination: Destination port UN/LOCODE.
    • startDate: valid from (YYYY-MM-DD).
    • endDate: valid until (YYYY-MM-DD).
    • type: DRY, REEFER, OPENTOP y FLATRACK.
    • includeApiSpot(opcional): Carrier code //all,maersk,cmacgm,evergreen,hapag-lloyd,sealand.

    Retorna: JSON array with rates for the requested rout.

    Ejemplo: Descargar JSON

  • Rates with parameters (Deprecated)

    • URL:https://api.cargofive.com/search/rates/group/ORIGIN/DESTINY/START/END/TYPE

    Method:GET

    Parameters

    • ORIGIN: Origin port using UN / LOCODE
    • DESTINY: Destination port using UN / LOCODE
    • START: Validity start date (YYYY-MM-DD)
    • END: Validity end date (YYYY-MM-DD)
    • TYPE: DRY, REEFER, OPENTOP y FLATRACK.

    Returns: JSON array with rates for the requested route.

    Model: Download JSON

  • Rate with parameters without grouping (Deprecated)

    • URL:https://api.cargofive.com/search/rates/nogroup/ORIGIN/DESTINY/START/END/TYPE

    Method:GET

    Parameters

    • ORIGIN: Origin port using UN / LOCODE
    • DESTINY: Destination port using UN / LOCODE
    • START: Validity start date (YYYY-MM-DD)
    • END: Validity end date (YYYY-MM-DD)
    • TYPE: DRY, REEFER, OPENTOP y FLATRACK.

    Returns: JSON array with rates for the requested route without grouping.

    Model: Download JSON

  • Contracts

    • URL:https://app.cargofive.com/api/v1/_contracts

    Method:GET

    Returns: JSON array with the detail of each contract associated with the querying user.


  • Create contract

    • URL:https://app.cargofive.com/api/v1/upload/contract

    Method:POST

    Parameters

    Parameters marked with * are required

    • type* (string): FCL or LCL
    • reference* (string): Custom reference (required)
    • direction* (string): import, export or both
    • carriers* (integer): IDs associated to the carrier (See carriers list)
    • valid_from* (date): YYYY/MM/DD
    • valid_until* (date): YYYY/MM/DD
    • file* (file): Excel or PDF file with rates

  • Shipping companies

    • URL:https://app.cargofive.com/api/v1/carriers

    Method:GET

    Returns: JSON array with list of shipping companies.

  • Airlines

    • URL:https://app.cargofive.com/api/v1/airlines

    Method:GET

    Returns: JSON array with list of airlines.

  • List of Surcharges

    • URL:https://app.cargofive.com/api/v1/surcharges

    Method:GET

    Returns: JSON array with all surcharges associated with the authenticated user's company.


  • Create Surcharge

    • URL:https://app.cargofive.com/api/v1/surcharge

    Method:POST

    Parameters

    • name (string): Name of the surcharge.
    • description (string): Description of the surcharge.
    • options (json): Allows you to save additional values in a json array.
  • Generate PDF

    • URL:https://api.cargofive.com/pdf

    Method:GET

    Parameters

    • ID (integer): Unique identifier of the quote.

    Returns: Downloadable .pdf file.