Home » Vinsight API  »  Example Sales Integration
Table of Contents

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: