API STILL IN BETA

Plugboard REST API Developer Guide

Welcome to Plugboard API developer manual pages.

Introduction

Plugboard REST API reference

The REST reference has a complete set of documented endpoints with detailed information about model schema response codes and such.

It also provides tools to interact with the API directly from your browser window. By entering user credentials in the top bar you can then issue queries to the API through the "Try now!" button. It's a great way to get started with the Plugboard API.

For a complete set of documentation of the REST API, you can go to Swagger.

Support

If you have questions or feedback, please send an email to plugboard-api@sharespine.com. If you have a support request, it is important to supply verbose information about what you want to achieve together with requests and response information. Then our technicians have as much information as possible to reproduce and answer your ticket.

Terminology

In order to understand references to specific parts and concept of Plugboard and Plugboard API here are explanations of common words;

Create API credentials

In order to access Plugboard API for given tenant, you need to setup a system integration of type Plugboard API within My Plugboard administration area. Just follow the steps in order to do that;

  1. Login to My Plugboard (https://my.plugboard.io)
  2. Go to System integrations » Settings
  3. Click on Add system integration
  4. Choose Plugboard API as System
  5. Enter information of your liking in the other fields
  6. Click Save
  7. Now new widgets apear underneath
  8. Click on API Credentials
  9. Copy value of field X-ConnectionId

This value is to be used in the top bar of Swagger (togheter with the other three regular autonetication details).

Basics of the REST API

Protocol

The application protocol used is HTTP 1.1 as defined in RFC 2616. HTTP/2 (RFC 7540) is not supported at the moment. Neither is HTTP 1.0 or 0.9.

Clients MUST use SSL/TLS encryption (HTTPS) when accessing the API.

Clients MUST NOT ever use plain unencrypted http as this can result in authentication details being exposed.

HTTP supports a number of methods (commands) that are used by this API:

In the resource documentation below each resource will have a description of the allowed HTTP methods, what data is expected and what will be returned.

Authentication

Due to the usage of HTTP Basic Auth it is REQUIRED that SSL/TLS (HTTPS) be used! The server will reject accesses using HTTP only, however this may still cause client credentials to be exposed unencrypted!

Therefore it is vital that clients NEVER use plain HTTP!

Authentication is acieved using HTTP Basic Auth with a few special HTTP headers. These headers are used to specify which API configuration is to be used. The API MUST be configured before use.

Example:


    X-Tenant: tnt
    X-ConnectionId: 72b7568eb7e165e34e00c489542a0008
    Authorization: Basic dXNlcjp0ZXN0
    

Authorization headers content MUST be encoded as UTF-8 BEFORE base64 encoding.

Clients SHOULD use the "API Root" resource to test user credentials and get information about the API.

User-Agent

The User-Agent header is not required, however it is recommended that one is provided containing your application name and possibly some contact information. Sending this information will aid in debugging.

Clients sending the user-agent header MUST ensure it is correctly formatted according to RFC 2616.

If the client wishes to provide an app name and a contact email address it MUST be encoded as follows since @-chars are not allowed everywhere in User-Agent headers.

Example:


    User-Agent: my-app/1.0 (test@example.com)
    

Local and remote ID's

ID's are local or remote in relation to Plugboard.

A localId is the ID WITHIN plugboard, and NOT an ID probided by the client. API users cannot change or provide localIds, these are the sole responsibility of Plugboard. API clients MAY use localId's as references, since they are stable.

A remoteId is an id supplied by an external system, for example the API user. The ID's are supplied in two forms:

Example:


      {
        "remoteId":"banan",
        "remoteIdMap":{
          "5377568eb7e165e3b38af6eece4a0001":{
            "connectionId":"5377568eb7e165e3b38af6eece4a0001",
            "remoteId":"/product/26/variant/46"
          },
          "2cd2568eb7e165e3b38b30b3e8c40003":{
            "connectionId":"2cd2568eb7e165e3b38b30b3e8c40003",
            "remoteId":"flarfennugel"
          },
          "4485568eb7e165e3b1bcbb4cc57b0001":{
            "connectionId":"4485568eb7e165e3b1bcbb4cc57b0001",
            "remoteId":"banan"
          }
        }
      }
    

Errors

Errors are signalled in two ways:

Firstly, all errors are signalled using the appropriate HTTP error codes, as defined in RFC 2616.

The body of the error response is a JSON document with more details about the error. The document contains these fields:

Example - error might look like this:


      {
        "error": true,
        "time": "2015-09-03T13:42:47.880Z",
        "code": 401,
        "message": "Auth Failed"
      }
    

A list of all error codes can be downloaded here: errors.json

However keep in mind that the message texts listed are only the defaults. The messages are usually elaborated when generating the error to provide more information.

Basic types

Decimal values

Decimal values (like amounts etc.) MUST be encoded as an JSON string, not as a float/double. This is to avoid rounding and precision issues that can arise with floats:

Like so:


      {
        "amount": "4.2"
      }
    

and NOT like so:


      {
        "amount": 4.2
      }
    

See these for more details:

Date-Time (dateTime)

Date/time according to RFC 3339 format.

The server will always send the datetime using the UTC time zone with the 'Z' suffix.

The client SHOULD send the date/time in UTC with a Z suffix, however the client MAY use any format from RFC 3339.

Country code (ccode)

Country codes are defined in the ISO-3166-1 alpha-2 standard.

The server WILL ALWAYS send country codes as upper case, two-letter codes according to ISO-3166-1 alpha-2.

The client SHOULD send codes as upper case.

Language code (language3)

Language codes are defined in the ISO-639 standard.

The server will ALWAYS send languages as lower case, three-letter codes according to ISO-639-2.

The client MAY use ISO-639-1 two-letter codes. The client SHOULD send codes as lower case.

Currency code (currency)

Currency codes are defined in the ISO-4217 standard.

The server will ALWAYS send currencies as lower case, three-letter ALPHABETIC codes according to ISO-4217.

The client MAY send numeric ISO-4217 codes.

Money

Money is encoded as a decimal amount and a currency code in a "money" object.

Both currency and amount is required when sending a monetary value.

Example money object:


      {
        "currency":"SEK",
        "amount":"42.23"
      }
    

Language support

Language tagged fields are supported in two ways by this API so as to simplify client implementations.

Each API user has a default language configured. The api provides information about this in the "API Root" block.

The API client SHOULD support multiple languages, however the client MAY only support one language. For clients that do not support multiple languages the language used MUST be the default language configured for the user.

Each string field with language information is encoded twice in the JSON document. First the field is encoded as a normal string using the language configured for this user.

Example:


      {
        "title":"the title"
      }
    

Then a language tagged version of the field, with the suffix "_lang" whose value is a JSON document with language codes as keys and the localized text as value.

Example:


      {
        "title_lang": {
          "swe":"Titeln",
          "eng":"The title"
        }
      }
    

Example - This results in an object like this:


      {
        "title":"the title",
        "title_lang": {
          "swe":"Titeln",
          "eng":"The title"
        }
      }
    

This enables forward and backward compatibility as current fiends that are extended with language information in the future retain the semantics in the document and just get an additional field containing the language information. Older clients will then just ignore this new field and continue as before.

Removal of translations

Example - To remove a translation you need to send that value as "null":


      {
        "swe": null
      }
    

Just ignoring the translation will not remove or change it, allowing you to only send the translations you wish to change.

Custom data (customData)

Some objects allow custom data to be attached to them. The custom data is formatted as a dictionary, where the dictionary key is the custom data parameter and the value is an object containing information about the parameter.

Parameters are separated into modules, and modules themselves have different keys. If a custom key is needed the moduleId MUST begin with "x-" so as not to cause conflicts. The moduleId and key MUST NOT contain pipe ("|") characters.

The dictionary key used in the customData object is comprised of connectionId + "|" + moduleId + "|" + key.

The information provided in the object is:

The connectionId, moduleId and key parameters are case sensitive!

Example of custom data object:


      {
        "customData":{
          "5377568eb7e165e3b38af6eece4a0001|test|href":{
            "connectionId":"5377568eb7e165e3b38af6eece4a0001",
            "moduleId":"test",
            "key":"href",
            "type":"string",
            "value":"/pricelist/2"
          },
          "5377568eb7e165e3b38af6eece4a0001|test|href2":{
            "connectionId":"5377568eb7e165e3b38af6eece4a0001",
            "moduleId":"test",
            "key":"href2",
            "type":"string",
            "value":"/pricelist/42"
          }
        }
      }
    

Removal of keys

To remove keys from a custom data object you need to send the key value as null.

Example:


      {
        "5377568eb7e165e3b38af6eece4a0001|test|href" : null
      }
    

Just ignoring the key will not remove or change it, allowing you to only send the keys you wish to change.

Code examples

Test Connection Example


      curl -X GET --header 'Accept: application/json' --header 'X-Tenant: %tenant%' --header 'X-ConnectionId: %connectionId%' --header 'Authorization: %auth%' 'https://api.dev.plugboard.io/api/'
    

Replace %variable% with your unique id.

Output:


    {
      {
        "version":0,
        "connectionId":"000772bee96aae826403d0ed08590008",
        "permissions":[
          "attribute.edit",
          "attribute.view",
          "connection.edit",
          "connection.transfer.trigger",
          "connection.view",
          "contentgroup.edit",
          "contentgroup.view",
          "file.edit",
          "file.view",
          "fileimport.export",
          "fileimport.export.products",
          "fileimport.import",
          "fileimport.import.products",
          "log.view",
          "order.edit",
          "order.view",
          "pricelist.edit",
          "pricelist.view",
          "product.edit",
          "product.view",
          "productcategory.edit",
          "productcategory.view",
          "stats.view",
          "superuser",
          "user.create",
          "user.delete",
          "user.edit"
        ],
        "serverTime":"2018-06-27T12:49:27Z",
        "defaultLanguage":"swe",
        "defaultLanguage_iso":{
          "iso639-1":"sv",
          "iso639-3":"swe"
        },
        "connectionName":"API",
        "connectionType":"api",
        "connectionCustomData":{},
        "configuration":{}
      }
    }
    

Create Product Example


      curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Tenant: %tenant%' --header 'X-ConnectionId: %connectionId%' --header 'Authorization: %auth%' -d '{ \
      "remoteId": "aRemoteIdHere", \
      "vatRatePercent": "25" \
      }' 'https://api.dev.plugboard.io/api/product'
    

Replace %variable% with your unique id.

Output:


      {
        "href": "/api/product/0006d682a5ecee8f64227e481f4aa12c",
        "remoteId": "aRemoteIdHere",
        "localId": "0006d682a5ecee8f64227e481f4aa12c",
        "remoteIdMap": {
          "000772bee96aae826403d0ed08590008": {
            "connectionId": "000772bee96aae826403d0ed08590008",
            "remoteId": "aRemoteIdHere"
          }
        },
        "title": null,
        "title_lang": {},
        "title_lang2": {},
        "pictures": [],
        "created": "2018-06-27T13:03:41Z",
        "lastModified": "2018-06-27T13:03:41Z",
        "customData": {},
        "remoteUris": [],
        "isDeleted": false,
        "shortDescription": null,
        "shortDescription_lang": {},
        "shortDescription_lang2": {},
        "description": null,
        "description_lang": {},
        "description_lang2": {},
        "attributes": [],
        "alternateContent": {},
        "state": "hidden",
        "purchasable": false,
        "prices": [],
        "vatRatePercent": "25",
        "productCategories": [],
        "productVariantGroups": []
    }
    

Create Order Example


      curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Tenant: %tenant%' --header 'X-ConnectionId: %connectionId%' --header 'Authorization: %auth%' -d '{ \
        "customerType": "company", \
        "currency": "SEK", \
        "totalSumExclVat": { \
            "currency": "SEK", \
            "amount": "1.0" \
        }, \
        "totalVat": { \
            "currency": "SEK", \
            "amount": "1.0" \
        } \
     }' 'https://api.dev.plugboard.io/api/order/'
    

Replace %variable% with your unique id.

Output:


      {
        "href": "/api/order/0006d682a5ecee8f64227e481f4ab4b9",
        "remoteId": null,
        "localId": "0006d682a5ecee8f64227e481f4ab4b9",
        "remoteIdMap": {},
        "created": "2018-06-28T06:51:49Z",
        "lastModified": "2018-06-28T06:51:49Z",
        "customData": {},
        "customerType": "company",
        "currency": "SEK",
        "totalSumExclVat": {
          "currency": "SEK",
          "amount": "1.00"
        },
        "totalVat": {
          "currency": "SEK",
          "amount": "1.00"
        },
        "billingAddress": null,
        "shippingAddress": null,
        "orderRows": [],
        "source": {
          "connectionType": "api",
          "connectionId": "000772bee96aae826403d0ed08590008",
          "code": null,
          "connectionName": "API"
        },
        "shipments": []
      }