Get started in five steps

From nothing to your first working call against an iVendNext site. You need git, curl, jq and Python 3; your own editor and language do the rest. Everything here is a first look: the guide's chapter 2 and its recipes go further.

1. Request a sandbox site

A sandbox site is your own iVendNext shop, hosted by us and full of made-up demo data, where you build and test before you touch a customer's site. You receive an address in your name, an administrator login, and logins for the shop's people. You never receive the software or a server.

Request a sandbox and read what is on your site and what its limits are.

2. Get the kit

The guide, the recipes, the API description, the request collection, the tools and the samples are one repository:

git clone https://github.com/ivendnext-developers/partner-kit.git
cd partner-kit

The commands in step 3 and the samples are run from that folder.

3. Sign in, make your keys, and make the first call

Your first hour on the sandbox, from the recipe:

1. Sign in at your address as admin@demo-retail.example with the one-time password we sent. Choose your own password when the site asks.

2. Make your administrator's API key: Desk → your user → Settings → API Access → Generate Keys. The secret is shown once; keep it in your secret store.

3. Check your site with the kit's sandbox check (Python 3, plus bash, curl and jq):

   BASE=https://<your-site> KEY=<api key> SECRET=<api secret> python3 tools/sandbox_check/check.py
   

   It checks that the site answers, that your key signs in, that the POS apps are installed, the demo company and its three stores, the integration user, the extension points' record types, and the request collection's first three files. The last line says SANDBOX CHECK GREEN or SANDBOX CHECK RED and names what failed. If it is red, send us its output: it never prints your key or secret.

4. Give your connected app its key: open the integration user and press Generate Keys. Its role starts with one right, reading items; widen it to what your app needs, as recipes/integration_user.md and guide chapter 2 show. Use this key in your app, never the administrator's.

5. Sell on the till: sign in to the till as a cashier with the till ID, password and PIN we sent, open a day, sell, and close the day before you stop.

Then make the first call with the integration user's key. It starts with one right, reading items:

curl -s "https://<your-sandbox>/api/resource/Item?limit_page_length=5" \
  -H "Authorization: token <api key>:<api secret>"

You get back the first five items as JSON. A missing key answers 403; a wrong one 401. Chapter 2 goes on to widen the role to what your app needs, and the request collection in api/collection/ holds every call the samples make. Its first files run on any sandbox; the later ones book stock on test items a sandbox does not carry, so read them as examples.

4. Run a sample

Each sample is a small working example of one way in, with its tests. Its page says what it needs and how to run it. Pick the one nearest your project. On a sandbox, we install a manifest for you until self-service install ships.

5. Choose your way in and build

Chapter 3 is the order in which to try the ways in: configure first, then an outside app, a till key, a manifest, a sandboxed function, and last a request for a new extension point. Most needs stop at the first two. The recipes are one per way in. Before you quote a customer, place every need on the ladder with the project blueprint.

When something is missing or broken, tell us.