Home » Example Logistics Warehouse Integration

Example Logistics Warehouse Integration

If you are a warehouse operator and would like to build an integration with Vinsight, here is some documentation that you will find useful on how best to use our API to acheive this. Leading to a smooth experience for the user when using Vinsight to communicate shipments to your system.

Expected Integration Process

You will need to create an OAuth Application in Vinsight to allow customers to connect your system to Vinsight using a standard OAuth Autentication Procedure. This process is outlined here:

Setting up Webhooks

Once you have a connection to a Vinsight Account, your application should create a Webhook in the Vinsight Account to listen to the following event:

{
    "EntityType": "SalesOrderDespatch",
    "EventType": "modified",
    "Url": "YOUR PUBLIC URL",
    "ContentType": "json",
    "DiscriminatorFilter": "IsActive eq true AND LocationStatus eq 'Pending' and StockLocationCode eq 'YOUR WAREHOUSE LOCATION'",
    "IsEnabled": true
}

If you are managing multiple locations, you should update the DiscriminatorFilter to allow each of these locations. For example:

"DiscriminatorFilter": "IsActive eq true AND LocationStatus eq 'Pending' and contains(new['WAREHOUSE1', 'WAREHOUSE2'], StockLocationCode)"

Each Vinsight Account has their own set of webhooks, and their own set of Stock Locations. You will need to collect the Stock Locations that are relevant to you.

Make sure you read the headers X-Vinsight-Organisation-Id and X-Vinsight-Connection-Name to figure out which company the webhook is for. Organisations can have multiple connections so make sure that you are not processing despatches from the organisation’s “Demo Co” connection for example. Alternatively you can use a unique Webhook URL per company.

Receiving and Processing Webhooks

LocationStatus: Pending is how we denote that an Order’s Despatch Note is ready for your warehouse to pick up.

When receiving a webhook, you will need to double check IsActive, LocationStatus and StockLocationCode to make sure they match your expected values. Don’t rely solely on the DiscriminiatorFilter to do this for you.

Ideally you would do an additional API request to get the definitive current state of the Despatch Note from our system as well, just in case we send an outdated webhook.

You will also need to make sure you only action a given Despatch once, as you will get multiple webhooks for a single Despatch (Any time a Despatch is modified and it matches the supplied filter).

The body of the webhook will be the JSON representation of the Despatch Note, this includes the Stock Location Code, Despatch Date, Address information and products to be despatched.

Not all entries will correspond to physical products. Items such as Fees and Shipping costs are likely to appear. If you see Entries with negative Quantities, ignore them.

Pay close attention to the StockItemCode (or StockItemNum), Quantity and UnitOfMeasureCode.

Each item can support multiple Units Of Measure so you will need to be careful about handling different case sizes and bottle units.

The UOM codes are unique to each company. You can do an API request to /UnitsOfMeasure to figure out the ML volume of each UOM for the company.

The UOM list should be retrieved and cached on your side for easy lookup.

Notifying Vinsight once shipment has been received

When you have finished importing the Despatch in to your system, you should send an update back to Vinsight, updating the Despatch properties LocationStatus to be “Notified“, and LocationNotified to be the datetime that you were notified e.g. “2022-09-22T17:43:27+12:00”.

This will move the order in Vinsight from the “3PL Shipment Pending” tab to the “3PL Shipment Complete” tab.

As part of the PUT request to the Despatch that you are updating us about, you should also include an Alias record. These tell us what the ID of the shipment is in your system and is attached to the Despatch in Vinsight.

We show this ID in the Vinsight UI, so users can see in Vinsight that you have successfully retrieved a given despatch.

PUT the following JSON data to the /SalesOrderDespatches/<DespatchNum> URL, ignoring comments and replacing the values in bold. <DespatchNum> in the URL to PUT to is the Vinsight DespatchNum you are updating e.g. /SalesOrderDespatches/111111 .

{
    "LocationStatus": "Notified",
    "LocationNotified": "2022-09-22T17:43:27+12:00",
    "Aliases": [
        {
            "$state": "inserted",
            "EntityType": "SalesOrderDespatch",
            "EntityNum": 111111, // DespatchNum from Vinsight
            "Domain": "YourWarehouseName", 
            "SubDomain": "Your client's CompanyCode In your system e.g. ABC Wine Estate",
            "SubDomainDescription": "Export",
            "DomainEntityType": "Order", //Your movement type eg "Outbound Order", "Shipment" etc
            "DomainEntityId": "ShipmentId in your warehouse",
            "DomainEntityCode": "ShipmentCode in your warehouse",
            "DomainEntityUrl": "https://yourwebsite/shipments/ShipmentId" //Optional but very useful link to this shipment in your system
        }
    ]
}