Supa Integration Reference for POS systems (2.0)

Webhooks to your POS system will be issues either through socket.io event or https endpoint.

Each command we issue has a corresponding args, and we expect from you a corresponding result

Each result returned from your POS system will be validated on our side, and we will display success or error for each operation in the Supa admin page.

Socket webhooks

For socket events:

• commands will be executed as events with a corresponding name.
• args object will be passed as a first and only event argument
• args of type void will not be passed at all
• POS system has to acknowledge the event (call a callback function with an appropriate response)

Your socket.io client should like in this example:

socketClient.on('getSections', (pagination, cb) => {
    const { page, limit } = pagination 

    const sections = [
        {
            externalId: 'section#1',
            name: 'VIP Section 1',
            description: 'Section for VIP Guests',
        },
    ];

    cb(sections.slice((page-1)*limit, page*limit));
});

For a full code reference for socket.io please take a look at Examples

HTTPS webhooks

For HTTPS webhooks we'll send a POST request with a corresponding JSON body. Example:

{ 
  command: 'getSections',  // getRestaurantAccount|getSections etc..
  args: { page: 1, limit: 15 } // or other arguments specific for other commands
}

Here in REQUEST BODY SCHEMA we're providing the models for the commands we'll issue through the webhooks.

• Each key (getRestaurantAccount|getSections etc.) corresponds to a commandName.
• Each args and result represent command details.

import { io as SocketIoClient } from 'socket.io-client';
import axios from 'axios';
import dayjs from 'dayjs';

const BASE_URL = 'https://pos.supa.pl'
const REFRESH_TOKEN = 'eyJhbGciOiJIU...CqmpNPDvfPN4mJpiFJp_s';

const getAccessToken = async (refreshToken) => {
    const { data } = await axios.post(`${BASE_URL}/auth/refresh?refreshToken=${refreshToken}`);

    return data.token;
}

const paginate = (array, { page, limit }) => {
    return array.slice((page - 1) * limit, page * limit)
}

const authToken = await getAccessToken(REFRESH_TOKEN);

const socketClient = new SocketIoClient(BASE_URL, {
    path: '/socket.io',
    query: { authToken },
    transports: ['websocket'],
    secure: true,
});

socketClient.on('connect', async () => {
    console.log('POS connected');

    // socketClient.emit('onOrderPrint', { externalOrderId: 'order1', externalTableId: 'table1' },  (response) => console.log(response, ' | onOrderPrint response'));
    // socketClient.emit('PING', (response) => console.log(response, ' | PING response'));
    await new Promise(resolve => setTimeout(resolve, 1000));
    socketClient.emit('onCashRegisterStart');
    socketClient.emit('onOrderUpsert', { externalOrderId: 'order#1' });
});

socketClient.on('disconnect', () => {
    console.log('POS disconnected');
});

socketClient.on('connect_error', (error) => {
    if (socketClient.active) {
        // temporary failure, the socket will automatically try to reconnect
    } else {
        // the connection was denied by the server
        // in that case, `socket.connect()` must be manually called in order to reconnect
        console.log(error.message);
    }
});

socketClient.on('getRestaurantAccount', (cb) => {
    console.log('getRestaurantAccount');

    const account = {
        organisationId: 'orgId2',
        organisationName: 'Test Organisation',
        cloudId: '#001',
        tariff: 'Basic',
    };

    cb(account);
});

socketClient.on('getSections', (pagination, cb) => {
    console.log('getSections', pagination);

    const sections = [
        {
            externalId: 'section#1',
            name: 'VIP Section 1',
            description: 'Section for VIP Guests',
        },
    ];

    cb(paginate(sections, pagination));
});

socketClient.on('getWaiters', (pagination, cb) => {
    console.log('getWaiters', pagination);

    const waiters = [
        {
            'externalId': 'waiterExternalId#1',
            'name': 'Daniella Waiter',
            'phone': '+48835000000',
            'requiresPin': false
        }
    ];

    cb(paginate(waiters, pagination));
});

socketClient.on('getTables', (pagination, cb) => {
    console.log('getTables', pagination);

    const tables = [
        {
            externalId: 'table1#1',
            externalSectionId: 'section#1',
            name: 'Table 1',
            number: 1,
            description: 'VIP table',
        },
    ];

    cb(paginate(tables, pagination));
});

socketClient.on('getPaymentTypes', (pagination, cb) => {
    console.log('getPaymentTypes', pagination);

    const paymentTypes = [
        {
            externalId: 'paymentType#1',
            name: 'Supa',
            kind: 'card',
        },
    ];

    cb(paginate(paymentTypes, pagination));
});

socketClient.on('getOrderById', (params, cb) => {
    console.log('getOrderById', params);

    const ordersById = {
        'order#1': {
            status: 'opened',
            externalId: 'order#1',
            currency: 'PLN',
            sum: 12300,
            paidSum: 12300,
            fullSum: 12500,
            guestsCount: 2,

            openedAt: dayjs().subtract(2, 'hours').toISOString(),
            billedAt: dayjs().subtract(15, 'minutes').toISOString(),
            closedAt: null,

            guests: [
                {
                    externalId: 'your-guest-id-1',
                    name: 'Guest 1',
                    raw: {},
                },
                {
                    externalId: 'your-guest-id-2',
                    name: 'Guest 2',
                    raw: {},
                },
            ],

            items: [
                {
                    externalId: 'jsakjdsakj',
                    price: 5000,
                    name: 'Hamburger of 1st guest',
                    amount: 2,
                    cost: 10000,
                    comment: 'extra spicy',
                    guestExternalId: 'your-guest-id-1',
                    product: {
                        externalId: 'product-id#1',
                        price: 5000,
                        name: 'Hamburger of 1st guest',
                    },
                    modifiers: [
                        {
                            externalId: 'modifier#1',
                            productExternalId: 'modifier-type-id#1',
                            name: 'Additional Gouda',
                            amount: 2,
                            sum: 2000,
                        }
                    ],
                    raw: {},
                },
                {
                    externalId: 'jsakjdsakjвфіо213',
                    price: 5300,
                    name: 'Salad of 2nd guest',
                    amount: 2.5,
                    cost: 13250,
                    guestExternalId: 'your-guest-id-2',
                    product: {
                        externalId: 'product-id#2',
                        price: 5300,
                        name: 'Salad of 2nd guest',
                    },
                    raw: {},
                },
            ],

            payments: [
                {
                    externalId: 'payment-id',
                    sum: 12300,
                    status: 'processed',
                    currency: 'PLN',
                    restaurantPaymentType: { externalId: 'paymentType#1' },
                    raw: {},
                },
            ],
            tables: [{ externalId: 'table1#1' }],
            waiters: [{ externalId: 'waiterExternalId#1' }],

            raw: {}
        }
    }

    cb(ordersById[params.orderId]);
});

socketClient.on('billAndLockOrder', async (data, cb) => {
    console.log('billAndLockOrder', data);
    await new Promise(resolve => setTimeout(resolve, 1000));

    cb();
});

socketClient.on('payOrder', async (data, cb) => {
    console.log('payOrder', data);
    await new Promise(resolve => setTimeout(resolve, 1000));

    cb();
});

Expected results

Example code, when launched, is expected to produce the following results visible in the Supa admin page:

Restaurant Account

Staff & tips page

Payment Types

Tables & QRs page

Orders Page

REQUIRED

This one should be sent as soon as the order has been created/updated or deleted. This will place a corresponding UpsertEvent in the Supa’s internal processing queue - and it will dispatch a corresponding getOrderById event as soon as possible

Before order bill is printed, you may call this endpoint and receive a link for a QR payment.

REQUIRED

This event will trigger the synchronisation process between Supa & your POS system. Supa will shortly ask for tables, waiters, sections and other entities to get the latest updates.

Every PING event will receive its “PONG” response - a healthcheck for your system to make sure the integration is up and running.