Example Sales Integration

If you want to create Sales Orders in Vinsight, here is an example of the data you will want to POST to our API.

It is more data that strictly necessary to create an Order but also includes data to make a better user experience eg see the order url from the system the order originated in.

Here is a fairly minimum POST:

POST https://app.vinsight.net/SalesOrders

 {
        "ContactNum": 41,
        "InvoiceDate": "2022-08-25T00:00:00+14:00",
        "OrderReference": "Your preferred Square Invoice Ref",
        "Categories": "source:Square;channel:POS;",
        "DateRequired": "",
        "DeliveryName": "Bobby Brown",
        "DeliveryAddress": "",
        "DeliverySuburb": "",
        "DeliveryCity": "",
        "DeliveryRegion": "NSW",
        "DeliveryPostCode": "",
        "DeliveryCountry": "Australia",
        "DeliveryEmail": "",
        "DeliveryPhone": "",
        "DeliveryInstructions": "",
        "CurrencyNum": 1,
        "PaymentTermDescription": "",
        "DatePaymentDue": "",
        "DatePaid": "",
        "Comments": "",
        "CurrencyRate": 1,
        "DivisionNum": 1,
        "Items": [{
                "Description": null,
                "Quantity": 1,
                "UnitOfMeasureCode": "12x750ml",
                "UnitPrice": 192,
                "Discount": 0,
                "SalesTaxRateValue": 0.10,
                "SalesTaxRateNum": 1,
                "PriceDescription": null,
                "CurrencyNum": 1,
                "StockItemNum": 1,
                "Sort": 0
            }
        ],
        "Aliases": [{
                //Vinsight Type
                "EntityType": "SalesOrder",
                "Domain": "Square",
                //Square Merchant Id
                "SubDomain": "2RNAQEEXAMPLE",
                //Square Type
                "DomainEntityType": "Order",
                //Square Order Id
                "DomainEntityId": "807269269574",
                //Square Order Display Num or orderreference if any
                "DomainEntityCode": "#1003",
                //url to Square order
                "DomainEntityUrl": "https://my-store.myshopify.com/admin/orders/123456789",
                //Sqaure datemodified or similar
                "DomainData": "{\"UpdatedAt\":\"2022-01-13T22:20:06-05:00\"}"
            }
        ]
    }

NB: Remember to remove the comment lines from the above example as json does not allow comments.

You will need to pre-lookup and cache on your server (or create the references for) the following data:

• ContactNum:  eg GET /Contacts.json?$filter=ContactCode eq ‘Bob Brown’ OR Email eq ‘abc@example.com’&$select=ContactNum,ContactCode,FirstName,LastName,Email
• CurrencyNum: eg  GET /Currencies.json?$filter=CurrencyCode eq ‘AUD’&$select=EntryNum,CurrencyCode
• DivisionNum: GET /Divisions.json?$filter=DivisionCode eq ‘Wine’&$select=EntryNum,DivisionCode
• SalesTaxRateNum: GET /TaxRates.json.json?$filter=TaxType/TaxArea/Code eq ‘Sales’&$select=EntryNum,Code,Amount
  //This should get all the sales taxes which might be GST or VAT etc depending on your tax settings.
  //You should use both the correct SalesTaxRateNum and use the tax amount (ie the tax percentage) in the SalesTaxRateValue
  //So a GST that returns the Amount as 0.1 (being 10%) you should also put the 0.1 into the SalesTaxRateValue property.//Get many items matching either their code or alias codes from other systems by making an array of strings to match and search both the Contact Code and any “Aliases” that are configured for those codes
• StockItemNum: /StockItems.json?$filter=contains(new[’15ABC-PinotGris-1.5L’,’15CHEFGH’],StockItemCode) or Aliases/Any(EntityType eq ‘SalesOrder’ and contains(new[’15ABC-PinotGris-1.5L’,’15CHEFGH’],DomainEntityCode))&$select=$select=StockItemNum,StockItemCode,UnitsInStockUOM as InventoryUOM,BaseUOM as BottleUOM,InnerUOM,OuterUOM as CaseUOM,UnitsOfMeasure/Select(new(UnitOfMeasureCode,ConversionRate)) as UnitsOfMeasure
  //You need to make sure that you  use the correct UnitOfMeasureCode (UOM) in the order, where you can select between the BaseUOM,InnerUOM and OuterUOM depending on your needs. ie BaseUOM should be the single bottle UOM and the OuterUOM should be the case UOM.

You can test both POST and GETs in our API page:  https://app.vinsight.net/ApiRequests?view-mode=create
eg:

JSON Example – Creating a Sales Order via API using Unmatched Items workflow
If you don’t want to look up existing id values for Contacts or Stock Items, it is also possible to create a Sales Order using the Unmatched Items workflow.
This is useful if you don’t know the exact codes to search for, or they are slightly different between the two systems.

{
        "ContactNum": 0, // We are using the "Not Matched" placeholder ID here
        "InvoiceDate": "2022-08-25T00:00:00+14:00",
        "OrderReference": "Your preferred Square Invoice Ref",
        "Categories": "source:Square;channel:POS;",
        "DateRequired": "",
        "DeliveryName": "Bobby Brown",
        "DeliveryAddress": "",
        "DeliverySuburb": "",
        "DeliveryCity": "",
        "DeliveryRegion": "NSW",
        "DeliveryPostCode": "",
        "DeliveryCountry": "Australia",
        "DeliveryEmail": "",
        "DeliveryPhone": "",
        "DeliveryInstructions": "",
        "CurrencyNum": 1,
        "PaymentTermDescription": "",
        "DatePaymentDue": "",
        "DatePaid": "",
        "Comments": "",
        "CurrencyRate": 1,
        "DivisionNum": 1,
        "Items": [{
                "Description": null,
                "Quantity": 1,
                "UnitOfMeasureCode": "12x750ml",
                "UnitPrice": 192,
                "Discount": 0,
                "SalesTaxRateValue": 0.10,
                "SalesTaxRateNum": 1,
                "PriceDescription": null,
                "CurrencyNum": 1,
                "Sort": 0,
                // We are using the "Not Matched" placeholder ID here
                "StockItemNum": 0,
                "Aliases": [{
                // This Alias is telling us about the StockItemNum property. 
                // The Stock Item is intended to represent the product in Square
                    "EntityUniqifier": "StockItemNum", 
                    "Domain": "Square",
                    "SubDomain": "2RNAQEEXAMPLE",
                    "DomainEntityType": "Product",
                    "DomainEntityId": "1624799388",
                    "DomainEntityCode": "MY SAUVIGNON BLANC 750ML",
                // Some form of minimal DomainData is required for Product Matching
                    "DomainData": "{\"ProductSKU\":\"#12345\"}"
                }]
            }
        ],
        "Aliases": [
             {
// This Alias is telling us where the document came from, not required for the Matching process
                "EntityType": "SalesOrder",
                "Domain": "Square",
                "SubDomain": "2RNAQEEXAMPLE",
                "DomainEntityType": "Order",
                "DomainEntityId": "807269269574",
                "DomainEntityCode": "#1003",
                "DomainEntityUrl": "https://my-store.myshopify.com/admin/orders/123456789",
                "DomainData": "{\"UpdatedAt\":\"2022-01-13T22:20:06-05:00\"}"
            },
            { 
// This Alias is telling us about the ContactNum property. 
// The Contact is intended to represent the customer in Square
                "EntityUniqifier": "ContactNum", 
                "Domain": "Sqaure", 
                "SubDomain": "2RNAQEEXAMPLE", 
                "DomainEntityType": "Customer", 
                "DomainEntityId": "9811884231", 
                "DomainEntityDescription": "Bobby Brown" 
            }
        ]
    }