Getting Started

POS API expects a custom plugin as a javascript file, that exports the default function. POS loads the file at runtime, imports the default function, and then calls the function with the appropriate configuration and API objects.

Before proceeding, review the following high-level overview of the plugin process:

The Plugin

Create a javascript file that exports the default method.

//plugin.js

export default (options) => {
   //an object containing custom configuration data such as { ip: '127.0.0.1', port: 9000 }
   const configuration = options.configuration; 
   
   //an object, containing references to available plug-in api methods and events
   const api = options.api; 

   //Use the configuration object to setup plugin
   let name;
   let ip;
   if (configuration) {
      name = configuration.name;
      ip = configuration.ip;
   }

   const plugin = new MyPlugin(name, ip);

   //Use the API object to subscribe to POS events and call associated public features
   const subscription = options.api.events.order.onOrderFinalized((order) => {
      //procedure to finalize order
   });
};

Configuration

Review the following procedure if the plugin requires configuration data, such as an integrated device ip address, or credentials for external resources.

Create a README file describing the required configuration data.
Adapt the plugin to extract the required data from the configuration object that is provided in the options and passed to the exported default function.

POS APIs

The POS APIs allows custom plugins to communicate with POS or other external resources. The API is passed to the plugin during initialization—see the options, passed to exported default function.

The POS provides the following APIs to the plugin:

POS API	Description
api.fs	A set of methods to read and write files in local file system
api.http	For http requests
api.tcpSocket	For TCP sockets
api.usb	For USB connected devices
api.uiControls	A set of UI controls to communicate with user inputs
api.terminal	For current POS terminal configuration
api.print	For printing functionality.
api.order	An API for an OrderObject
api.override	For overriding some of the POS functionality
api.events	Provides subscription capability to POS events
api.events.order	Included with events, access to a set of order events
api.events.application	Included with events, access to a set of general application events
api.events.eod	Included with events, access to a set of POS events related to functionality of closing the current business date—known as End-of-Day (EOD).

Warning

A plugin may only use the API provided by POS—this avoids the possibility of DOM manipulation or direct communication with external resources that may occur by using WebAPI directly.

Deployment

For additional information, review Download and Import Plugin on POS.

Before deploying the plugin to the cloud:

Build and bundle the plugin code into a single javascript file.
Digitally sign the generated javascript file with a public key—reach out to the POS development team for instructions.
Create a manifest.json file which provides plugin metadata—POS uses this file during plugin initialization.
- For more information, see Manifest Structure.
Deploy the signed plugin javascript file and the manifest.json to cloud storage.

Manifest Structure

Information for manifest.json file.

Field	Type	Description
name	string	Plugin name
version	string	Plugin version
main	string	Name of the main plugin file (entry point)
files	string[]	A list, containing all file names provided with the plugin. POS API expects only one, `main` file.

Manifest Example

Example:

{
   "name": "My first plugin",
   "version": "1.0.0",
   "main": "index.js",
   "files": [
      "index.js"
   ]
}