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 IsUpdated eq true and StockLocationCode eq 'YOUR WAREHOUSE LOCATION'",
"IsEnabled": true
}You create this by doing an HTTPS POST to https://app.vinsight.net/Webhooks with the json object above.
If you are managing multiple locations, you should update the DiscriminatorFilter to allow each of these locations. For example:
"DiscriminatorFilter": "IsActive eq true AND IsUpdated eq true 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
IsUpdated: true is how we denote that an Order’s Despatch Note is ready for your warehouse to pick up. This is set when a user marks their Despatch as “Complete” in Vinsight, and we have already depleted the Units In Stock of their Stock Items, based on the transaction.
When receiving a webhook, you will need to double check IsActive, IsUpdated 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 us 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 .
{
"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
}
]
}