Quick start

Introduction

In this guide we will go through the simple process of establishing an API connection to a Tenant and do a couple of queries to the Order endpoints. The guide will take you step by step through the process and takes about 15 minutes to complete and will touch upon some important concepts along the way.

Now, start by logging into your Tenant UI to get started. You should have received account information to environments when you got your developer status.

Step 1: Create a new API User

First step in the preparations is to create a new API User.

Note

You should always create a dedicated API user for your integration as best practice. Then you can set custom permissions on it, and it is easier to block specific integration if needed. If you use shared accounts it will probably end up in problems further down the road. Don’t do that.

Navigate to Users from the left side menu.
Click the + button to create new a new User.
Fill in Username and Password (fields which we will use as part of API request in a moment).
Also, with other basic information such as Full name and Email. Information that is good to set in order to distinguish users from each other on the Tenant.
An important field is the Language field and the concept of language can be read in-depth in dedicated Language & translations chapter.
Then you can assign the user Permissions and be sure to only give permissions needed by the API users to keep the access level on a need basis.
Click the SAVE button to save the user and its settings.

Step 2: Create a new API Connection

First step in the preparations is to create a new API Connection.

Navigate to Connections from the left side menu.
Click on the NEW CONNECTION button.
Assign your Connection a name.
Click the Authentication on the left side pane.
Read Tenant (X-Tenant) and Connection ID (X-ConnectionId) fields which we will use as part of API request in a moment.
Click SAVE button.
Now Enable the newly created API Connection.

Step 3: Test connection

Now you can use the credentials from the previous two sections in order to test your API Connection.

By calling the root endpoint /api/ you can test the connection as well as get basic information about your API user and its permissions. Section Authentication contains more information about the auth.

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.plugboard.io/api/

Note

It is highly recommended to set a User Agent for all calls to the API. Sending this information will aid in troubleshooting and debugging in the future.

Response

If the credentials are correct you will receive a HTTP 200 OK response along with a response body.

{
  "version": 8,
  "connectionId": "000682324c27d8b488dbf73da68a002a",
  "permissions": [
    "order.edit",
    "order.settings",
    "order.view",
    "payment.configure",
    "payment.edit",
    "payment.view",
    "paymentmethod.edit",
    "paymentmethod.view",
    "stats.view",
    "zreport.edit",
    "zreport.view"
  ],
  "serverTime": "2022-02-10T07:37:33Z",
  "defaultLanguage": "swe",
  "defaultLanguage_iso": {
    "iso639-1": "sv",
    "iso639-3": "swe"
  },
  "connectionName": "API",
  "connectionType": "api",
  "connectionCustomData": {},
  "configuration": {}
}

The payload will contain information key information such as;

version: The version of the API. See Change policy and Changelog for more information on versioning.
connectionId: The unique id of the API connection you use. See Connectors and Connections for more info about these concepts.
permissions: The specific permissions for the user accessing the API Connection. See Users and Permissions for more information about these concepts.
serverTime: The time of the server as reference.
defaultLanguage: The language set on the API User (remember the Language step in the preparation step above).
defaultLanguage_iso: The language set on the API User in different ISO-formats, read more about this in the Language & translations chapter.
connectionName: The name of your API Connection (remember the Naming step in the preparation step above).
connectionType: The unique Connector type of the API Connection.
connectionCustomData: Possible custom data stored on the Connections. Read more in the dedicated Custom data chapter.

However, if the credentials are not correct you will receive an HTTP 401 Forbidden instead, also with a response body containing an Error structure.

{
  "error": true,
  "time": "2022-02-10T15:45:18Z",
  "code": 2000,
  "subCode": null,
  "message": "Unauthorized",
  "defaultMessage": "Unauthorized",
  "helpText": null,
  "field": null,
  "fieldValue": null,
  "class": "theo.api.error.ApiErrors$AuthFailed",
  "errorCategory": "PermissionDenied"
}

Step 4: Create order

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.plugboard.io/api/order
    -X POST \
    -d \
    '{
      "orderTime": "2022-01-09T11:47:46Z",
      "remoteOrderNo": "100088896",
      "orderType": "sale",
      "orderStatus": "processing",
      "shippingStatus": "not-shipped",
      "paymentStatus": "fully-paid",
      "customerNo": "C9000",
      "customerType": "company",
      "organizationNo": "556642-8768",
      "vatNo": "SE556642876801",
      "currency": "SEK",
      "customerReference": "Sven Svensson",
      "totalSumExclTax": {
          "currency": "SEK",
          "amount": "100.00",
          "decimals": 2
      },
      "totalTax": {
          "currency": "SEK",
          "amount": "25.00",
          "decimals": 2
      },
      "shippingAddress": {
          "company": "Sharespine AB",
          "street": "Kungsgatan 38",
          "zipCode": "411 19",
          "city": "Göteborg",
          "country": "SE",
          "phoneNumbers": [
              {
                  "type": "landline",
                  "number": "+46317043800"
              }
          ],
          "emailAddress": "info@sharespine.com"
      },
      "billingAddress": {
          "company": "Sharespine AB",
          "street": "Kungsgatan 38",
          "zipCode": "411 19",
          "city": "Göteborg",
          "country": "SE",
          "phoneNumbers": [
              {
                  "type": "landline",
                  "number": "+46317043800"
              }
          ],
          "emailAddress": "info@sharespine.com"
      },
      "orderRows": [
          {
              "rowType":"product",
              "sku": "ABC123",
              "title": "Test product",
              "qty": "10",
              "vatRatePercent": "25",
              "pricePerUnitExclTax": {
                  "currency": "SEK",
                  "amount": "10.00",
                  "decimals": 2
              },
              "perUnitTaxes": [
                  {
                      "taxType": "vat",
                      "percentage": "25.0",
                      "taxableAmount": {
                          "currency": "SEK",
                          "amount": "10.00",
                          "decimals": 2
                      },
                      "tax": {
                          "currency": "SEK",
                          "amount": "2.50",
                          "decimals": 2
                      }
                  }
              ]
          }
      ]
    }'

Response

Full response omitted for brevity.

{
  "localId": "000162cd052333b5508514110ddf0023",
  "orderStatus": "processing",
  ...
}

If successfully you will receive an HTTP 201 Created response along with a body containing the current state of the newly created order.

Now we can use the localId in the response which identifies this single order by unique id. Read more about this concept in the dedicated Id’s and references chapter.

Step 5: Read order

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.plugboard.io/api/order/000162cd052333b5508514110ddf0023

Response

Full response omitted for brevity.

{
  "localId": "000162cd052333b5508514110ddf0023",
  "orderStatus": "processing",
  ...
}

If successfully you will receive an HTTP 200 OK response along with a body containing the current state of the newly created order.

Step 6: Update order

Request

$ curl     -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Tenant: <TENANT CODE>' \
    -H 'X-ConnectionId: <CONNECTION ID>' \
    https://api.plugboard.io/api/order/000162cd052333b5508514110ddf0023 \
    -X PUT \
    -d \
    '{
        "orderStatus": "completed"
    }'

Response

Full response omitted for brevity.

{
  "localId": "000162cd052333b5508514110ddf0023",
  "orderStatus": "completed",
  ...
}

If successfully you will receive an HTTP 200 OK response along with a body containing the current state of the newly created order.

Wrap up

In this guide we did all steps to establish access to the API including the preparation of creating new User and Connection. This was a very simple example to showcase some fundamental building blocks. If you want to learn more the best place to continue is the Connect & communicate chapters containing important know-how about the Integration Platform.

Next: Become a partner