MENU

Integrate Software Into SQUIZZ.com Platform

Within the SQUIZZ.com platform there is the ability to connect and integrate software running external to the platform. Such software can be used to help organisations effectively use the platform, and allow them to trade, communicate, and collaborate with its people, customers or suppliers. The platform contains an Application Programming Interface (API) that allows software developers and providers to have their software and systems push data into the platform, or receive data from the platform. Collectively this allows for universal Electronic Data Interchange known as EDI, where businesses can connect their software to other businesses without having to know or understand the software that each other business uses.

Topics

  1. Prerequisites
  2. Overview
  3. Importing Organisation Data Directly Into The Platform Using The API
  4. Importing Organisation Data Indirectly Using The SQUIZZ.com Connector
  5. Setting Up Access To Use The Platform's API
  6. Retrieving Organisational Data From The Platform
  7. Receiving Organisational Data From The Platform
  8. Receiving Realtime Organisational Data Requests From The Platform
  9. Sending Notifications to SQUIZZ.com

Prerequisites

Before reading on please ensure that you have understood the following topics:

Overview

The SQUIZZ platform allows software developers and software providers to integrate their software into the platform. There are several options on how software can be integrated into the platform, either by software directly talking to the platform's RESTful API, or indirectly through using the SQUIZZ.com Connector software. Additionally external software can receive requests and data from the SQUIZZ.com platform if the software supports running as a web service and conforms to the platform's HTTPS request structures. In both cases the platform only supports organisation data being imported and exported from the API using secure HTTPS transport layer requests, through the use of Transport Layer Security (TLS) certificates to encrypt data. This ensures that an organisation's data is securely transferred across the public internet without any 3rd parties eavesdropping in on the data.

SQUIZZ.com Platform Organisation API Diagram

Importing Organisation Data Directly Into The Platform Using The API

The SQUIZZ.com Platform has an API that allows software external to the platform to push in different kinds of data for each organisation. The API only accepts HTTPS requests to receive data using GET or POST requests. The API is broken up into a number of "endpoints" with each performing a different function.

Creating An Organisation API Session

Before any of the platform's endpoints can be called by software, a session must first be created in the API through using its Create Organisation API Session endpoint. This endpoint authenticates that the software is allowed to use the API, based on the software providing credentials that have been set up for an organisation in the platform. Each organisation has its own credentials that can be changed at any time by people who are administrators of the organisation.

Validating An Organisation API Session

Once a session has been successfully created in the API then all other endpoints can be repeatedly called without having to authenticate again. This can be achieved by providing the session ID in all the other API endpoint calls. Note that sessions only last for a limited amount of time, so over periods of time your software may need to verify that the session still exists by calling the Validate Organisation API Session endpoint.

Endpoint For Importing Organisation Data

The main endpoint in the API for importing organisation data is the Import Ecommerce Standards Document (ESD) endpoint. This endpoint can be used to import a number of different kinds of data, including an organisation's products, pricing, customer accounts, supplier accounts, taxcodes, plus many more. You can learn about the kinds of organisation data that can be imported by reading the Organisational Data document. The endpoint receives the data HTTPS POST request, with the data formatted into JSON and placed within the body of the request. The JSON is structured in the Ecommerce Standards Document (ESD) open standards format. When the organisation data is imported the platform will check if existing records have been previously imported, if not then the records will be created within the platform, if the records do exist then the platform will update selected fields of each record. Additionally the imports can deactivate or delete data no longer required to be stored on the platform. Most kinds data will be deactived ensuring that important data is not accidentally lost. Some types of data may be permanently removed.

Endpoint For Procuring And Send Purchase Orders To Supplier

Within the API there is the ability for purchase orders to imported into the platform and be "procured" by a designated supplier organisation. This allows purchase orders of a customer organisation to be converted into sales orders of the supplier organisation, based on the platform being able to match the products in the platform to a supplier organisation's products. Using this endpoint it can be used to automate the process of a customer organisation buying goods and services of an existing supplier.  The endpoint requires that both the customer and supplier organisations are registered within the platform, both are connected together, and the supplier organisation has assigned a customer account to the customer organisation. To find out more about this endpoint look at the API documentation for it.

Importing Organisation Data Indirectly Using The SQUIZZ.com Connector

SQUIZZ.com has developed the SQUIZZ.com Connector, and is a free piece of software that can run on Microsoft Windows operating systems that also have the Microsoft .NET framework installed. The Connector has broken up into 2 separate applications. The Connector Host Service is installed as a Windows service, and can always run in the background. The Connector Application is a client application that can be run by Windows users who have installed the app. The Connector application allows users to configure how the Connector service works, see any messages, logs and data as data is being sent to or from the SQUIZZ.com platform.

SQUIZZ.com Platform Organisation API and Connector diagram

Supported Data Sources

The SQUIZZ.com Connector can be configured to read data from a number of popular business systems, or it can be configured to read data from a wide variety of data sources, including:

  • ODBC databases (MySQL, PostgreSQL, Microsoft Access)
  • CSV Spreadsheets
  • XLSX Spreadsheets (through Excel ODBC driver)
  • Microsoft SQL Server Databases
  • JSON Based Web Services
  • JSON Files
  • XML Based Web Services
  • XML Files
  • ESD Compatible Web Services
  • SQLite Databases

The Connector software can be used to read data from any of its configured data sources, and push the organisation data up to the SQUIZZ.com platform. The Connector also has a scheduler that allows data to be read repeatedly and uploaded to the SQUIZZ.com platform on a regular basis, such as updating available product stock often. Additionally the SQUIZZ.com Connector is run as a webservice that can be configured to receive data securely from the SQUIZZ.com platform, allow data such as sales orders and purchase orders to received and pushed onto selected data sources and systems.

Connector Integration Benefits

Using the Connector software developers may be able to configure it to read and write data with their own software without having to develop an integration directly into the SQUIZZ.com platform's API. There are several advantages to this approach, which include:

  • No need to spend time developing an integration into the SQUIZZ.com platform to push up an organisation's data.
  • No need to spend time developing your own web service to accept secure requests from the SQUIZZ.com platform.
  • Ability to leverage the scheduler already built within the Connector for pushing up organisation data on a regular basis.
  • Ability to leverage the caching feature built within the Connector to reduce the amount of data that is uploaded to the platform.
  • Ability to see the data SQUIZZ.com has sent to the Connector before it tries to import data into your own system.
  • No need to support all kinds of organisation data in your software, since other data sources could be used by organisations to manage that other data.
  • Ability to leverage the query browser functionality within the Connector application that can help software support staff understand how the Connector is configured to read data from its data sources.

Connector Integration Requirements

In order for your software to use the Connector it will require you to do the following:

  • Install the Connector software on Microsoft Windows based machines within organisation computer networks. It will need to be installed on Windows machines that have DotNet 4.6.1 or higher installed.
  • Install and configure adaptor(s) within the Connector that control how the data can be read or written to your software.
  • Your software will need to support the kinds of data sources that the Connector can read or write to.
  • For the Connector to support receiving data pushed from the SQUIZZ.com platform it needs to be set up to accept incoming HTTPS requests, with connections secured by a TLS/SSL certificate. SQUIZZ.com can issue TLS certificates for free to organisations registered on the platform.

Setting Up Access To Use The Platform's API

Once an organisation has been registered by a person on the SQUIZZ.com platform, credentials must be set up to allow the platform's API to be be used to import data and modify details about an organisation on the platform. These credentials may need to be stored in the organisation's business systems or SQUIZZ.com Connector software to allow data to be imported into the platform and use its other features.

For the platform to allow software to use the platform's APIs for an organisation the following credentials must be initially when creating a session in the API:

  • Organisation ID
    Each organisation in the platform is issued a unique ID that allows the organisation to be identified.
     
  • API Org Key
    Each organisation in the platform is issued an API Key that allows software to access the API as that organisation. The API Org Key may by changed by administrators of the organisation.
     
  • API Org Password
    Each  organisation in the platform allows an administrator person of the organisation to create a unique password to allow software to access the API as that organisation. The API Org Password may be changed by administrators of the organisation. The password should be kept secret and be securely stored.

To learn how to set up API credentials for an organisation in the platform read the Connecting Business Systems document on how to do so.

Retrieving Organisational Data From The Platform

For each organisation registered within the SQUIZZ.com platform there is the ability for the platform to request and retrieve data from other connected organisations on the platform. An organisation can configure their own business system software, or use the SQUIZZ.com Connector software to make requests to retrieve organisational data from the platform's API. This can allow organisations to automate the data transfer from other customer and supplier organisations. The kinds of data that can be retrieved include product data, product pricing, product stock availability, and other data. Read the API's Retrieve Organisation Data endpoint document to learn the technical details on how the make requests to retrieve data through the API.

Receiving Organisational Data From The Platform

For each organisation registered within the platform there is the ability for the platform to push data out to connected business systems. The kinds of data being pushed from the platform can include sales orders, purchase orders, invoice payments, and other data.  Additionally the platform to make requests to get organisational data from connected business systems. This allows people connected to the organisation to retrieve data from a business system in real time. The kinds of data being requested could include invoices, sales orders, purchase orders, credits, payments, transactions, product stock availability and other data.

Using Web Services To Accept Outgoing Platform Requests

For the platform to be able to send requests to an organisation's business system, the business systems needs to support being run as a web service and receiving incoming HTTPS requests. If the business cannot be run as a web service then the SQUIZZ.com Connector software could be installed instead since it is run as a web service and can accept HTTPS requests. The Connector could then be configured to read or write data to the business system in many different ways, such as using ODBC database connections and SQL, reading and writing to spreadsheet CSV files, reading and writing to XML files, reading and writing to JSON files, or forwarding on requests to another web service internal to the organisation's local network.

Security Of Requests Sent From The Platform

The platform only supports sending out requests to connected business systems using HTTPS requests and Transport Layer Security (TLS) certificates, also known as SSL certificates. This ensures that the platform can securely transfer data across the public internet without any third parties being able to read the data. Within the SQUIZZ.com platform allows each organisation can create TLS certificates for free that are signed by SQUIZZ.com. These certificates can be used by business systems, the SQUIZZ.com Connector, or web server software such as Apache HTTP Server, Nginx or IIS to allow secure HTTPS connections to be made. If the platform's TLS certificates are installed on a computer then the platform's intermediate and root certificates will also need to be installed to allow secure connections to made from the platform's servers. To create a free certificate for an organisation in the platform read the Connecting Business Systems document. Alternatively a TLS certificate issued by a well known certificate authority such as Verisign, Geotrust, or Comodo could also be used to allow the platform to send secure requests to the associated web service connected to the organisation's business systems.

Structure Of Requests Sent From The Platform

In order for business systems to accept organisation data requests from the platform the system's web service needs to accept HTTPS requests that conform to the URL structure that the platform expects. This can be determined by viewing each of the outgoing endpoints listed on Platform API document.

Receiving Realtime Organisational Data Requests From The Platform

For each organisation registered within the platform there is the ability for the platform to make requests to obtain data from an organisation's business systems in real time. These requests are typically initiated by people in the platform connected to an organisation wanting to receive certain types of information such as invoices, sales orders, payments, credits, transactions, and other customer account data. By requesting this data in real time it ensures that people are always looking at the most up to date data, without needing to login to computer networks or business system software.

For the platform to be able to send requests to an organisation's business system, the business systems needs to support being run as a web service and receiving incoming HTTPS requests. If the business cannot be run as a web service then the SQUIZZ.com Connector software could be installed instead since it can be run as a web service and accept HTTPS requests. The Connector could then be configured to read data to the business system in many different ways, such as using ODBC database connections and SQL, reading from spreadsheet CSV files, reading from XML files, reading from JSON files, or forwarding on requests to another web service internal to the organisation's local network to obtain the data.

Structure Of Requests Sent From The Platform

In order for business systems to accept organisation data requests from the platform the system's web service needs to accept HTTPS requests that conform to the URL structure that the platform expects. This can be determined by viewing each of the outgoing endpoints listed on Platform API document.

Sending Notifications to SQUIZZ.com

The SQUIZZ.com platform supports external software pushing notifications to organisations and its selected people within the platform. This can allow different people connected to each organisation's notification categories to receive notifications from a wide variety of systems. In turn this can help centralise notifications, removing the reliance and complexity of an organisation managing emails, as well as leveraging the platform's apps to ensure people can receive notifications on different devices.

To allow external software to push in organisation notifications it needs to use the platform's API. The Create Organisation Notification API endpoint allows external software to push in notifications against a selected notification category, with a customised message, and a number of links or labels. To learn more about the platform's API read the Platform API document.