Cargofive Última actualización: 28-05-2021

Cargofive es una plataforma que permite buscar, comparar y gestionar las tarifas de fletes marítimos entre distintas navieras en tiempo record, logrando obtener cotizaciones en solo unos pocos minutos.

APIs

API Rest

API es un conjunto de reglas y especificaciones que las aplicaciones pueden seguir para comunicarse entre ellas. Para que lo entendamos, el uso de una API es el mecanismo más útil para conectar dos softwares entre sí, de esta manera, podemos garantizar el intercambio de mensajes o datos en formato estándar.

  • Operaciones disponibles

    • Las operaciones disponibles en el entorno de la API son POST (crear), GET (leer y consultar), PUT (editar) y DELETE (borrar).

Primeros pasos API Cargofive

  • Obtener API Key

    • Para poder acceder al API de Cargofive necesitará contar con un usuario registrado y activo en nuestra plataforma. Cumplido esto, deberá solicitar las credenciales adicionales que le permitiran obtener un token de acceso. Desde Cargofive se le proveerán todos los datos necesarios para completar este proceso.

  • Realizar pruebas con Potsman

    • Antes de llevar a cabo una integración completa probablemente querrá realizar algunas pruebas. Para tal fin puede utilizar la aplicación Postman, a continuación se hará una breve explicación de cómo instalarla y utilizarla correctamente.

  • Instalación Postman

    • Para instalar Postman deberá acceder al sitio https://www.postman.com/downloads y proceder a descargar el instalador compatible con su sistema operativo.

  • Pruebas esenciales

    • Luego de instalado Postman podrá comenzar a realizar las pruebas necesarias. En esta sección utilizaremos algunos endpoints del API Cargofive que posteriormente se explicarán en detalle.

    • Headers

      • Antes de realizar una petición debe configurar los headers correspondientes:

      Content-Type: application/json

      X-Requested-With: XMLHttpRequest

    • Obtener Bearer Token

      • Para realizar una operación sobre el API Cargofive deberá contar con Bearer Token válido, lo cual acredita que se encuentra correctamente autenticado.

      Para obtener el Bearer Token deberá hacer una llamada POST al endpoint https://app.cargofive.com/oauth/token junto con los siguientes parámetros que debe configurar en la pestaña Body seleccionando form-data:

      • client_id: El client id proporcionado por Cargofive.
      • client_secret: El client secret proporcionado por Cargofive.
      • grant_type: Acá deberá colocar “password”.
      • username: El email con el cual se encuentra registrado en Cargofive.
      • password: El password que utiliza para el ingreso a Cargofive.

      Al completar la petición se le entregará el “access_token” con el cual podrá acceder a los diferentes endpoints del API Cargofive. Para ello deberá copiar el valor que se encuentra entre las comillas (“) y pegarlo en el valor Bearer Token ubicado en la pestaña autorización para todas las peticiones que vaya a realizar hacia el API Cargofive.

    • Petición de prueba

      • Al contar con un bearer token (access_token) válido podrá realizar las diferentes operaciones que sean permitidas por el API. Para llevar a cabo esto primeramente deberá configurar el bearer token obtenido en el proceso previo. Antes de realizar cualquier petición diríjase a la pestaña Authorization y en el desplegable Type seleccione la opción Bearer Token y finalmente en el campo token pegue el valor del bearer token (access_token).

      Configurado el bearer token, estará listo para poder realizar una petición válida al API. En esta oportunidad se ejemplificará una petición GET para consultar rates al siguiente endpoint:

      https://api.cargofive.com/search/rates/group/ORIGEN/DESTINO/INICIO/FIN/TIPO

      Método: GET

      Los parámetros que deben utilizarse en el endpoint son:

      • ORIGEN: Puerto de Origen usando UN/LOCODE
      • DESTINO: Puerto de Destino usando UN/LOCODE
      • INICIO: Fecha de inicio de validez (YYYY-MM-DD)
      • FIN: Fecha de finalización de validez (YYYY-MM-DD)
      • TIPO: DRY, REEFER, OPENTOP y FLATRACK.

      El resultado de esta operación será un json con la información correspondiente a las tarifas que cumplan con el criterio de los parámetros enviados.

Endpoints disponibles

Para acceder a cada endpoint deberá contar con un bearer token válido. Todas las peticiones tienen disponible los siguientes parámetros opcionales:

  • size (integer): Limita la cantidad de registros que devuelve una petición.
  • paginate (integer): Pagina los resultados de acuerdo al valor indicado.

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

Tenga en cuenta que hay algunos endpoints que apuntan a la URL: https://api.cargofive.com/

  • Obtener token

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

    Método:POST

    Parámetros

    • grant_type: Tipo de acceso que requiere el generador de token, su valor es “password”.
    • username: email de acceso a Cargofive.
    • password: contraseña de acceso a Cargofive.
    • scope: su valor por defecto será *.
    • client_id: Valor numero brindado en la generación de tokens.
    • client_secret: Hash oauth brindado en la generación de tokens.

    Retorna: JSON con Bearer token (access_token).

  • Usuario

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

    Método:GET

    Retorna: JSON con el detalle del usuario autenticado.

  • Lista de cotizaciones (Obsoleto)

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

    Método:GET

    Parámetros

    • Integration: True //Si el valor es true, el listado solo devolverá cotizaciones nuevas y/o editadas recientementes, obviando aquellas que ya han sido integradas con anterioridad.
    • Type: FCL, LCL o AIR.
    • Status: Win, Draft, Sent, Negotiated, Lost.
    • Size: Limita la cantidad de registros que retorna la consulta. Indicar un número entero.

    Retorna: Arreglo JSON con el detalle de cada cotización asociada al usuario que consulta.

    Modelo: Descargar JSON


  • Cotización por ID (Obsoleto)

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

    Método:GET

    Parámetros

    • ID: ID de la cotización a consultar.

    Retorna: JSON con el detalle de la cotización solicitada.

  • Lista de cotizaciones | versión 2 (Obsoleto)

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

    Método:GET

    Parámetros

    • Integration: True //Si el valor es true, el listado solo devolverá cotizaciones nuevas y/o editadas recientementes, obviando aquellas que ya han sido integradas con anterioridad.
    • Type: FCL o LCL
    • Status: Win, Draft, Sent, Negotiated, Lost.
    • Paginate: Permite indicar la cantidad de registros a obtener por página. Indicar un número entero.

    Retorna: Arreglo JSON con listado de cotizaciones. Por defecto, el resultado está paginado a un máximo de 100 registros por página.

    Ejemplo: Descargar JSON

    Modelo: Descargar archivo


  • Cotización por ID | versión 2

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

    Método:GET

    Parámetros

    • ID: ID de la cotización a consultar.

    Retorna: JSON con el detalle de la cotización solicitada.

  • Compañías

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

    Método:GET

    Retorna: Arreglo JSON con el detalle de cada compañía cliente asociada al usuario que consulta.

    Ejemplo: Descargar JSON

    Modelo: Descargar archivo


  • Crear compañía

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

    Método:POST

    Parámetros

    Parámetros marcados con * son obligatorios

    • business_name* (string): Nombre de la compañía (único obligatorio).
    • phone (string): Teléfono de la compañía.
    • address (string): Dirección de la compañía.
    • email (string): Dirección de correo electrónico.
    • tax_number (string): Número de contribuyente.
    • options (json): Permite guardar valores adicionales en un arreglo json.
    • pdf_language (enum | 'spanish','english','portuguese'): Lenguaje en el cual se genera el PDF para una cotización asociada a la compañía que se está creando.
    • payment_conditions (string): Condiciones de pago.

  • Ver Compañía

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

    Método:GET

    Parámetros

    • ID (integer): Id de la compañía a consultar.

    Retorna: JSON con el detalle de la compañía solicitada.

    Ejemplo: Descargar JSON

    Modelo: Descargar archivo


  • Actualizar Compañía

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

    Método:PUT

    Parámetros

    • ID (integer): Id de la compañía a modificar.

    Importante: Al realizar con pruebas con postman puede que al enviar la petición con PUT este no complete la acción solicitada (Es una incidencia de postman documentada). De ocurrir esto, cambie el método a POST y agregue dentro del form-data del body lo siguiente: _method: PUT.


  • Eliminar Compañía

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

    Método:DELETE

    Parámetros

    • ID (integer): Id de la compañía a eliminar.
  • Contactos

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

    Método:GET

    Retorna: Arreglo JSON con el detalle de cada contacto perteneciente a las compañías asociadas al usuario que consulta.


  • Crear contacto

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

    Método:POST

    Parámetros

    Parámetros marcados con * son obligatorios

    • first_name* (string): Nombre de la compañía (único obligatorio).
    • last_name* (string): Teléfono de la compañía.
    • email (string): Dirección de correo electrónico.
    • phone (string): Número de teléfono.
    • position (string): Cargo que ocupa.
    • options (json): Permite guardar valores adicionales en un arreglo json.
    • company_id (integer): ID de la compañía a la que será asociado el contacto.

  • Ver Contacto

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

    Método:GET

    Parámetros

    • ID (integer): Id del contacto a consultar.

    Retorna: JSON con el detalle del contacto solicitado.


  • Actualizar Contacto

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

    Método:PUT

    Parámetros

    • ID (integer): Id del contacto a modificar.

    Importante: Al realizar con pruebas con postman puede que al enviar la petición con PUT, este no complete la acción solicitada (Es una incidencia de postman documentada), de ocurrir esto, cambie el método a POST y agregue dentro del form-data del body lo siguiente: _method: PUT.


  • Eliminar Contacto

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

    Método:DELETE

    Parámetros

    • ID (integer): Id del contacto a eliminar.
  • Gastos locales FCL (Obsoleto)

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

    Método:GET

    Retorna: Arreglo JSON con el detalle de cada cargo local FCL asociado al usuario que consulta.

    Ejemplo: Descargar JSON

    Modelo: Descargar archivo

  • Tarifas FCL con parámetros (Obsoleto)

    • URL:https://app.cargofive.com/api/v1/rates/group/ORIGEN/DESTINO/INICIO/FIN/TIPO

    Método:GET

    Parámetros

    • ORIGEN: Puerto de origen usando UN/LOCODE.
    • DESTINO: Puerto de destino usando UN/LOCODE.
    • INICIO: Fecha de validez inicial (YYYY-MM-DD).
    • FIN: Fecha de validez final (YYYY-MM-DD).
    • TIPO: DRY, REEFER, OPENTOP y FLATRACK.
    • OPCIONAL: Puede indicar el flujo a consultar mediante un parámetro de tipo query llamado "traffic" y las opciones que admite son "import" o "export".

    Retorna: Arreglo JSON con las tarifas para la ruta solicitada.

    Ejemplo: Descargar JSON

    Modelo: Descargar JSON

  • Tarifas FCL (Obsoleto)

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

    Método:GET

    Parámetros (Query)

    • origin: Puerto de origen usando UN/LOCODE.
    • destination: Puerto de destino usando UN/LOCODE.
    • startDate: Fecha de validez inicial (YYYY-MM-DD).
    • endDate: Fecha de validez final (YYYY-MM-DD).
    • type: DRY, REEFER, OPENTOP y FLATRACK.
    • includeApiSpot(opcional): Código de la naviera //all,maersk,cmacgm,evergreen,hapag-lloyd,sealand.

    Retorna: Arreglo JSON con las tarifas para la ruta solicitada.

    Ejemplo: Descargar JSON

  • Tarifas FCL con parámetros sin agrupar (Obsoleto)

    • URL:https://app.cargofive.com/api/v1/rates/nogroup/ORIGEN/DESTINO/INICIO/FIN/TIPO

    Método:GET

    Parámetros

    • ORIGEN: Puerto de origen usando UN/LOCODE.
    • DESTINO: Puerto de destino usando UN/LOCODE.
    • INICIO: Fecha de validez inicial (YYYY-MM-DD).
    • FIN: Fecha de validez final (YYYY-MM-DD).
    • TIPO: DRY, REEFER, OPENTOP y FLATRACK.
    • OPCIONAL: Puede indicar el flujo a consultar mediante un parámetro de tipo query llamado "traffic" y las opciones que admite son "import" o "export".

    Retorna: Arreglo JSON con las tarifas para la ruta solicitada sin agrupar.

    Ejemplo: Descargar JSON

    Modelo: Descargar JSON

  • Contratos

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

    Método:GET

    Retorna: Arreglo JSON con el detalle de cada contrato asociado al usuario que consulta.


  • Crear contrato

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

    Método:POST

    Parámetros

    Parámetros marcados con * son obligatorios

    • type* (string): FCL o LCL
    • reference* (string): Identificador/Referencia personalizada
    • direction* (string): import, export o both
    • carriers* (integer): Identificadores de navieras (Ver listado de navieras de Cargofive)
    • valid_from* (date): YYYY/MM/DD
    • valid_until* (date): YYYY/MM/DD
    • file* (file): Archivo excel o PDF con tarifas

  • Navieras

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

    Método:GET

    Retorna: Arreglo JSON con todos las navieras.

  • Aerolíneas

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

    Método:GET

    Retorna: Arreglo JSON con todos las aerolíneas.

  • Lista de Surcharges

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

    Método:GET

    Retorna: Arreglo JSON con todos los surcharges asociados a la compañía del usuario autenticado.

    Ejemplo: Descargar JSON

    Modelo: Descargar archivo


  • Crear Surcharge

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

    Método:POST

    Parámetros

    • name (string): Nombre del surcharge.
    • description (string): Descripción del surcharge.
    • options (json): Permite guardar valores adicionales en un arreglo json.
  • Generar PDF

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

    Método:GET

    Parámetros

    • ID (integer): Identificador único de la cotización.

    Retorna: Archivo .pdf descargable.