Description

The Visiwise Import API is a robust RESTful interface designed to streamline the process of importing multiple shipments into the Visiwise platform. This API facilitates the seamless integration of data from various file formats, including XLS, XLSX, and CSV, providing users with a versatile and user-friendly solution for managing their shipments.

How to use this API?

To get API access send an email to [email protected]

URL:

https://www.visiwise.co/api/v1/shipments/import

Request method:
POST

Request headers:

{
    "Authorization": "token <your_visiwise_api_token>",
    "Content-Type": "multipart/form-data"
}

Request body:

{
    "file": "<your xls,xlsx or csv file>"
}

Maximum file size is 20 MB

What’s next?

When you call the API if your call is successful then an ImportShipmentHistory will be created for you that you can use to track status of you imported file.

Resposnse example

Status Code Response Body Description
200 OK { "success": true, "link": "<dashboard_link_to_imported_file>" } Successful request. Returns a link to the dashboard for the imported file.
401 Unauthorized { "detail": "Authentication credentials were not provided." } Failed request due to missing or incorrect authorization token.
403 Forbidden { "detail": "You do not have permission to perform this action." } Failed request because import API access is not enabled for the user.
400 Bad Request { "detail": "Invalid fileType. Only xlsx, xls and csv files are valid" } Failed request due to an invalid file type.
400 Bad Request { "detail": "This file needs at least 2 rows to be imported." } Failed request because the uploaded file is empty or has less than 2 rows.
400 Bad Request { "detail": "The imported file contains <number_of_rows> shipments, but only 300 rows can be imported in each call. To continue the process, please remove extra items." } Failed request because the file exceeds the maximum allowed number of rows (300).
400 Bad Request { "detail":"Only <your_remaining_credit> containers remain to be tracked, but the uploaded file contains more. To continue, remove extra items or upgrade for more tracking and features." } Failed request because the new shipments count exceeds the total available credit.

File structure

Lets assume that we have created these custom fields for your account:

  1. "Customer"
  2. "PO Number"
  3. "Expected Delivery Date"
  4. "Product"

The following is a list of columns that your file can have:

Header(Case sensetive) Is required Example Description
Reference Yes DFSU7162007 Your tracking number(Bill of lading,Booking or container number)
ReferenceType Yes ContainerTracking What type is your tracking number? choices are listed below
ShippingLine Yes MSC Name of the shipping line, choices listed below
Name No Coconut n Apple Your desired name for this shipment, if shipment already exists, it’s name will be updated
SharedWith No [email protected], [email protected] List of comma separated emails to share this shipment with
Tags No Goods, Import, … List of comma separated strings to use as tag for each shipment
ShipmentReference No fruits-2034 A unique reference for this shipment.
Assignees No [email protected] A list of comma separated emails to assign them to this shipment. Each email should be a member of workspace otherwise it will be ignored
Shipment.Customer No – Header is case sensitive
Shipment.PO Number No – Header is case sensitive
Shipment.Expected Delivery Date No – Header is case sensitive
Shipment.Product No – Header is case sensitive

ReferenceType options

Tracking Type Valid ReferenceType Options
Container Tracking cn, containertracking, container tracking, container-tracking, container
Bill of Lading Tracking bl, bltracking, bl tracking, bl-tracking, bill-of-lading, bill of lading, mbl
Booking Tracking bk, booking tracking, booking-tracking, bookingtracking

ShippingLine options

  • AUTO (Only available for container tracking type)
  • MSC
  • Wan Hai
  • Yang Ming
  • ZIM
  • Gold Star
  • ACL
  • ANL
  • APL
  • CMA CGM
  • CNC
  • COSCO
  • CULines
  • Evergreen
  • Grimaldi
  • Hamburg Sud
  • Hapag-Lloyd
  • HMM
  • KMTC
  • Matson
  • Messina
  • One
  • OOCL
  • PIL
  • Safmarine
  • Sealand
  • Seth Shipping
  • SM Line
  • WEC Lines
  • Namsung
  • SCI
  • Turkon
  • Maersk

Import history page error/warning descriptions

Message Type Message Related Field Description
Warning Custom field ‘FieldName’ (Shipment) is not created for user Shipment.Customer, Shipment.PO Number, Shipment.Expected Delivery Date, Shipment.Product If you encounter this error it means that <FieldName> is not created for your workspace. Please contact support so we’ll take care of this
Warning <email> is not a valid email address SharedWith, Assignees One or more of the emails you provided is not a valid email e.g: [email protected], sample2.com. sample2.com is invalid
Warning email:’‘ is registered as NON Viewer SharedWith The email you provided is registered on site as a non viewer account.(Viewer accounts are limited)
Warning Email ‘‘ already has access to this shipment SharedWith The email address you provided already has access to target shipment
Error Reference can not be empty Reference –
Error Invalid shipment reference, Use only letters, numbers, hyphen (-), or underscore (_) characters ShipmentReference
Error The shipment reference (<value>) already exists. Please provide a unique reference ShipmentReference ShipmentReference must be unique, you can have only one shipment with each shipment reference
Error Duplicate Refernce: <tracking_number> Reference, ShipmentReference The combination of reference and ShipmentReference you provided is not unique. e.g: you provided DFSU7162007 with No ShipmentReference twice or with same ShipmentReference twice
Error Shipping Line can not be empty ShippingLine –
Error Invalid line name ShippingLine Provided value is not one of the choices mentioned above
Error ReferenceType can not be empty ReferenceType –
Error {value} is not a valid reference type ReferenceType Provided value is not one of the choices mentioned above

Creation Status

When you visit visiwise dashboard to check your import history page, there’s a column called Creation Status, it’s values are:

  • Created: New shipment was created for this row since we could not find a shipment with same tracking number,shipping line and Shipment reference.
  • Updated: An old shipment which was not closed and had the same shipping line, tracking number and shipment reference was found and now it’s data has been updated with the information you provided.
  • Failed: Creation of shipment because there was an error in the information you provided

Tracking Status

  • Track-Queued: your shipment was either created or updated and now awaits in tracking queue for new tracking update
  • Is-Tracking: your shipment is currently in tracking(we’re fetching data of your shipment)
  • Track-Succeeded: tracking your shipment was successful
  • Track-Failed: tracking of your shipment has encountered an exception either we could not fetch data for it or the shipping line did not provide tracking info for this shipment at the current time

Notes

  1. This API is continuously evolving, and updates are expected. For the most current information, please revisit this page periodically. (Last Updated: 2023/11/16)
  2. If a shipment is created but it’s tracking is not successful then you won’t see it in your dashboard
  3. If a shipment is created before but it’s tracking was not successful then when you import it again it will be updated
  4. To unset value of a column for example Name column of a shipment you can set the value in your file as <empty> to clear the value
  5. Tracking number X with Shipment reference Y is unique so if you enter X, Y1 and another row X, Y2 or X, ” these are all valid choices and 3 shipments will be created. But if you enter X, Y2 twice or tracking number N with Y1 then since the shipment reference must be unique you encounter an error.
  6. You can go to shipment page using the ShipmentReference you have entered. e.g: you have entered CARGO1 as shipment reference you can go it’s dashboard page on Visiwise using the pattern below:
    • https://www.visiwise.co/r/shipment/reference=CARGO1 it will redirect you to the related shipment page of this shipment reference